如何创建一个dart package

farmerz

推荐一个作者的package,一个方便flutter初学者使用编写计算器的库。
点击获取

创建packages

dart生态使用pakcage来分享ku或者工具。下面我们来看一下最常见的库的package的创建。

库的组成

下面的示意图展示了最简单的库结构:

示意图

库的最基本组成:

pubspec文件

dart应用也是使用这个文件,这个文件中没有特殊的标识符说明当前的项目是package还是app。

lib 文件夹

如我们所想,库代码放在lib文件夹中。给文件夹是公开可访问的。你可以重建一个子目录,通常来说,实现代码放在lib/src文件夹下。src文件夹应该认为是私有的。其他package不应该直接从src文件夹中import。你可以export src文件夹中的文件。

提示 当声明了`library`指令,会依据路径和文件名生成唯一的tag。因此我们一般应该忽略这个声明,除非你打算生成library-level等级的文档。

构建一个library package

独立的小的库组成的library pacage是最容易维护,扩展,测试的。
大多数的例子,每个类应该是个小的library,除非某些类之间有紧密的关系。

提示你也许听说过`part`指令,它允许你把ku分写道几个小的dart文件中。在创建小的ku时,建议不要使用part指令。

在lib文件夹下创建一个主要的库文件,形式如lib/<package-name>.dart,用来导出所有的公共接口。这样用户就可以通过一个文件导入所有的功能。

lib文件夹也许包括其他的接口文件,像是一些no-src的,例如也许你的库是跨平台的,你创建了分开的入口。比如依赖dart:io或者dart:html的。一些库做了import前缀,用来指明不同的导入需求(当主库不能适应使用环境时)。

我来看下现实中的库的组织结构。shelf库提供了创建webserver的简单方法,它提供了常用的dart package结构。

如图

主库shelf.dart的到处内容。

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库也包含一个小的库:shelf_io。这个用来处理来自dart:io的HttpRequest对象。

web app提示:为了编译时的性能,建议把是下代码放到`lib/src`文件夹下,也要避免使用`package:package_name/src..`这类导入方法。

import 库文件

当导入一个库文件,你可以使用package:指令加上文件uri路径。

import 'package:utilities/utilities.dart';

当文件都在lib文件夹中/外时可以使用相对路径导入。
然而又是你必须使用package:引入一个文件,不管它始在lib内还是外。如果有疑问就用package:,它都能胜任。

下面视图,说明引入lib/foo/a.dart的不同方式。

示意图

提示:图中使用的`import'../foo/a/dart';可以使用`import 'package:my_package/foo/a.dart`。

条件引入

如果你的库支持多个平台,那么你可能需要考虑按条件引入和导出库文件。通常的情况是支持web和本地平台。

想要有条件的引入和导出,你需要检查dart:*的存在。整个例子根据不同的存在导出文件。

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

代码做的事:

  • 一个应用能够使dart:io,导出src/hw_io.dart.
  • 一个应用使用dart:html,导出src/hw_html.dart.
  • 其他的导出dart:hw_one.dart

条件导出和上面的代码基本一样,但是使用的是import指令。

提示 条件导出和引入只是检查库是否在当前平台可用,而不是实际导入或使用。

所有的条件导出不行hi是新建一样的api,例如这里的dart:io实现。

import 'dart:io';

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

String get message => 'Hello World from the VM!';

这里有一个默认实现,这是一部分抛出错误的代码。

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

String get message => throw UnsupportedError('hw_none message');

在任何平台你都可引入使用了条件导出的库。

import 'package:hw_mp/hw_mp.dart';

void main() {
  print(message);
}

添加其他的文件

一个设计良好的package是易测试的。我们建议你使用test package编写测试文件。把测试代码放到test文件夹(顶级目录)中。

如果你编写了命令行工具想要别人使用,那么把它们放到bin文件夹中,这是惯例。实现使用pub global active运行命令行工具。把命令放到pubspecexecutables字段域下面,这样允许用户直接运行,而不需要调用pub global run,来运行。

在你的项目里添加example顶级文件夹,对于怎么使用你的库是有用的。

开发时使用的工具或者命令行文件而不是最终给用户使用的,放到tool文件夹中。

发布到pub.dev网址你需要添加的其他文件包括README.md以及CHANGELOG.md。其他内容可以查看pub package layout conventions

文档

你可以使用dartdoc工具生成文档。文档使用文档注释——///来解析。

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

可以通过shelf document来查看生成的文档示例。

提示 想要生成时包含任何ligrary-level的文档,你需要声明library指令。

发布开源库

如果你的库是开源的,我们建议把它分享到pub.dev网站。发布和更新你的代码使用pub publish命令。它会上传你的代码然后生成或者更新页面。查看示例shelf package。或者查看发布这一张,了解如何准备和发布你的package。

pub.dev网站不只是保存你的package,而且会生成和host你的package api文档。最新生成的文档会在package的About tab。更多示例查看shelf package的API docs。更多的版本查看pacage页面的Version tab。

为了使你的package文档看起来不错,跟随下面做。

  • 发布前,运行dartdoc工具来生成文档。
  • 发布后检查Version tab,保证成功生成。
  • 如果文档没有生成,查看Version tab,查看文档导出。
阅读 598

前端这两年(2016~)
近几年来前端的变化记录

可可西里,可可西里,我只是想去看一看。

1.2k 声望
53 粉丝
0 条评论

可可西里,可可西里,我只是想去看一看。

1.2k 声望
53 粉丝
宣传栏