如何编写 API 参考

在开始记录 API 之前，有一些事项您应该在开始实际编写之前提前准备和计划。

假设您在阅读本指南之前已经对以下内容有所了解

• Web 技术，如 HTML、CSS 和 JavaScript。JavaScript 最重要。
• 阅读 Web 技术规范。在您记录 API 时，您将经常参考这些规范。

其他一切都可以边学边做。

在开始记录 API 之前，您应该准备好以下资源

1. 最新规范：无论是 W3C 建议还是早期编辑草案，您都应该参考涵盖该 API（或涵盖该 API 的规范）的最新可用草案。要找到它，您通常可以在网上搜索。最新版本通常会在规范的所有版本中链接到，并在“最新草案”或类似内容下列出。
2. 最新现代 Web 浏览器：这些应该是实验性/alpha 版本，例如 Firefox Nightly/Chrome Canary，它们更有可能支持您正在记录的功能。如果您正在记录一个新兴/实验性 API，这一点尤其重要。
3. 演示/博客文章/其他信息：尽可能多地查找信息。
4. 有用的工程联系：找到一位友好的工程联系人，向他们询问有关规范的问题，该联系人参与了 API 的标准化工作，或参与了其在浏览器中的实现。寻找他们的好地方是
   • 如果您在相关公司工作，请使用您公司内部的地址簿。
   • 参与该 API 讨论的公共邮件列表，例如 Mozilla 的 dev-platform 或 W3C 列表，例如 public-webapps。
   • 规范本身。例如，Web 音频 API 规范 在顶部列出了作者及其联系方式。

在记录 API 的过程中，您将多次返回来构建演示，但从花时间熟悉 API 的工作原理开始会很有用——了解主要接口/属性/方法是什么，主要用例是什么，以及如何使用它编写简单的功能。

当 API 发生变化时，您需要小心，确保您引用或学习的现有演示没有过时。检查演示中使用的主要结构，看看它们是否与最新规范相符。它们也可能在最新的浏览器中不起作用，但这并不是一个非常可靠的测试，因为旧功能通常会为了向后兼容性而继续得到支持。

API 参考通常包含以下页面。您可以在我们的 页面类型 文章中找到每个页面包含的内容、示例和模板的更多详细信息。在您开始之前，您应该写下您应该创建的所有页面的列表。

1. 概述页面
2. 接口页面
3. 构造函数页面
4. 方法页面
5. 属性页面
6. 事件页面
7. 概念/指南页面
8. 示例

概述页面

单个 API 概述页面用于描述 API 的作用、其顶级接口、包含在其他接口中的相关功能，以及其他高级细节。它的名称和标识符应该是 API 的名称，最后加上“API”。它位于 API 参考的顶层，作为 https://mdn.org.cn/en-US/docs/Web/API 的子级。

示例

• 标题：Web 音频 API
• 标识符：Web_Audio_API
• URL：https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API

接口页面

每个接口也会有自己的页面，描述接口的目的，列出任何成员（它包含的构造函数、方法、属性等），以及显示它与哪些浏览器兼容。页面的名称和标识符应该是接口的名称，与规范中写的一模一样。每个页面都位于 API 参考的顶层，作为 https://mdn.org.cn/en-US/docs/Web/API 的子级。

示例

• 标题：AudioContext
• 标识符：AudioContext
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioContext

• 标题：AudioNode
• 标识符：AudioNode
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioNode

• 我们记录在实现此接口的对象（实例方法）的原型上定义的方法，以及在实际类本身（静态方法）上定义的方法。在很少的情况下，它们同时存在于同一个接口上，您应该在页面上的单独部分列出它们（静态方法/实例方法）。通常只有实例方法存在，在这种情况下，您可以将它们放在标题“方法”下。
• 我们不记录接口继承的属性和方法：它们在各自的父接口中列出。不过，我们会暗示它们的存在。
• 我们确实记录了 mixin 中定义的属性和方法。有关更多详细信息，请参阅 mixin 贡献指南。
• 如果存在，字符串化器 (toString()) 和 json 化器 (toJSON()) 等特殊方法也会列出。
• 如果相关，也会列出命名构造函数（例如，HTMLImageElement 的 Image()）。

