目录

使用共享的 package

借用和分享代码。

本文的重点是什么?

  • Pub.dev 网站是 Dart package 主要的公共仓库。

  • 遵循一些规定,比如一个有效的 pubspec.yaml 文件,使你的应用成为一个 package。

  • 如果你正在开发一款 Web 或服务端应用,请使用 dart create 生成相关初始化文件。

  • 如果你正在开发一款 Web 或服务端应用,请使用 dart pub get 命令下载相关的 package。

  • 如果你正在开发一款移动应用,请使用 Flutter 工具。

当你可以创建和运行 Dart 应用时,你就已经准备复用其他程序员编写的代码了。 pub.dev 网站 仓库有许多可用的使用 Dart 代码编写的 package。

本教程将向你展示如何使用 dart pub 命令 —Dart 的 package 管理命令—即用以安装仓库中某个 package (比如 vector_math package)的命令。你可以使用这些步骤来安装由 pub.dev 网站 提供的任意一个 package;当你想安装其它你想要使用的 package 时只需修改这些步骤中的示例的 package 名称即可。本教程同时也会向你展示一些你可能会使用到的优秀的 package。

关于 pubspec.yaml 文件

想要使用外部的 package,你的应用其本身也必须是一个 package。任何在顶层目录中包含有效 pubspec.yaml 文件的应用都是一个 package,从而可以使该应用使用外部的 package。

你可以使用 dart create 命令来生成带有有效 pubspec.yaml 文件和目录结构的 package。你可以使用命令行工具来调用 Stagehand 工具,也可以使用类似 IntelliJ 或 WebStorm 这样的 IDE 来间接使用 Stagehand 工具。

现在你可以运行 dart create 命令,使用 --help 来查看它可以生成的模板文件:

$ dart create --help

你将会看到一系列的生成器,包括各种 Web 和服务端应用的。其中一个生成器叫 console-full

使用 dart create 工具来生成一个叫做 vector_victor 的命令行应用:

$ dart create -t console vector_victor 
$ cd vector_victor

pubspec.yaml 文件包含了由 YAML 语言撰写的 package 规格。(访问 Pubspec 格式 获取更多深入的介绍。)而你的 pubspec.yaml 文件看起来则应该是这样的

name: vector_victor
description: A sample command-line application.
version: 1.0.0
# homepage: https://www.example.com

environment:
  sdk: '>=2.18.0 <3.0.0'

# dependencies:
#   path: ^1.8.0

dev_dependencies:
  lints: ^2.0.0
  test: ^1.16.0

依赖 package 的命名

为了能够使用外部的 package,你需要将其添加到你应用 pubspec.yaml 文件的依赖里。依赖中的每一项都指定了你应用所使用的 package 名称以及版本。

下面让我们为 vector_victor 应用添加一个名为 vector_math 的 package,这个 package 可以在 pub.dev 网站 中找到。

运行 dart pub add 命令并指定使用 vector_math,将其加入你的依赖中。

$ dart pub add vector_math
Resolving dependencies... 
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

这个命令将会将 vector_math 加入你工程文件中 pubspec.yamldependencies 部分:

dependencies:
  vector_math: ^2.1.3

You can also find your desired version on the vector_math page on pub.dev and add it manually to the dependency section.

你可以查阅 Pub 版本管理 获取更多有关版本号含义以及格式化的相关信息。

pub.dev 网站 是 Dart package 主要的公共仓库。 dart pub 命令在解析 package 依赖时会自动去该网站进行检查。如果你想使用该网站的某个 package,你可以像我们上面所说的那样在 dependencies 中指定对应的 package 名称。

安装依赖的 package

如果你使用适配了 Dart 语言开发的编辑器或者 dart pub 命令了编辑 pubspec.yaml 文件,其可能会在你编辑了该文件后自动下载安装相关依赖的 package。

否则,你只能手动地执行 dart pub get 命令进行下载安装:

$ dart pub get
Resolving dependencies...
+ vector_math 2.1.3
Changed 1 dependency!

dart pub get 命令会安装你应用依赖列表中的 package。而每一个 package 可能还会包含其它的库或资源,Pub 同样会将它们依次安装;如果一个依赖的 package 已经安装过,则会直接使用。 Pub 会缓存你应用依赖过的每一个 package 并将其缓存至 .dart_tool/package_config.json 的文件中。

Pub 会创建一个名为 pubspec.lock 的文件来标识哪些 package 的哪些版本已经安装过。此举可以为开发者提供一个稳定的开发环境。你也可以修改 package 的版本并使用 dart pub upgrade 命令来更新 package。

你可以从中获取(或不可获取)什么?

除了 Dart 库以外,vector_math package 可能包含其它对你有用但不会安装到你应用目录的资源。让我们后退一步看看你在获取依赖时得到了什么以及它们从何而来。

访问 Github 仓库 Dart 数学矢量仓库 来查看 vector_math package 的具体内容。尽管该仓库中有大量的文件和目录,但是只有 lib 目录下的文件会在你执行 pub get 命令时安装。


Dart libraries directory
Dart libraries: Dart 库: The lib directory contains one or more Dart libraries, which can be imported into your Dart programs. lib 目录包含一个或多个可以安装到你 Dart 程序的 Dart 库。

Housekeeping files
Housekeeping files: 管理文件: When using a package written by someone else, the README.md file is a good place to start. It should contain important information about the package, such as its intent, contents, samples, and instructions. The LICENSE file provides copyright and rules-of-use information. All of these files are in the package repository; the contents of some, such as README.md, are also displayed in pub.dev. These files aren't installed when you install a package. 当使用别人开发的 package 时,README 文件是了解这个 package 的最好地方。它会包含与这个 package 相关的重要信息,比如开发 package 时的想法、其相关内容、示例以及使用说明。 LICENSE 文件则包含了版权信息以及使用规则信息。所有文件均在 package 的代码仓库中,且在你安装 package 时它们不会被下载。而 README.md 中的内容同样也会展示在 pub.dev 网站上。

Document, scripts, tests, and other resources
Other resources: 其它资源: Along with Dart libraries, a package might also contain other resources such as example code, tests, scripts, and documentation. If a package contains these resources, they should be in the directories as specified in the pub. 一个 package 可能会包含库以外的其它资源,比如示例代码、测试、脚本以及文档。如果 package 中包含诸如此类的信息,它们会存放在 Pub 指定的目录中。 conventions.

从 package 中导入库

现在你已经安装了 package,你可以在你的应用中导入和使用 package 中的库。

与 SDK 库一样,使用 import 关键字导入使用安装了的库中的代码。 Dart SDK 库是内置的且由特殊的 dart: 前缀标识。如果你使用由 pub 命令安装的外部库,请使用 package: 前缀。

  1. 获取 package 中主要库的导入流程:

    1. 打开 pub.dev 网站中 vector_math package 的网页。

    2. 点击 Installing 标签。

    3. 拷贝有 import 的这一行代码。其看起来像下面这样:

      import 'package:vector_math/vector_math.dart';
  2. 在你的 vector_victor 应用中,编辑 lib/vector_victor.dart 文件,由此它导入 vector_math 库并使用了它的一些 API。你可以阅读 vector_math API 文档 获取更多相关信息。

其它资源

  • Dart 开发者们在 pub.dev site 分享它们开发的 package。你可以在那里查找你想要使用的 package 或者分享你自己开发的 package。

  • 你也可以查阅 pub package 文档 获取更多有关如何使用和分享 package 的信息。