综合开发

如何创建一个dart package

微信扫一扫,分享到朋友圈

如何创建一个dart package

推荐一个作者的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,查看文档导出。

单例模式的 8 种写法,整理非常全!

上一篇

[热]全网最全的官方1+x证书web前端初级中级高级全课程分析及大纲

下一篇

你也可能喜欢

评论已经被关闭。

插入图片

热门栏目

如何创建一个dart package

长按储存图像,分享给朋友