构造函数页面

每个接口都有零个或一个构造函数，记录在接口页面的子页面上。它描述了构造函数的目的，并显示了它的语法是什么，使用示例，浏览器兼容性信息等。它的标识符是构造函数的名称，与接口名称完全相同，标题是接口名称，点，构造函数名称，然后是结尾的括号。

示例

• 标题：AudioContext.AudioContext()
• 标识符：AudioContext
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioContext/AudioContext

属性页面

每个接口都有零个或多个属性，记录在接口页面的子页面上。每个页面都描述了属性的目的，并显示了它的语法是什么，使用示例，浏览器兼容性信息等。它的标识符是属性的名称，标题是接口名称，点，然后是属性名称。

示例

• 标题：AudioContext.state
• 标识符：state
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioContext/state

方法页面

每个接口都有零个或多个方法，记录在接口页面的子页面上。每个页面都描述了方法的目的，并显示了它的语法是什么，使用示例，浏览器兼容性信息等。它的标识符是方法的名称，标题是接口名称，点，方法名称，然后是括号。

示例

• 标题：AudioContext.close()
• 标识符：close
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioContext/close

• 标题：AudioContext.createGain()
• 标识符：createGain
• URL：https://mdn.org.cn/en-US/docs/Web/API/AudioContext/createGain

事件页面

将事件记录为其目标接口的子页面，并使用标识符 eventname_event，标题设置为 Interface: eventName event。

不要为on事件处理程序属性创建页面。在eventName_event页面上提及访问事件的两种方法。

示例

• 标题：XRSession：end 事件
• 标识：end_event
• URL：https://mdn.org.cn/en-US/docs/Web/XRSession/end_event

概念/指南页面

大多数 API 参考至少包含一个指南，有时还包含一个概念页面作为补充。至少，API 参考应该包含一个名为“使用api-名称”的指南，该指南将提供有关如何使用 API 的基本指南。更复杂的 API 可能需要多个使用指南来解释如何使用 API 的不同方面。

如果需要，您还可以包含一篇名为“api-名称概念”的概念文章，该文章将解释与 API 相关的任何概念背后的理论，开发人员应了解这些概念才能有效地使用它。

这些文章应该全部创建为 API 概述页面的子页面。例如，Web Audio 有四个指南和一篇概念文章

• https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API
• https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API
• https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics
• https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API

示例

您应该创建一些示例，以演示至少 API 最常见的用例。您可以将它们放在任何合适的地方，尽管推荐的位置是MDN GitHub 仓库。

列出所有内容

创建所有这些子页面的列表是跟踪它们的好方法。例如

• Web_Audio_API
• AudioContext
  • AudioContext.currentTime
  • AudioContext.destination
  • AudioContext.listener
  • …
  • AudioContext.createBuffer()
  • AudioContext.createBufferSource()
  • …
• AudioNode
  • AudioNode.context
  • AudioNode.numberOfInputs
  • AudioNode.numberOfOutputs
  • …
  • AudioNode.connect(Param)
  • …
• AudioParam
• 事件（更新列表）
  • start
  • end
  • …

列表中的每个接口都作为https://mdn.org.cn/en-US/docs/Web/API的子页面创建了一个单独的页面；例如，AudioContext 的文档将位于https://mdn.org.cn/en-US/docs/Web/API/AudioContext。每个接口页面都解释了该接口的作用，并提供了一个包含构成该接口的方法和属性的列表。然后，每个方法和属性都在其自己的页面上进行文档记录，该页面被创建为其所属接口的子页面。例如，BaseAudioContext/currentTime 在https://mdn.org.cn/en-US/docs/Web/API/AudioContext/currentTime上进行文档记录。

