推荐一个作者的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/
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
运行命令行工具。把命令放到pubspec
的executables
字段域下面,这样允许用户直接运行,而不需要调用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,查看文档导出。