dart doc

目录 keyboard_arrow_down keyboard_arrow_up

more_horiz

dart doc 命令用于生成 Dart 源代码的 HTML 参考文档。

要向生成的文档中添加参考文本和示例，请使用带有 Markdown 格式的文档注释。有关编写文档注释的指南，请查看 Effective Dart：文档指南。

要生成包的文档，请从包的根目录运行 dart doc . 。例如，为 my_package 包生成 API 文档可能类似于以下内容：

$ cd my_package
$ dart pub get
$ dart doc .
正在编制 my_package 的文档...
...
成功！文档已生成到 /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 托管和 GitHub Pages 。

pub.dev 站点为上传包的公共库生成并托管文档。

要查看包的生成的文档，请导航到其页面并在页面右侧的信息框中打开“API 参考”链接。例如，您可以在 pub.dev/documentation/http 找到 package:http 的 API 文档。

dart doc 也用于为 Dart 核心库生成 API 参考文档。

要查看 Dart SDK 参考文档，请访问与您正在开发的 Dart 版本分支对应的 api.dart.dev 链接：

要识别和解决使用 dart doc 生成的文档的常见问题，请查阅以下参考部分。

如果生成的文档的搜索栏无法正常工作或包含类似“未能初始化搜索”的文本，则可能出现以下情况之一：

如果生成的文档的侧边栏丢失或包含类似“未能加载侧边栏”的文本，则可能出现以下情况之一：

您正在从自己的文件系统访问文档，但文档没有通过 HTTP 服务器提供和加载。要了解如何提供本地 API 文档服务，请查看如何查看本地文档。
生成的文档的 base-href 行为已配置。此配置选项已弃用，不应再使用。尝试删除该选项并使用 dart doc 的默认行为。如果默认行为破坏了生成的文档中的链接，请提交问题。

如果您找不到或无法访问您期望具有文档的 API 的生成的文档，则可能出现以下情况之一：

该包未将您正在查找的 API 公开为公共 API。 dart doc 仅为其他包可以导入和使用的公共库和成员生成文档。要了解有关配置包的公共库的更多信息，请查看有关公共库的包布局指南。
您尝试访问的 URL 大小写不正确。默认情况下， dart doc 生成的文件名区分大小写，与其对应的源声明匹配，并具有 .html 扩展名。尝试验证 URL 是否符合这些预期。

如果您看到文本而不是菜单和主题按钮之类的图标，则您的浏览器可能无法加载 Material Symbols 字体。解决此问题的一些方法包括：

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。查看源代码或报告问题.

编写文档