目錄

如何使用 package

Dart 生態系統使用 來管理共享軟體,比如:函式庫和工具。我們使用 Pub 包管理工具 來獲取 Dart 套件。在 Pub 上,可以找到公開可用的套件。或者從本地檔案系統或其他的位置,比如 Git 儲存庫,載入可用的套件。無論包是從什麼途徑載入的, Pub 都會進行版本依賴管理,從而幫助我們獲得版本相容的軟體包以及 SDK 。

大多數 Dart-savvy IDEs 都支援 Pub 的使用,包括套件的建立,下載,更新和釋出。同樣上述功能也可以在命令列上透過 dart pub 來操作。或者可以在命令列上使用pub。

Dart 包目錄中至少包含一個 pubspec 檔案。 pubspec 檔案記錄一些關於套件的元資料。此外,套件還包含其他依賴項(在 pubspec 中列出), Dart 函式庫,應用,資源,測試,圖片,以及範例。

透過以下步驟,參考使用包:

  • 建立一個 pubspec (一個名為 pubspec.yaml 檔案,檔案列出依賴的套件以及包含的其他元資料,比如當前套件的版本)。

  • 使用 dart pub get 獲取當前所依賴的套件。

  • 如果當前 Dart 程式碼相依套件中的某個庫,匯入 (import) 該函式庫。

建立 pubspec

pubspec 是一個名為 pubspec.yaml 的檔案,檔案位於應用的根路徑。最簡單的 pubspec 只需要列出套件名稱:

name: my_app

下面是一個 pubspec 的範例,範例中宣告依賴了在 Pub 站點上託管的兩個 package(jsintl):

name: my_app

dependencies:
  js: ^0.6.0
  intl: ^0.17.0

有關建立 pubspec 的詳細內容,請參閱 pubspec 文件 以及使用套件的相關文件。

獲取套件

專案中一旦擁有了 pubspec 檔案,就可以在專案根目錄中執行 dart pub get 命令:

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

上面的操作即 獲取依賴

dart pub get 命令確定當前應用所依賴的套件,並將它們儲存到中央 系統快取 (central system cache) 中。如果當前應用依賴了一個公開套件, Pub 會從 Pub 站點 獲取該套件。對於一個 Git 依賴, Pub 會 Clone 該 Git 儲存庫。同樣包括套件的相關依賴也會被下載。例如,如果 js 套件相依 test 套件,pub 會同時獲取 js 套件和 test 套件。

Pub 會建立一個 package_config.json 檔案(位於 .dart_tool/ 目錄下),該檔案將應用程式所依賴的每個套件名稱相應的對映到系統快取中的套件。

從套件中匯入庫

使用 package: 字首,匯入套件中的函式庫:

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

Dart 執行時會抓取 package: 之後的內容,並在應用程式的 package_config.json 檔案中查詢它。

也可以使用此方式從自己的套件中匯入庫。思考下面的 pubspec 檔案,該檔案聲明瞭對 transmogrify 套件(虛構的套件名稱)的依賴:

name: my_app
dependencies:
  transmogrify:

假如 transmogrify 這個 package 的佈局如下:

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

parser_test.dart 就可以透過下面的方式匯入 parser.dart

import 'package:transmogrify/parser.dart';

升級依賴

第一次獲取依賴時,Pub 會下載依賴及其相容的最新版本。然後透過建立 lockfile 鎖定依賴,以始終使用這個版本。 Pub 會在 pubspec 旁建立並存儲一個名為 pubspec.lock 檔案。它列出了使用的每個相依套件的指定版本(當前包或傳遞套件的版本)。

如果套件是一個應用程式套件,那麼應該將此檔案加入到 原始檔管理。這樣,在應用上開發的每個人都能夠使用所有相同版本的套件。同樣加入到 lockfile 可以保證部署的應用使用的是同一版本的程式碼。

如果已經準備更新依賴到最新版本,使用 dart pub upgrade 命令:

$ dart pub upgrade

dart pub upgrade 命令用於重新產生 lockfile 檔案,並使用最新可用版本的相依套件。如果僅升級某個依賴,可以在命令中指定需要升級的包:

$ dart pub upgrade transmogrify

上面的命令升級 transmogrify 到最新版本,但維持其它套件不變。

dart pub upgrade] 命令並非總是可以將所有的 package 更新到最新版本,原因是 pubspec 檔案中的一些 package 之間有版本限制的衝突。想要確定 pubspec 裡已經過時且需要編輯的 package,請使用 dart pub outdated 命令。

更多內容

以下連結的頁面是關於套件及 Pub 包管理的更多內容。

如何使用

參考

Pub 子命令

The dart pub tool provides the following subcommands:

有關所有 pub 命令的概述,參見 pub 工具文件

故障排除

Pub 故障排除 提供使用中可能遇到問題的解決方法。