现在根据以下结构创建所需的页面。我们的MDN 内容自述文件包含有关创建新文档的说明，我们的页面类型指南包含可能会有用的更多示例和页面模板。

API 着陆页的长度差异很大，具体取决于 API 的大小，但它们基本上都具有相同的特性。请参阅https://mdn.org.cn/en-US/docs/Web/API/Web_Audio_API，了解大型着陆页的示例。

下面概述了着陆页的特性

1. 描述：着陆页的第一段应该简要概述 API 的主要目的。
2. 概念和使用部分：下一部分的标题应为“[api 名称] 概念和使用”，并概述 API 提供的所有主要功能，它解决了什么问题以及它的工作原理——所有这些都处于较高水平。本节应相当简短，不要涉及代码或特定实现细节。
3. 接口列表：本节的标题应为“[api 名称] 接口”，并提供指向构成 API 的每个接口的参考页面的链接，以及简要说明每个接口的作用。请参阅“使用 {{domxref}} 宏引用其他 API 特性”一节，了解创建新页面的更快捷方法。
4. 示例：本节应该展示 API 的一个或两个简单用例。
5. 规范表：在这一点上，您需要包含一个规范表——请参阅“创建规范引用表”一节以了解更多详细信息。
6. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。
7. 另请参阅： “另请参阅”部分是包含学习此技术时可能会有用的进一步链接的好地方，包括 MDN（和外部）教程、示例、库等。

现在您应该准备好开始编写接口页面。每个接口参考页面都应该遵循以下结构

1. {{APIRef}}：在每个接口页面的第一行中包含 {{APIRef}} 宏，并将 API 的名称作为参数，例如 {{APIRef("Web Audio API")}}。此宏用于在接口页面的左侧构建一个参考菜单，包括属性和方法以及在GroupData 宏中定义的其他快捷链接（如果您的 API 尚未在其中列出，请让某人将其添加到现有 GroupData 条目中，或创建一个新的条目）。菜单将看起来像下面的屏幕截图。
2. 特性状态：如果需要，会自动添加指示特性状态（例如已弃用、非标准或实验性）的横幅。为此，您需要在浏览器兼容性数据存储库中更新状态。
3. 描述：接口页面的第一段应该简要概述接口的主要目的。您可能还想包含几段，如果需要其他描述。如果接口实际上是一个字典，则应该使用该术语而不是“接口”。
4. 继承图：使用{{InheritanceDiagram}} 宏为接口嵌入 SVG 继承图。
5. 属性列表，方法列表：这些部分的标题应为“属性”和“方法”，并提供指向该接口每个属性/方法的参考页面的链接（使用 {{domxref}} 宏），以及对每个属性/方法的作用的描述。这些应该使用描述/定义列表进行标记。每个描述都应该简短简洁——如果可能的话，一句话。请参阅“使用 {{domxref}} 宏引用其他 API 特性”一节，了解创建指向其他页面的链接的更快捷方法。在两个部分的开头，在属性/方法列表开头之前，使用适当的句子，以斜体表示继承
   • 此接口不实现任何特定属性，但从 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 继承属性。
   • 此接口还从 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 继承属性。
   • 此接口不实现任何特定方法，但从 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 继承方法。
   • 此接口还从 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 继承方法。

   注意：只读属性应该在其 {{domxref}} 链接（在使用 {{experimentalInline}}、{{non-standard_Inline}} 和 {{deprecatedInline}} 宏之后，如果需要其中一些）的同一行中包含 {{ReadOnlyInline}} 宏，该宏会创建一个漂亮的“只读”徽章。

