如何建立一个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运行命令行工具。把命令放到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，查看文档导出。