目录

Contents

如何使用 package

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

The Dart ecosystem uses packages to manage shared software such as libraries and tools. To get Dart packages, you use the pub package manager. You can find publicly available packages on the pub.dev site, or you can load packages from the local file system or elsewhere, such as Git repositories. Wherever your packages come from, pub manages version dependencies, helping you get package versions that work with each other and with your SDK version.

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

Most Dart-savvy IDEs offer support for using pub that includes creating, downloading, updating, and publishing packages. Or you can use pub on the command line.

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

At a minimum, a Dart package is a directory containing a pubspec file. The pubspec contains some metadata about the package. Additionally, a package can contain dependencies (listed in the pubspec), Dart libraries, apps, resources, tests, images, and examples.

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

To use a package, do the following:

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

    Create a pubspec (a file named pubspec.yaml that lists package dependencies and includes other metadata, such as a version number).

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

    Use pub to get your package’s dependencies.

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

    If your Dart code depends on a library in the package, import the library.

创建 pubspec

Creating a pubspec

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

The pubspec is a file named pubspec.yaml that’s in the top directory of your application. The simplest possible pubspec lists only the package name:

name: my_app

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

Here is an example of a pubspec that declares dependencies on two packages (js and intl) that are hosted on the pub.dev site:

name: my_app
dependencies:
  js: ^0.6.0
  intl: ^0.15.8

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

For details on creating a pubspec, see the pubspec documentation and the documentation for the packages that you want to use.

获取包

Getting packages

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

Once you have a pubspec, you can run pub get from the top directory of your application:

$ cd <path-to-my_app>
$ pub get

上面的操作即_获取依赖_。

This process is called getting the dependencies.

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

The pub get command determines which packages your app depends on, and puts them in a central system cache. If your app depends on a published package, pub downloads that package from the pub.dev site. For a Git dependency, pub clones the Git repository. Transitive dependencies are included, too. For example, if the js package depends on the test package, pub grabs both the js package and the test package.

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

Pub creates a .packages file (under your app’s top directory) that maps each package name that your app depends on to the corresponding package in the system cache.

从包中导入库

Importing libraries from packages

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

To import libraries found in packages, use the package: prefix:

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

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

The Dart runtime takes everything after package: and looks it up within the .packages file for your app.

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

You can also use this style to import libraries from within your own package. Consider the following pubspec file, which declares a dependency on the (fictional) transmogrify package:

name: my_app
dependencies:
  transmogrify:

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

transmogrify/
  lib/
    transmogrify.dart
    parser.dart
  test/
    parser/
      parser_test.dart

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

The parser_test file could import parser.dart like this:

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

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

But that’s a fragile relative path. If parser_test.dart ever moves up or down a directory, that path breaks. Instead, you can do as follows:

import 'package:transmogrify/parser.dart';

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

This way, the import can always get to parser.dart regardless of where the importing file is.

升级依赖

Upgrading a dependency

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

The first time you get a new dependency for your package, pub downloads the latest version of it that’s compatible with your other dependencies. It then locks your package to always use that version by creating a lockfile. This is a file named pubspec.lock that pub creates and stores next to your pubspec. It lists the specific versions of each dependency (immediate and transitive) that your package uses.

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

If your package is an application package, you should check this file into source control. That way, everyone working on your app uses the same versions of all of the packages. Checking in the lockfile also ensures that your deployed app uses the same versions of code.

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

When you’re ready to upgrade your dependencies to the latest versions, use pub upgrade:

$ pub upgrade

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

That command tells pub to regenerate the lockfile, using the newest available versions of your package’s dependencies. If you want to upgrade only one dependency, you can specify the package to upgrade:

$ pub upgrade transmogrify

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

That command upgrades transmogrify to the latest version but leaves everything else the same.

更多内容

More information

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

The following pages have more information about packages and the pub package manager.

如何使用

How to

参考

Reference

Pub 命令

Pub commands

pub 工具提供一下命令:

The pub tool provides the following commands:

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

For an overview of all the pub commands, see the pub tool documentation.

故障排除

Troubleshooting

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

Troubleshooting pub gives solutions to problems that you might encounter when using pub.