Contents

Creating packages

Dart生态系统使用软件包来共享软件,例如库和工具. 该页面告诉您如何创建一个程序包,重点介绍最常见的程序包程序包 .

What makes a library package

下图显示了最简单的库包的布局:

root directory contains pubspec.yaml and lib/file.dart

一个库的最低要求是:

pubspec file

库的pubspec.yaml文件与应用程序包的文件相同-没有特殊的指示以表明该包是库.

lib directory

如您所料,库代码位于lib目录下,并且对其他软件包是公共的. 您可以根据需要在lib下创建任何层次结构. 按照约定,实现代码位于lib / src下 . lib / src下的代码被认为是私有的; 其他软件包永远不需要导入src/... 要公开lib / src下的API,可以从直接在lib下的文件中导出lib / src文件.

Organizing a library package

创建小型的单个库(称为迷你库)时,库包最容易维护,扩展和测试. 在大多数情况下,每个类都应位于自己的微型库中,除非您遇到两个类紧密耦合的情况.

直接在lib,lib / <package-name> .dart下创建一个"主"库文件,该文件导出所有公共API. 这使用户可以通过导入单个文件来获得库的所有功能.

lib目录可能还包括其他可导入的非src库. 例如,也许您的主库跨平台工作,但是您创建了依赖dart:io或dart:html的单独的库. 某些软件包具有单独的库,但如果没有主库,则应使用前缀导入.

让我们看一下实际库包的结构:架子. 货架软件包提供了一种使用Dart创建Web服务器的简便方法,并以Dart库软件包常用的结构进行布局:

shelf root directory contains example, lib, test, and tool subdirectories

直接在lib下,主库文件shelf.dart从lib / src导出几个文件:

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/handlers/logger.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/pipeline.dart';
export 'src/request.dart';
export 'src/response.dart';
export 'src/server.dart';
export 'src/server_handler.dart';

书架包还包含一个小型库:shelf_io. 该适配器处理dart:io的HttpRequest对象.

Importing library files

从另一个包中导入库文件时,请使用package:指令指定该文件的URI.

import 'package:utilities/utilities.dart';

从自己的包中导入库文件时,如果两个文件都在lib内,或者两个文件都在lib之外,请使用相对路径. 使用package:当导入的文件在lib中并且导入器在外部时.

下图显示了如何从lib和web导入lib/foo/a.dart .

lib/bar/b.dart uses a relative import; web/main.dart uses a package import

Conditionally importing and exporting library files

如果您的库支持多个平台,则可能需要有条件地导入或导出库文件. 一个常见的用例是同时支持Web和本机平台的库.

要有条件地导入或导出,您需要检查dart:*库的存在. 这是一个条件导出代码示例,该代码检查dart:iodart:html

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation
lib/hw_mp.dart

该代码的作用如下:

  • 在可以使用dart:io的应用程序(例如,命令行应用程序)中,导出src/hw_io.dart .
  • 在可以使用dart:html的应用程序(网络应用程序)中,导出src/hw_html.dart .
  • 否则,导出src/hw_none.dart .

要有条件地导入文件,请使用与上面相同的代码,但是将export更改为import .

所有有条件导出的库都必须实现相同的API. 例如,这是dart:io实现:

import 'dart:io';

void alarm([String text]) {
  stderr.writeln(text ?? message);
}

String get message => 'Hello World from the VM!';
lib/src/hw_io.dart

这是默认的实现,它是一个引发UnsupportedErrors的存根:

void alarm([String text]) => throw UnsupportedError('hw_none alarm');

String get message => throw UnsupportedError('hw_none message');
lib/src/hw_none.dart

在任何平台上,您都可以导入具有条件导出代码的库:

import 'package:hw_mp/hw_mp.dart';

void main() {
  print(message);
}

Providing additional files

设计良好的库包易于测试. 我们建议您使用测试包编写测试,并将测试代码放在包顶部的test目录中.

如果您创建任何供公众使用的命令行工具,请将其放置在bin目录中,该目录是公共的. 使用pub global activate从命令行运行工具的功能. 在pubspec的executables部分列出该工具后,用户无需调用pub global run即可直接运行它.

如果提供一个有关如何使用库的示例,将很有帮助. 这进入软件包顶部的example目录.

您在开发过程中创建的任何非公共使用的工具或可执行文件都进入tool目录.

如果将库发布到pub.dev站点,则需要其他文件,例如README.mdCHANGELOG.md ,在发布程序包中进行了描述. 有关如何组织程序包目录的更多信息,请参见pub程序包布局约定 .

Documenting a library

您可以使用dartdoc工具为您的库生成API文档. Dartdoc解析源以查找文档注释 ,该注释使用///语法:

/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

有关生成的文档的示例,请参阅架子文档.

Distributing an open source library

如果您的库是开源的,我们建议在pub.dev站点上共享它. 要发布或更新库,请使用pub publish ,它会上传您的软件包并创建或更新其页面. 例如,请参阅架子包装页面. 有关如何准备要发布的软件包的详细信息,请参见发布软件包 .

pub.dev站点不仅托管您的软件包,还生成并托管您的软件包的API参考文档. 软件包的" 关于"框中提供了最新生成的文档的链接. 例如,请参阅扩展包的API文档. 指向先前版本文档的链接位于软件包页面的" 版本"标签中.

为确保您的包的API文档在pub.dev网站上看起来不错,请按照以下步骤操作:

  • 在发布软件包之前,请运行dartdoc工具,以确保您的文档生成成功并且外观符合预期.
  • 发布软件包后,请检查" 版本"选项卡,以确保文档已成功生成.
  • 如果文档根本没有生成,请在" 版本"选项卡中单击" 失败 "以查看dartdoc输出.

Resources

使用以下资源来了解有关库软件包的更多信息:

by  ICOPY.SITE