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之外时,可以使用相对路径导入库. 但是,在导入到达lib内部或外部的文件时,必须使用package: :. 如有疑问,请使用package:指令; 它适用于所有情况.

下图显示了如何从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目录.

Other files that are required if you publish your library to the pub.dev site, such as a README and a CHANGELOG, are described in Publishing a package. For more information on how to organize a package directory, see the pub package layout conventions.

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