使用共享的 package

借用和分享程式碼。

當你可以建立和執行 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: ^3.0.0

# dependencies:
#   path: ^1.8.0

dev_dependencies:
  lints: ^2.1.0
  test: ^1.24.2

依賴 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.4
Downloading vector_math 2.1.4...
Changed 1 dependency!

這個命令將會將 vector_math 加入你工程檔案中 pubspec.yaml 的 dependencies 部分:

dependencies:
  vector_math: ^2.1.4

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.4
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: Dart 庫： The lib directory contains one or more Dart libraries, which can be imported into your Dart programs. lib 目錄包含一個或多個可以安裝到你 Dart 程式的 Dart 庫。

---

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 網站上。

---

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 的資訊。