建立套件

Dart 生態系統使用套件來分享軟體，例如程式庫和工具。本頁面將說明如何建立標準的共享套件。

若要為套件建立初始目錄和結構，請使用 dart create 命令和 package 範本

$ dart create -t package <PACKAGE_NAME>

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

程式庫的最低要求如下

pubspec 檔案

程式庫的 pubspec.yaml 檔案與應用程式套件的檔案相同—沒有特殊的指定來表示該套件是程式庫。

lib 目錄

如同您預期的，程式庫程式碼位於 lib 目錄下，並且對其他套件公開。您可以根據需要，在 lib 下建立任何階層結構。依照慣例，實作程式碼會放在 lib/src 下。lib/src 下的程式碼被視為私有；其他套件永遠不應該匯入 src/...。若要將 lib/src 下的 API 公開，您可以從直接位於 lib 下的檔案匯出 lib/src 檔案。

當您建立小的、個別的程式庫（稱為迷你程式庫）時，套件最容易維護、擴充和測試。在大多數情況下，每個類別都應該放在自己的迷你程式庫中，除非您遇到兩個類別緊密耦合的情況。

在 lib 下直接建立一個「主要」程式庫檔案，lib/<套件名稱>.dart，它會匯出所有公開的 API。這讓使用者可以透過匯入單一檔案來取得程式庫的所有功能。

lib 目錄也可能包含其他可匯入的、非 src 的程式庫。例如，您的主要程式庫可能跨平台運作，但您建立個別的程式庫，這些程式庫依賴 dart:io 或 dart:js_interop。有些套件具有獨立的程式庫，這些程式庫旨在使用前綴匯入，而主要程式庫則不然。

讓我們看看真實世界套件的組織方式：shelf。shelf 套件提供了一種使用 Dart 建立 Web 伺服器的簡單方法，並且以 Dart 套件常用的結構佈局

在 lib 下，主要程式庫檔案 shelf.dart 從 lib/src 中的多個檔案匯出 API。為了避免公開超出預期的 API—並讓開發人員全面了解套件的整個公開 API—shelf.dart 使用 show 來精確指定要匯出的符號

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。

import 'package:utilities/utilities.dart';

當從您自己的套件匯入程式庫檔案時，如果兩個檔案都在 lib 內部，或兩個檔案都在 lib 外部，請使用相對路徑。當匯入的檔案在 lib 中，而匯入器在外部時，請使用 package:。

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

如果您的程式庫支援多個平台，那麼您可能需要有條件地匯入或匯出程式庫檔案。常見的用例是支援 Web 和原生平台的程式庫。

若要有條件地匯入或匯出，您需要檢查 dart:* 程式庫是否存在。以下是有條件匯出程式碼的範例，它檢查 dart:io 和 dart:js_interop 是否存在

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 的實作

import 'dart:io';

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

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

以下是預設實作，它使用會拋出 UnsupportedError 的 Stub。

void alarm([String? text]) => throw UnsupportedError('hw_none alarm');

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

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

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.md 和 CHANGELOG.md）在發佈套件中有說明。如需更多關於如何組織套件目錄的資訊，請參閱 pub 套件版面配置慣例。

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

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

如需產生文件的範例，請參閱 shelf 文件。

若要在產生的文件中包含任何程式庫層級的文件，請新增 library 指令，並將註解直接附加在其上方。如需關於為何以及如何為程式庫編寫文件的資訊，請參閱 Effective Dart: Documentation。

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

pub.dev 網站不僅託管您的套件，還會產生和託管您套件的 API 參考文件。最新產生文件的連結位於套件的關於方塊中；例如，請參閱 shelf 套件的 API 文件。先前版本文件的連結位於套件頁面的版本標籤中。

為了確保您套件的 API 文件在 pub.dev 網站上看起來良好，請按照下列步驟操作

• 在發佈套件之前，請執行 dart doc 工具，以確保您的文件成功產生並看起來符合預期。
• 在發佈套件之後，請檢查版本標籤，以確保文件成功產生。
• 如果文件完全沒有產生，請在版本標籤中點擊「失敗」，以查看 dart doc 輸出。

使用以下資源來深入瞭解套件

• 程式庫與匯入涵蓋程式庫檔案的使用。
• 套件文件非常有用，尤其是套件版面配置慣例。
• 什麼不該提交涵蓋了什麼不應該簽入原始碼儲存庫。
• dart-lang 組織下的較新套件傾向於展示最佳實務。請考慮研究以下範例：dart_style、path、shelf、source_gen 和 test。

除非另有說明，否則本網站上的文件反映的是 Dart 3.7.1 版本。頁面最後更新於 2024-12-10。 檢視原始碼 或 回報問題。