建立套件

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: 文件。

如果您的函式庫是開放原始碼，我們建議您在 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.6.0。頁面最後更新於 2024-12-10。 檢視原始碼 或 回報問題。