6. 示例：包括代码清单以显示 API 主要特性的典型用法。您应该列出其有趣子集，而不是列出所有代码。对于完整的代码清单，您可以参考包含完整示例的GitHub 仓库，您还可以链接到使用GitHub gh-pages 功能创建的实时示例（只要它只使用客户端代码，当然可以）。如果示例是视觉上的，您也可以使用 MDN 实时示例 功能，使其在页面中实时播放。
7. 规范表：在这一点上，您需要包含一个规范表——请参阅“创建规范引用表”一节以了解更多详细信息。
8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。
9. 垫片：如果适用，请包含此部分，提供垫片的代码，即使在没有实现 API 的浏览器上也可以使用该 API。如果没有垫片存在或需要，请完全省略此部分。
10. 另请参阅： “另请参阅”部分是包含学习此技术时可能会有用的进一步链接的好地方，包括 MDN（和外部）教程、示例、库等。我们对链接到外部来源的政策很宽松，但请注意
    • 不要包含与 MDN 中另一个页面相同信息的页面；请改为链接到该页面。
    • 不要放置作者姓名——我们是一个作者中立的文档网站。链接到文档；作者姓名将在那里显示。
    • 特别注意博客文章：它们往往会过时（旧语法、错误的兼容性信息）。只有当它们具有在维护的文档中找不到的明确附加值时，才链接到它们。
    • 不要使用“参阅…获取更多信息”或“单击…”之类的动作动词，您不知道您的读者是否能够看到或单击链接（例如在文档的纸质版本上）。

接口页面示例

以下是一些接口页面的示例

• Request 来自Fetch API。
• SpeechSynthesis 来自Web 语音 API。

将属性页面创建为它们所实现的接口的子页面。复制另一个属性页面的结构作为新页面的基础。

编辑属性页面名称以遵循Interface.property_name约定。

属性页面必须包含以下部分

1. 标题：页面的标题必须为InterfaceName.propertyName。接口名称必须以大写字母开头。尽管接口是在 JavaScript 中在对象的原型上实现的，但我们不会在标题中包含.prototype.，就像我们在JavaScript 参考中所做的那样。
2. {{APIRef}}：在每个属性页面的第一行中包含 {{APIRef}} 宏，并将 API 的名称作为参数，例如 {{APIRef("Web Audio API")}}。此宏用于在接口页面的左侧构建一个参考菜单，包括属性和方法以及在GroupData 宏中定义的其他快捷链接（如果您的 API 尚未在其中列出，请让某人将其添加到现有 GroupData 条目中，或创建一个新的条目）。菜单将看起来像下面的屏幕截图。
3. 特性状态：如果需要，会自动添加指示特性状态（例如已弃用、非标准或实验性）的横幅。为此，您需要在浏览器兼容性数据存储库中更新状态。
4. 描述：属性页面的第一段应该简要概述属性的主要目的。您可能还想包含几段，如果需要其他描述。要包含的明显额外信息是其默认/初始值，以及它是否为只读。第一句话的结构必须为

   对于只读属性

   InterfaceName.property 只读属性返回一个 {{domxref("type")}}，它…

   对于其他属性

   InterfaceName.property 属性是一个 {{domxref("type")}}，它…

   注意: InterfaceName.property 应该放在 <code> 标签中，并且在第一次使用时应该用 <strong> 标签加粗。

5. 值: "值" 部分将包含对属性值的描述。这应该包含属性的数据类型以及它所代表的内容。例如，请参见 SpeechRecognition.grammars
6. 示例: 包含一个代码列表以显示对该属性的典型用法。您应该从一个简单的示例开始，展示如何创建一个该类型的对象以及如何访问该属性。更复杂的示例可以在这类示例之后添加。在这些额外的示例中，您应该列出代码的有趣子集，而不是列出所有代码。对于完整的代码列表，您可以参考包含完整示例的 GitHub 仓库，您也可以链接到使用 GitHub gh-pages 功能 创建的实时示例（只要它只使用客户端代码即可）。如果示例是视觉化的，您也可以使用 MDN 的 实时示例 功能使其在页面中实时可玩。
7. 规范表：在这一点上，您需要包含一个规范表——请参阅“创建规范引用表”一节以了解更多详细信息。
8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。
9. 另请参见: "另请参见" 部分是包含在使用此技术时可能会有用的其他链接的最佳位置: 例如受此属性更改影响的方法和属性，或者与其相关的事件。更多在学习此技术时有用的链接，包括 MDN（和外部）教程、示例、库，… 可以添加，但将它们添加到接口参考页面上可能更有用。

