跳到主要內容
目錄

dart doc

目錄 keyboard_arrow_down keyboard_arrow_up
more_horiz

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

撰寫文件

#

若要將參考文字和範例新增至產生的文件，請使用具有 Markdown 格式的文件註解。如需撰寫文件註解的指引，請查看Effective 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 輸出的連結，通常是 http://localhost:8080。

檢視託管文件

#

您也可以使用任何支援靜態 Web 內容的託管服務線上託管您產生的 API 文件。兩個常見的選項是 Firebase hosting 和 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 產生的文件的常見問題，請參閱以下參考章節。

#

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

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

側邊欄載入失敗

#

如果產生的文件的側邊欄遺失或包含類似「Failed to load sidebar」的文字，則可能發生以下其中一種情況

  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 伺服器的 Proxy。
  2. 更新產生的頁面以使用字型的本機版本。

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