diff --git a/files/zh-cn/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md b/files/zh-cn/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md new file mode 100644 index 00000000000000..ec0c9b6ae91e9d --- /dev/null +++ b/files/zh-cn/mdn/writing_guidelines/howto/write_an_api_reference/sidebars/index.md @@ -0,0 +1,95 @@ +--- +title: API 参考侧边栏 +slug: MDN/Writing_guidelines/Howto/Write_an_API_reference/Sidebars +l10n: + sourceCommit: fc7310a85a8e6d5c0677dfaffba9b8fbbadc94a9 +--- + +{{MDNSidebar}} + +你可以在 API 参考页面上包含一个自定义侧边栏,以便它显示与该 API 相关的接口、教程和其他资源的链接。本文介绍了如何实现。 + +## 创建侧边栏 + +你需要完成以下三个步骤来创建你的 API 侧边栏: + +1. 创建你的 API 参考页面。 +2. 将你的特定 API 的条目添加到 [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) 文件中。 +3. 使用 [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) 宏将侧边栏插入到你想要显示它的每个页面中。 + +让我们依次介绍这三个步骤。本文中我们将以 [Fetch API](/zh-CN/docs/Web/API/Fetch_API) 为示例。 + +### 向 GroupData.json 添加条目 + +`GroupData.json` 文件包含与 API 参考侧边栏中应显示的链接相关的所有数据。在 `APIRef` 宏被调用时,需要将一个 API 名称作为参数传递给它,然后它会在 `GroupData.json` 中查找该名称,构建一个适当的侧边栏,并将其插入到页面中。 + +要在 `GroupData.json` 中添加条目,你需要: + +1. 确保你有一个 [GitHub](https://github.com/) 账户。 +2. 复刻(fork)MDN 内容(content)仓库,再创建一个新的分支来包含你的更改,并将仓库克隆到本地。 +3. 在开始工作前,签出(checkout)你的新分支,并在完成工作后确保你将更改推送到该分支。 +4. 创建拉取请求(pull request),以便 MDN 团队可以审查你的工作,并在必要时提出更改。 + +`GroupData.json` 文件可以在 `files/jsondata/` 目录中找到。查看该文件,你会看到一个巨大的 JSON 结构,其中每个 API 都有自己的成员。名称为 API 名称,值为一个对象,其中包含定义要创建的侧边栏链接的几个子成员。 + +例如,查看 MDN 上的 [Fetch API](/zh-CN/docs/Web/API/Fetch_API) 页面。在 `GroupData.json` 中对应的条目如下所示: + +```json +"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "fetch()" ], + "properties": [], + "events": [] +}, +``` + +如你所见,我们将“Fetch API”作为名称,其对象值中包含了许多子成员。 + +#### GroupData 条目中包含的子成员 + +此部分列出了你可以在 `GroupData` 条目中包含的所有子成员。 + +注意,列在列出的子成员中的大部分值都等同于链接文本,以及附加到主 API 索引页面(`https://developer.mozilla.org//docs/Web/API`)的末尾的别名(slug)以创建显示的链接的最终 URL。因此,例如,“Response”将创建如下链接: + +```html +
  • Response
  • +``` + +这也有些例外。例如,“guides”子成员包含指向与指南/教程相关的 URL。在这种情况下,URL 将附加到 MDN 文档根路径(`https://developer.mozilla.org/`)的末尾,因而允许包含 MDN 上任何位置的文章。 + +以下是可用的成员。这些都是可选的,但强烈建议你不要省略它们,而是包含空数组。 + +1. `"overview"`——该值是一个数组,如果有的话,请在其中包含 API 概述页面的别名(slug)。“Fetch API”会创建如下链接:[https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API](/zh-CN/docs/Web/API/Fetch_API)。 +2. `"interfaces"`——该值是一个数组,你应该在其中列出组成该 API 的所有接口。“Response”会创建如下链接:[https://developer.mozilla.org/zh-CN/docs/Web/API/Response](/zh-CN/docs/Web/API/Response)。 +3. `"methods"`——该值是一个数组,其中应包含由规范添加的与其他 API 相关的接口的任何方法,例如在 {{domxref("Navigator")}} 或 {{domxref("Window")}} 上创建的实例化方法。如果有大量的方法,你可能需要考虑只列出最受欢迎的方法,或者将它们放在列表的前面。“fetch()”会创建如下链接:[https://developer.mozilla.org/zh-CN/docs/Web/API/fetch](/zh-CN/docs/Web/API/fetch)。请*不要*列出属于同一 API 拥有的接口的成员方法。 +4. `"properties"`——该值是一个数组,其中应包含与 API 相关的所有属性。这可以包括 API 规范中定义的接口的成员属性,以及 API 在其他接口上定义的属性。如果有大量的属性,你可能需要考虑只列出最受欢迎的属性,或者将它们放在列表的前面。“Headers.append”会创建如下链接:[https://developer.mozilla.org/zh-CN/docs/Web/API/Headers/append](/zh-CN/docs/Web/API/Headers/append)。 +5. `"events"`——该值是一个数组,其中应包含属于 API 而定义它的接口又*不*属于该 API 的事件的*标题*(属于 API 的接口(`interfaces`)中的事件会被默认记录)。如果有大量的事件,你可能需要考虑只列出最受欢迎的事件,或者将它们放在列表的前面。例如,`"Document: selectionchange"` 属于 [Selection API](/zh-CN/docs/Web/API/Selection_API),但 `Document` 并不属于,所以我们将该事件添加到数组中,[Selection API](/zh-CN/docs/Web/API/Selection_API) 主题会链接到该事件。 +6. `"guides"`——该值是一个字符串数组,其中的每一个都是涉及解释如何使用该 API 的指南的主题。这些字符串包含了指南 URL 在语言路径之后的部分:即,指南 URL 的 `/docs/...` 部分。例如,要链接到位于 `https://developer.mozilla.org/zh-CN/docs/Web/API/Fetch_API/Using_Fetch` 的主题“使用 Fetch”,指南数组中需要包含“/docs/Web/API/Fetch_API/Using_Fetch”。 +7. `"dictionaries"`——该值是一个字符串数组,其中列出了 API 的所有字典。通常,只有被多个属性或方法使用的字典才应该在此列出,除非它们具有特殊意义或可能需要从多个页面引用。“CryptoKeyPair”会创建如下链接:[https://developer.mozilla.org/zh-CN/docs/Web/API/CryptoKeyPair](/zh-CN/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 源代码](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs)。 + +## 插入侧边栏 + +在你将 API 条目添加到 `GroupData.json` 中,并将其作为拉取请求提交且更改已被主仓库接受后,你可以使用 [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) 宏(该宏以你在 GroupData 中为 API 使用的名称作为参数),将其包含在 API 参考页面中。例如,通过以下内容为 [WebVR API](/zh-CN/docs/Web/API/WebVR_API) 添加侧边栏: + +```plain +\{{APIRef("WebVR API")}} +```