属性页面示例

以下是属性页面的示例。

• Request.method 来自 Fetch API.
• SpeechSynthesis.speaking 来自 Web 语音 API.

将您的方法页面创建为它们实现的接口的子页面。复制另一个方法页面的结构作为您新页面的基础。

方法页面需要以下部分

1. 标题: 页面的标题必须是 InterfaceName.method()（带有两个终端圆括号），但 slug（页面 URL 的结尾）不能包含圆括号。此外，接口名称必须以大写字母开头。虽然接口是在 JavaScript 中在对象的原型上实现的，但我们不会在标题中添加 .prototype.，就像我们在 JavaScript 参考 中所做的那样。
2. {{APIRef}}: 在每个方法页面的第一行中包含 {{APIRef}} 宏，并将 API 名称作为参数，例如 {{APIRef("Web 音频 API")}}。此宏用于在接口页面的左侧构建参考菜单，包括属性和方法，以及在 GroupData 宏中定义的其他快速链接（如果还没有列出，请让其他人将您的 API 添加到现有的 GroupData 条目中，或创建一个新的条目）。此菜单将类似于下面的屏幕截图。
3. 特性状态：如果需要，会自动添加指示特性状态（例如已弃用、非标准或实验性）的横幅。为此，您需要在浏览器兼容性数据存储库中更新状态。
4. 描述: 方法页面的第一段应简要概述方法的总体用途。您可能还想包含另外几段，如果需要其他描述。明显需要包含的额外信息是其默认参数值、方法依赖的任何理论以及参数值的作用。

   第一句话的开头必须遵循以下结构

   InterfaceName.method() 方法接口…

   注意: InterfaceName.method() 应该放在 <code> 标签中，并且在第一次使用时也应该用 <strong> 标签加粗。

5. 语法: 语法部分应包含一个 2-3 行的示例 - 通常只是接口的构造，然后是接口方法的调用。

   语法应为以下形式

   method(param1, param2, …)

   语法部分应包含三个小节（请参见 SubtleCrypto.sign() 以获取示例）
   • "参数": 这应该包含一个定义列表（或无序列表），其中命名并描述方法接受的不同参数。对于可选参数，您应该在参数名称旁边包含 可选 宏。如果没有参数，则应省略此部分。
   • "返回值": 这应该说明方法的返回值是什么，无论是简单值（例如双精度数或布尔值），还是更复杂的值（例如另一个接口对象），在这种情况下，您可以使用 {{domxref}} 宏链接到涵盖该接口的 MDN API 页面（如果存在）。方法可能不返回任何值，在这种情况下，返回值应写为 "{{jsxref('undefined')}}"（在渲染的页面中将显示为：undefined）。
   • "异常": 这应该列出调用方法时可能引发的不同异常，以及导致它们的具体情况。如果没有异常，则应省略此部分。
6. 示例: 包含一个代码列表以显示对该方法的典型用法。您应该列出代码的有趣子集，而不是列出所有代码。对于完整的代码列表，您可以参考包含完整示例的 GitHub 仓库，您也可以链接到使用 GitHub gh-pages 功能 创建的实时示例（只要它只使用客户端代码即可）。如果示例是视觉化的，您也可以使用 MDN 的 实时示例 功能使其在页面中实时可玩。
7. 规范表：在这一点上，您需要包含一个规范表——请参阅“创建规范引用表”一节以了解更多详细信息。
8. 浏览器兼容性：现在您需要包含一个浏览器兼容性表。有关详细信息，请参阅兼容性表。

方法页面示例

以下是方法页面的示例。

• Document.getAnimations 来自 Web 动画 API.
• fetch() 来自 Fetch API.

创建完 API 参考页面后，您需要在其中插入正确的侧边栏以将页面关联起来。我们的 API 参考侧边栏 指南解释了如何操作。