建立包

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/<package-name>.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的存根的預設實現

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指令並將註釋直接附加在其上方。有關記錄庫的方式和原因，請參見有效 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.5.3。頁面最後更新於 2024-07-03。 檢視原始碼 或 報告問題.