API 参考侧边栏

创建侧边栏

您需要执行以下三个步骤来创建 API 侧边栏

1. 创建您的 API 参考页面。
2. 在 GroupData.json 文件中为您特定的 API 添加一个条目。
3. 使用 APIRef 宏将侧边栏插入到您希望显示它的每个页面上。

让我们一步一步地介绍这些步骤。本文中我们将引用的示例是 Fetch API。

向 GroupData.json 添加条目

GroupData.json 文件包含所有与 API 参考侧边栏中应显示的链接相关的数据。当调用时，APIRef 宏会接收一个作为参数传递给它的 API 名称，在 GroupData.json 中查找该名称，构建一个合适的侧边栏，并将其插入到页面中。

要向 GroupData.json 添加条目，您需要

1. 确保您有一个 GitHub 账户。
2. Fork MDN content 仓库，创建一个新的分支来包含您的更改，并在本地克隆该仓库。
3. 在开始工作之前切换到您的新分支，并在完成后将其推送到您的分支。
4. 创建一个拉取请求，以便 MDN 团队可以审查您的工作，并在必要时要求进行更改。

GroupData.json 文件位于 files/jsondata/ 目录下。查看该文件，您会看到一个巨大的 JSON 结构，每个 API 都有自己的成员。名称是 API 名称，值是一个对象，其中包含几个子成员，用于定义要创建的侧边栏链接。

例如，查看 MDN 上的 Fetch API 页面。GroupData.json 中对应的条目如下所示：

{
  "Fetch API": {
    "overview": ["Fetch API"],
    "interfaces": [
      "Headers",
      "Request",
      "Response",
      "FetchController",
      "FetchObserver",
      "FetchSignal",
      "ObserverCallback"
    ],
    "methods": ["fetch()"],
    "properties": [],
    "events": []
  }
}

正如您所见，我们使用了“Fetch API”作为名称，并在值对象中包含了一些子成员。

GroupData 条目中要包含的子成员

本节列出了您可以在 GroupData 条目中包含的所有子成员。

请注意，列出的子成员中的大多数值都等同于链接文本，并且是附加到主 API 索引页面 — https://mdn.org.cn/<language-code>/docs/Web/API — 末尾的“slug”，用于创建显示链接的最终 URL。例如，“Response”将创建如下链接：

<li><a href="/en-US/docs/Web/API/Response">Response</a></li>

有几种例外情况。例如，“guides”子成员包含指向相关指南/教程的 URL。在这种情况下，URL 会附加到 MDN 文档根目录 — https://mdn.org.cn/<language-code> — 的末尾，从而允许包含 MDN 上的任何文章。

以下是可用的成员。这些在技术上都是可选的，但强烈建议您不要省略它们，而是包含空数组。

1. "overview" — 值是一个数组，您可以在其中包含 API 概述页面的 slug（如果存在）。“Fetch API”将创建一个指向 https://mdn.org.cn/en-US/docs/Web/API/Fetch_API 的链接。
2. "interfaces" — 值是一个数组，您应该在此列出构成该 API 的所有接口。“Response”将创建一个指向 https://mdn.org.cn/en-US/docs/Web/API/Response 的链接。
3. "methods" — 值是一个数组，其中应包含规范添加到与其他 API 关联的接口的任何方法，例如在 Navigator 或 Window 上创建的实例化方法。如果方法数量众多，您可以考虑仅列出最受欢迎的方法，或将它们放在列表的开头。“fetch()”将创建一个指向 https://mdn.org.cn/en-US/docs/Web/API/fetch 的链接。请*不要*列出属于同一 API 的接口的成员方法。
4. "properties" — 值是一个数组，其中应包含与 API 相关的所有属性。这可以包括 API 规范中定义的接口的属性，以及 API 在其他接口上定义的属性。如果属性数量众多，您可以考虑仅列出最受欢迎的属性，或将它们放在列表的开头。“Headers.append”将创建一个指向 https://mdn.org.cn/en-US/docs/Web/API/Headers/append 的链接。
5. "events" — 值是一个数组，其中应包含属于 API 但定义在*不*属于该 API 的接口中的事件的*标题*（属于 API 中接口的事件（interfaces）默认会被记录）。如果事件数量众多，您可以考虑仅列出最受欢迎的事件，或将它们放在列表的开头。例如，"Document: selectionchange" 是 Selection API 的一部分，但 Document 不是，因此我们将事件添加到数组中，它将从 Selection API 主题中链接。
6. "guides" — 值是一个字符串数组，每个字符串都代表一个解释如何使用该 API 的指南主题。字符串包含指南 URL 地址中语言路径之后的部分：即指南 URL 的 /docs/... 部分。例如，要链接到主题“Using Fetch” (https://mdn.org.cn/en-US/docs/Web/API/Fetch_API/Using_Fetch)，指南数组将包含“/docs/Web/API/Fetch_API/Using_Fetch”。
7. "dictionaries" — 列出 API 所属的所有字典的字符串数组。通常，只有被一个以上属性或方法使用的字典才应在此列出，除非它们具有特殊意义或可能需要从多个页面引用。“CryptoKeyPair”将创建一个指向 https://mdn.org.cn/en-US/docs/Web/API/CryptoKeyPair 的链接。

   注意： MDN 正在逐步淘汰单独记录字典。在可能的情况下，这些现在被描述为它们被使用的位置的对象。

8. "types" — 由 API 定义的 typedef 和枚举类型的数组。您可以选择仅列出具有特殊重要性或从多个页面引用的类型，以保持列表简短。

   注意： MDN 正在逐步淘汰单独记录 typedef。在可能的情况下，这些现在被描述为它们被使用的位置的值。

9. "callbacks" — 值是一个数组，其中包含 API 定义的所有回调类型的列表。您可能会发现根本不需要使用此组，即使对于包含回调类型的 API，因为它们通常没有单独记录的价值。

侧边栏使用的标签

一些子成员是根据页面标签自动从子页面中发现的。API 顶级页面在每次渲染侧边栏时都会被抓取，并且会自动为方法（“Method”标签）、属性（“Property”标签）和构造函数（“Constructor”标签）创建条目。

子成员也会根据标签自动添加警告图标。会为实验性（“Experimental”标签）、非标准（“Non Standard”或“Non-standard”标签）或已弃用（“Deprecated”标签）的子成员添加装饰。

有关基于标签的处理的进一步信息，请参阅 APIRef 源代码。

插入侧边栏

在将 API 条目添加到 GroupData.json、将其作为拉取请求提交并将其合并到主仓库后，您可以使用 APIRef 宏将其包含在您的 API 参考页面中，该宏将您在 GroupData 中使用的 API 名称作为参数。例如，WebVR API 的侧边栏在其页面中包含如下内容：

{{APIRef("WebVR API")}}