API 参考侧边栏
您可以将自定义侧边栏包含在 API 参考页面中，以便它显示指向相关接口、教程和其他仅与该 API 相关的资源的链接。本文介绍了如何操作。
创建侧边栏
您需要执行以下三个步骤来创建您的 API 侧边栏
- 创建您的 API 参考页面。
- 在
GroupData.json文件中添加您特定 API 的条目。 - 使用
APIRef宏将侧边栏插入您希望在其上显示的每个页面。
让我们依次浏览每个步骤。我们将在本文中参考的示例是 Fetch API。
向 GroupData.json 添加条目
GroupData.json 文件保存与 API 参考侧边栏中应显示哪些链接相关的所有数据。当被调用时，APIRef 宏将以参数形式获取给定的 API 名称，在 GroupData.json 中查找该名称，构建相应的侧边栏，并将其插入页面。
要向 GroupData.json 添加条目，您需要
- 确保您拥有 GitHub 帐户。
- 派生 MDN 内容存储库，创建一个新分支以包含您的更改，并将存储库克隆到本地。
- 在开始工作之前检出您的新分支，并在完成后确保将更改推送到该分支。
- 创建一个拉取请求，以便 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 - 以创建显示链接的最终 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 上任何位置的文章。
以下是可用的成员。从技术上讲，这些都是可选的，但强烈建议您不要省略它们，而是包含空数组。
-
"overview"- 值是一个数组，您可以在其中包含 API 概述页面的片段（如果存在）。“Fetch API”会导致创建指向 https://mdn.org.cn/en-US/docs/Web/API/Fetch_API 的链接。 -
"interfaces"- 值是一个数组，您应该在其中列出构成该 API 的所有接口。“Response”会导致创建指向 https://mdn.org.cn/en-US/docs/Web/API/Response 的链接。 -
"methods"- 值是一个数组，其中应包含规范添加到与其他 API 关联的接口的任何方法，例如在Navigator或Window上创建的实例化方法。如果有大量方法，您可能需要考虑仅列出最受欢迎的方法，或将它们放在列表的开头。“fetch()”会导致创建指向 https://mdn.org.cn/en-US/docs/Web/API/fetch 的链接。**不要**列出属于同一 API 拥有的接口的方法。 -
"properties"- 值是一个数组，其中应包含与 API 关联的所有属性。这可能包括 API 规范中定义的接口的成员属性，以及 API 在其他接口上定义的属性。如果有大量属性，您可能需要考虑仅列出最受欢迎的属性，或将它们放在列表的开头。“Headers.append”会导致创建指向 https://mdn.org.cn/en-US/docs/Web/API/Headers/append 的链接。 -
"events"- 值是一个数组，其中应包含 API 的一部分但在**不属于** API 的接口中定义的事件的**标题**（属于 API 中的接口（interfaces）的事件默认记录）。如果有大量事件，您可能需要考虑仅列出最受欢迎的事件，或将它们放在列表的开头。例如，"Document: selectionchange"是 Selection API 的一部分，但Document不是，因此我们将事件添加到数组中，它将从 Selection API 主题链接。 -
"guides"- 值是一个字符串数组，每个字符串都指向一个解释如何使用 API 的指南主题。字符串包含指南 URL 地址在语言路径之后的那个部分：即指南 URL 的/docs/...部分。例如，要链接到https://mdn.org.cn/en-US/docs/Web/API/Fetch_API/Using_Fetch中的“Using Fetch”主题，指南数组将包含“/docs/Web/API/Fetch_API/Using_Fetch”。 -
"dictionaries"- 列出 API 所有字典的字符串数组。通常，只有多个属性或方法使用的字典才会在此处列出，除非它们具有特殊意义或可能需要从多个页面进行引用。“CryptoKeyPair”会导致链接到 https://mdn.org.cn/en-US/docs/Web/API/CryptoKeyPair。**注意：**MDN 正在逐步停止单独记录字典。在可能的情况下，现在在使用它们的地方将其描述为对象。
-
"types"- API 定义的类型定义和枚举类型的数组。您可以选择仅列出那些特别重要的或从多个页面引用的类型定义，以保持列表简洁。**注意：**MDN 正在逐步停止单独记录类型定义。在可能的情况下，现在在使用它们的地方将其描述为值。
-
"callbacks"- 值是一个数组，包含 API 所有定义的回调类型的列表。您可能会发现根本不需要使用此组，即使在包含回调类型的 API 上也是如此，因为通常它们没有单独记录的用处。
侧边栏使用的标签
某些子成员会根据页面标签从子页面自动发现。每次渲染侧边栏时都会抓取顶级 API 下的页面，并为方法（“Method”标签）、属性（“Property”标签）和构造函数（“Constructor”标签）自动创建条目。
子成员也会根据标签自动装饰警告图标。将为实验性（“Experimental”标签）、非标准（“Non Standard”或“Non-standard”标签）或已弃用（“Deprecated”标签）子成员添加装饰。
有关基于标签的处理的更多信息，请访问 APIRef 源代码。