目錄

dart doc

目錄 keyboard_arrow_down keyboard_arrow_up
more_horiz

dart doc 命令會為 Dart 原始碼產生 HTML 參考文件。

撰寫文件

#

若要將參考文字和範例新增至產生的文件，請使用具有 Markdown 格式的文件註解。如需撰寫文件註解的指引，請查看有效的 Dart：文件指南。

產生 API 文件

#

若要產生套件的文件，請從套件的根目錄執行 dart doc .。例如，產生 my_package 套件的 API 文件可能如下所示

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

預設情況下，dart doc 會將產生的文件和支援檔案放置在 doc/api 目錄中。若要變更輸出目錄，請使用 --output 旗標指定路徑

$ dart doc --output=api_docs .

如果您的套件設定或文件註解有任何問題，dart doc 會將其輸出為錯誤或警告。如果您只想測試問題，而不想儲存產生的文件，請新增 --dry-run 旗標

$ dart doc --dry-run .

設定產生

#

若要設定 dart doc 產生文件的方式，請在套件的根目錄中建立一個名為 dartdoc_options.yaml 的檔案。

若要深入瞭解檔案的格式和支援的設定選項，請查看 dart.dev/go/dartdoc-options-file。

檢視產生的文件

#

您可以使用多種方式檢視使用 dart doc 產生的文件。

檢視本機文件

#

若要檢視您使用 dart doc 產生或從線上下載的 API 文件，您必須使用 HTTP 伺服器載入它們。

若要提供檔案，請使用任何 HTTP 伺服器。請考慮使用 pub.dev 的 package:dhttpd。

若要使用 package:dhttpd，請全域啟動它，然後執行它並指定產生的文件路徑。以下命令會啟動套件，然後執行它以提供位於 doc/api 的 API 文件

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

然後若要在瀏覽器中讀取產生的文件，請開啟 dhttpd 輸出的連結，通常是 https://127.0.0.1:8080。

檢視託管文件

#

您也可以使用任何支援靜態 Web 內容的託管服務，將產生的 API 文件託管在線上。兩個常見的選項是Firebase 託管和GitHub Pages。

檢視套件文件

#

pub.dev 網站會產生並託管已上傳套件的公用程式庫文件。

若要檢視套件產生的文件，請導覽至其頁面，然後開啟頁面右側資訊方塊中的 API 參考 連結。例如，您可以在 pub.dev/documentation/http 找到 package:http 的 API 文件。

檢視核心程式庫文件

#

dart doc 也用於產生 Dart 核心程式庫的 API 參考文件。

若要檢視 Dart SDK 參考文件，請造訪與您正在開發的 Dart 發行管道相對應的 api.dart.dev 連結

分支產生的文件
stableapi.dart.dev/stable
betaapi.dart.dev/beta
devapi.dart.dev/dev
mainapi.dart.dev/main

疑難排解

#

若要識別並解決使用 dart doc 產生之文件的常見問題，請參閱下列參考章節。

#

如果產生的文件搜尋列無法運作或包含類似「無法初始化搜尋」的文字，則可能發生下列其中一種情況

  1. 您正在從自己的檔案系統存取文件，但它們未透過 HTTP 伺服器提供和載入。若要瞭解如何提供本機 API 文件，請查看如何在本機檢視產生的文件。
  2. dart doc 產生的 index.json 檔案遺失，或無法從文件目錄或您託管的 Web 伺服器存取。嘗試重新產生文件並驗證您的託管設定。

側邊欄載入失敗

#

如果產生的文件側邊欄遺失或包含類似「無法載入側邊欄」的文字，則可能發生下列其中一種情況

  1. 您正在從自己的檔案系統存取文件，但文件未透過 HTTP 伺服器提供和載入。若要瞭解如何提供本機 API 文件，請查看如何檢視本機文件。
  2. 已設定產生的文件 base-href 行為。此設定選項已棄用，不應再使用。請嘗試移除選項並使用 dart doc 的預設行為。如果預設行為中斷產生的文件中的連結，請提交問題。

缺少 API 文件

#

如果您找不到或無法存取您預期應有文件的 API 產生文件，則可能發生下列其中一種情況

  1. 套件未將您要尋找的 API 公開為公用 API。dart doc 僅產生公用程式庫和成員的文件，這些程式庫和成員會公開供其他套件匯入和使用。若要深入瞭解如何設定套件的公用程式庫，請查看公用程式庫上的套件配置指南。
  2. 您嘗試存取的 URL 大小寫不正確。預設情況下，dart doc 會產生區分大小寫的檔案名稱，這些檔案名稱會符合其對應的原始碼宣告，並且具有 .html 副檔名。請嘗試驗證 URL 是否符合這些預期。

應顯示圖示的地方卻出現文字

#

如果您看到的是文字而非圖示，例如選單和主題按鈕，您的瀏覽器可能無法載入 Material Symbols 字體。以下是一些解決方案：

  1. 嘗試使用代理伺服器，以允許存取 Google Fonts 伺服器。
  2. 更新產生的頁面以使用字體的本地版本。

除非另有說明，否則本網站上的文件反映的是 Dart 3.6.0 版本。頁面上次更新時間為 2024-04-11。 檢視原始碼 或 回報問題。