如何使用 package

Dart 生态系统使用 来管理共享软件,比如:库和工具。我们使用 Pub 包管理工具 来获取 Dart 包。在 Pub 上,可以找到公开可用的包。或者从本地文件系统或其他的位置,比如 Git 仓库,加载可用的包。无论包是从什么途径加载的, Pub 都会进行版本依赖管理,从而帮助我们获得版本兼容的软件包以及 SDK 。

大多数 Dart-savvy IDEs 都支持 Pub 的使用,包括包的创建,下载,更新和发布。同样上述功能也可以在命令行上通过 pub 来操作。或者可以在命令行上使用pub。

Dart 包目录中至少包含一个 pubspec 文件。pubspec 文件记录一些关于包的元数据。此外,包还包含其他依赖项(在 pubspec 中列出),Dart 库,应用,资源,测试,图片,以及示例。

通过以下步骤,引用使用包:

  • 创建一个 pubspec (一个名为 pubspec.yaml 文件,文件列出依赖的包以及包含的其他元数据,比如当前包的版本)。

  • 使用 Pub 获取当前所依赖的包。

  • 如果当前 Dart 代码依赖包中的某个库,导入(import)该库。

创建 pubspec

pubspec 是一个名为 pubspec.yaml 的文件,文件位于应用的根路径。最简单的 pubspec 只需要列出包名:

  1. name: my_app

下面是一个 pubspec 的示例,示例中声明依赖了在 Pub 站点上托管的两个包( jsintl ):

  1. name: my_app
  2. dependencies:
  3. js: ^0.6.0
  4. intl: ^0.15.8

有关创建 pubspec 的详细内容,请参阅 pubspec 文档以及使用包的相关文档。

获取包

项目中一旦拥有了 pubspec 文件,就可以在项目根目录中执行pub get 命令:

  1. $ cd <path-to-my_app>
  2. $ pub get

上面的操作即获取依赖

pub get 命令确定当前应用所依赖的包,并将它们保存到中央系统缓存(central system cache)中。如果当前应用依赖了一个公开包, Pub 会从 Pub 站点 该包。对于一个 Git 依赖, Pub 会 Clone 该 Git 仓库。同样包括包的相关依赖也会被下载。例如,如果 js 包依赖 test 包, pub 会同时获取 js 包和 test 包。

Pub 会创建一个.packages 文件(位于应用程序的根路目录下),该文件将应用程序所依赖的每个包名相应的映射到系统缓存中的包。

从包中导入库

使用 package: 前缀,导入包中的库:

  1. import 'package:js/js.dart' as js;
  2. import 'package:intl/intl.dart';

Dart 运行时会抓取 package: 之后的内容,并在应用程序的 .packages 文件中查找它。

也可以使用此方式从自己的包中导入库。思考下面的 pubspec 文件,该文件声明了对 transmogrify 包(虚构的包名)的依赖:

  1. name: my_app
  2. dependencies:
  3. transmogrify:

Let’s say that your package is laid out as follows:

  1. transmogrify/
  2. lib/
  3. transmogrify.dart
  4. parser.dart
  5. test/
  6. parser/
  7. parser_test.dart

parser_test 文件可以通过 import parser.dart 的方式来导入:

  1. import '../../lib/parser.dart';

但是相对路径是脆弱的。如果 parser_test.dart 在包目录中上下移动,那么该路径就会被破坏。我们应该通过下面的方式来代替:

  1. import 'package:transmogrify/parser.dart';

这样,无论 parser.dart 文件在哪个位置,总可以被导入。

升级依赖

第一次获取依赖时,Pub 会下载依赖及其兼容的最新版本。然后通过创建 lockfile 锁定依赖,以始终使用这个版本。Pub 会在 pubspec 旁创建并存储一个名为 pubspec.lock 文件。它列出了使用的每个依赖包的指定版本(当前包或传递包的版本)。

如果包是一个应用程序包,那么应该将此文件加入到 源文件管理。这样,在应用上开发的每个人都能够使用所有相同版本的包。同样加入到 lockfile 可以保证部署的应用使用的是同一版本的代码。

如果已经准备更新依赖到最新版本,使用命令 pub upgrade

  1. $ pub upgrade

上面的命令用于重新生成 lockfile 文件,并使用最新可用版本的依赖包。如果仅升级某个依赖,可以在命令中指定需要升级的包:

  1. $ pub upgrade transmogrify

上面的命令升级 transmogrify 到最新版本,但维持其它包不变。

更多内容

以下链接的页面是关于包及 Pub 包管理的更多内容。

如何使用

参考

Pub 命令

pub 工具提供一下命令:

有关所有 pub 命令的概述,参见 pub 工具文档

故障排除

Pub 故障排除 提供使用中可能遇到问题的解决方法。