內容

Dart 生態系統使用 套件 來分享軟體,例如函式庫和工具。此頁面會告訴您如何建立標準的共用 套件

建立新套件

#

若要建立套件的初始目錄和結構,請使用 dart create 指令和 package 範本

$ dart create -t package <PACKAGE_NAME>

套件組成

#

下圖顯示套件最簡單的配置

root directory contains pubspec.yaml and lib/file.dart

函式庫的最低需求為

pubspec 檔案
函式庫的 pubspec.yaml 檔案與 應用程式套件 相同,沒有特別的標示來表示套件是函式庫。
lib 目錄
正如您所料,函式庫程式碼位於 lib 目錄下,並對其他套件公開。您可以在 lib 下建立任何層級,視需要而定。依慣例,實作程式碼會放在 lib/src 下。lib/src 下的程式碼被視為私有的;其他套件永遠不需要匯入 src/...。若要讓 lib/src 下的 API 公開,您可以從 lib 下的檔案匯出 lib/src 檔案。

整理套件

#

當您建立小型個別函式庫(稱為 迷你函式庫)時,套件最容易維護、擴充和測試。在大多數情況下,每個類別都應該在自己的迷你函式庫中,除非您有兩個類別緊密結合的情況。

在 lib 下建立一個「主要」函式庫檔案 lib/<package-name>.dart,匯出所有公開 API。這允許使用者透過匯入單一檔案來取得函式庫的所有功能。

lib 目錄也可能包含其他可匯入的非 src 函式庫。例如,您的主要函式庫可能跨平台運作,但您建立了依賴於 dart:iodart:js_interop 的個別函式庫。有些套件有不同的函式庫,當主要函式庫不存在時,這些函式庫會用前綴匯入。

讓我們來看看實際套件的組織:shelf。 shelf 套件提供使用 Dart 建立網路伺服器的簡易方式,其結構是 Dart 套件常用的結構

shelf root directory contains example, lib, test, and tool subdirectories

在 lib 下,主要函式庫檔案 shelf.dartlib/src 中的幾個檔案匯出 API。為了避免公開比預期更多的 API,並讓開發人員概覽套件的整個公開 API,shelf.dart 使用 show 來明確指定要匯出的符號

lib/shelf.dart
dart
export 'src/cascade.dart' show Cascade;
export 'src/handler.dart' show Handler;
export 'src/hijack_exception.dart' show HijackException;
export 'src/middleware.dart' show Middleware, createMiddleware;
export 'src/middleware/add_chunked_encoding.dart' show addChunkedEncoding;
export 'src/middleware/logger.dart' show logRequests;
export 'src/middleware_extensions.dart' show MiddlewareExtensions;
export 'src/pipeline.dart' show Pipeline;
export 'src/request.dart' show Request;
export 'src/response.dart' show Response;
export 'src/server.dart' show Server;
export 'src/server_handler.dart' show ServerHandler;

shelf 套件也包含一個迷你函式庫:shelf_io。這個轉接器處理來自 dart:io 的 HttpRequest 物件。

匯入函式庫檔案

#

從其他套件匯入函式庫檔案時,請使用 package: 指令指定該檔案的 URI。

dart
import 'package:utilities/utilities.dart';

從自己的套件匯入函式庫檔案時,請使用相對路徑(如果兩個檔案都在 lib 內,或兩個檔案都在 lib 外)。如果匯入的檔案在 lib 內,而匯入程式在 lib 外,請使用 package:

下列圖表顯示如何從 lib 和 web 匯入 lib/foo/a.dart

lib/bar/b.dart uses a relative import; web/main.dart uses a package import

有條件地匯入和匯出函式庫檔案

#

如果您的函式庫支援多個平台,您可能需要有條件地匯入或匯出函式庫檔案。常見的用例是同時支援 web 和原生平台的函式庫。

若要進行有條件的匯入或匯出,您需要檢查是否存在 dart:* 函式庫。以下是檢查是否存在 dart:iodart:js_interop 的有條件匯出程式碼範例:

lib/hw_mp.dart
dart
export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.js_interop) 'src/hw_web.dart'; // package:web implementation

以下是該程式碼執行的動作:

  • 在可使用 dart:io 的應用程式(例如命令列應用程式)中,匯出 src/hw_io.dart
  • 在可使用 dart:js_interop 的應用程式(web 應用程式)中,匯出 src/hw_web.dart
  • 否則,匯出 src/hw_none.dart

若要進行有條件的檔案匯入,請使用與上述相同的程式碼,但將 export 變更為 import

所有有條件匯出的函式庫都必須實作相同的 API。例如,以下是 dart:io 實作:

lib/src/hw_io.dart
dart
import 'dart:io';

void alarm([String? text]) {
  stderr.writeln(text ?? message);
}

String get message => 'Hello World from the VM!';

以下是預設實作,它使用會擲回 UnsupportedError 的 stub:

lib/src/hw_none.dart
dart
void alarm([String? text]) => throw UnsupportedError('hw_none alarm');

String get message => throw UnsupportedError('hw_none message');

在任何平台上,您都可以匯入具有有條件匯出程式碼的函式庫。

dart
import 'package:hw_mp/hw_mp.dart';

void main() {
  print(message);
}

提供其他檔案

#

設計良好的套件很容易測試。我們建議您使用 test 套件撰寫測試,並將測試程式碼放在套件頂端的 test 目錄中。

如果您建立任何供公開使用的命令列工具,請將它們放在公開的 bin 目錄中。使用 dart pub global activate 啟用從命令列執行工具。在 pubspec 的 executables 區段 中列出工具,讓使用者可以直接執行,而不需要呼叫 dart pub global run

如果您包含函式庫使用範例,會很有幫助。這會放在套件頂端的 example 目錄中。

在開發期間建立的任何工具或可執行檔,如果不用於公開使用,請放在 tool 目錄中。

如果您將函式庫發佈到 pub.dev 網站,其他必要的檔案(例如 README.mdCHANGELOG.md)說明在 發佈套件 中。如需瞭解如何整理套件目錄的詳細資訊,請參閱 pub 套件佈局慣例

記錄函式庫

#

你可以使用 dart doc 工具為你的程式庫產生 API 文件。dart doc 會剖析原始碼,尋找使用 /// 語法的 文件註解

dart
/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

有關已產生文件範例,請參閱 shelf 文件

若要將任何程式庫層級文件包含在已產生文件中,請新增 library 指令,並將註解附加在其正上方。有關如何以及為何記錄程式的說明,請參閱 Effective Dart:文件

散布開源函式庫

#

如果你的程式庫是開放原始碼,我們建議你在 pub.dev 網站 上分享它。若要發布或更新程式庫,請使用 pub publish,它會上傳你的套件並建立或更新其頁面。例如,請參閱 shelf 套件 的頁面。有關如何準備套件以進行發布的詳細資訊,請參閱 發布套件

pub.dev 網站不僅會主機你的套件,還會產生並主機你的套件的 API 參考文件。指向最新已產生文件的連結會顯示在套件的關於方塊中;例如,請參閱 shelf 套件的 API 文件。指向先前版本文件的連結會顯示在套件頁面的版本標籤中。

若要確保你的套件的 API 文件在 pub.dev 網站上看起來不錯,請執行下列步驟

  • 在發布你的套件之前,請執行 dart doc 工具,以確保你的文件已成功產生,且看起來符合預期。
  • 發布你的套件後,請查看版本標籤,以確保文件已成功產生。
  • 如果文件完全沒有產生,請按一下版本標籤中的失敗,以查看 dart doc 輸出。

資源

#

使用下列資源,以深入了解套件