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.club.tw/<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.club.tw/<language-code> — 的末尾，從而允許包含 MDN 上的任何文章。

以下是可用的成員。這些在技術上都是可選的，但強烈建議您不要省略它們，而是包含空陣列。

1. "overview" — 值是一個數組，您可以在其中包含 API 概述頁面的 slug（如果存在）。“Fetch API”將建立一個指向 https://mdn.club.tw/en-US/docs/Web/API/Fetch_API 的連結。
2. "interfaces" — 值是一個數組，您應該在此列出構成該 API 的所有介面。“Response”將建立一個指向 https://mdn.club.tw/en-US/docs/Web/API/Response 的連結。
3. "methods" — 值是一個數組，其中應包含規範新增到與其他 API 關聯的介面的任何方法，例如在 Navigator 或 Window 上建立的例項化方法。如果方法數量眾多，您可以考慮僅列出最受歡迎的方法，或將它們放在列表的開頭。“fetch()”將建立一個指向 https://mdn.club.tw/en-US/docs/Web/API/fetch 的連結。請*不要*列出屬於同一 API 的介面的成員方法。
4. "properties" — 值是一個數組，其中應包含與 API 相關的所有屬性。這可以包括 API 規範中定義的介面的屬性，以及 API 在其他介面上定義的屬性。如果屬性數量眾多，您可以考慮僅列出最受歡迎的屬性，或將它們放在列表的開頭。“Headers.append”將建立一個指向 https://mdn.club.tw/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.club.tw/en-US/docs/Web/API/Fetch_API/Using_Fetch)，指南陣列將包含“/docs/Web/API/Fetch_API/Using_Fetch”。
7. "dictionaries" — 列出 API 所屬的所有字典的字串陣列。通常，只有被一個以上屬性或方法使用的字典才應在此列出，除非它們具有特殊意義或可能需要從多個頁面引用。“CryptoKeyPair”將建立一個指向 https://mdn.club.tw/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")}}