如何編寫 API 參考

準備工作

在開始文件化 API 之前，您應該提前準備和計劃一些事情，而不是等到真正開始編寫時。

先決知識

假設您在閱讀本指南之前對以下內容有相當的瞭解：

• HTML、CSS 和 JavaScript 等 Web 技術。JavaScript 最為重要。
• 閱讀 Web 技術規範。在文件化 API 時，您會經常查閱這些規範。

其他一切都可以在實踐中學習。

必備資源

在開始文件化 API 之前，您應該準備好以下資源：

1. 最新規範：無論是 W3C 推薦規範還是早期編輯草案，您都應該參考涵蓋該 API 的最新可用規範草案（或涵蓋該 API 的多個規範）。通常可以透過 Web 搜尋找到它。最新版本通常會從所有版本的規範中連結，列在“最新草案”或類似標題下。
2. 最新的現代 Web 瀏覽器：這些應該是實驗性/Alpha 版本，例如 Firefox Nightly/Chrome Canary，它們更有可能支援您正在文件化的功能。如果您正在文件化一個新興/實驗性 API，這一點尤其重要。
3. 演示/部落格文章/其他資訊：儘可能多地查詢資訊。
4. 有用的工程聯絡人：找到一個友好的工程聯絡人來詢問有關規範的問題，或者參與 API 標準化或在瀏覽器中實現的人，這非常有幫助。找到他們的好地方是：
   • 如果您在相關公司工作，請查閱您的公司內部通訊錄。
   • 參與該 API 討論的公共郵件列表，例如 Mozilla 的 dev-platform 或 W3C 列表，例如 public-webapps。
   • 規範本身。例如，Web Audio API 規範在頂部列出了作者及其聯絡方式。

花些時間玩轉 API

在文件化 API 的過程中，您會多次回來構建演示，但首先花時間熟悉 API 的工作原理很有用——瞭解主要的介面/屬性/方法是什麼，主要用例是什麼，以及如何用它編寫簡單的功能。

當 API 發生變化時，您需要小心，確保您引用或學習的現有演示沒有過時。檢查演示中使用的主要構造，看它們是否與最新規範匹配。它們可能無法在最新瀏覽器中工作，但這不是一個非常可靠的測試，因為舊功能通常會為了向後相容而繼續受支援。

建立需要編寫或更新的文件列表

API 參考通常包含以下頁面。您可以在我們的頁面型別文章中找到每個頁面包含內容的更多詳細資訊、示例和模板。在開始之前，您應該寫下所有需要建立的頁面列表。

1. 概述頁
2. 介面頁
3. 建構函式頁
4. 方法頁
5. 屬性頁
6. 事件頁
7. 概念/指南頁
8. 示例

概述頁

單個 API 概述頁用於描述 API 的作用、其頂層介面、其他介面中包含的相關功能以及其他高階細節。其名稱和 slug 應為 API 名稱加上“API”字尾。它放置在 API 參考的頂層，作為 https://mdn.club.tw/en-US/docs/Web/API 的子級。

示例

• 標題：Web Audio API
• Slug：Web_Audio_API
• URL：https://mdn.club.tw/en-US/docs/Web/API/Web_Audio_API

介面頁

每個介面也將有自己的頁面，描述介面的目的，列出其包含的任何成員（建構函式、方法、屬性等），並顯示其相容的瀏覽器。頁面的名稱和 slug 應與規範中完全一致的介面名稱相同。每個頁面都放置在 API 參考的頂層，作為 https://mdn.club.tw/en-US/docs/Web/API 的子級。

示例

• 標題：AudioContext
• Slug：AudioContext
• URL：https://mdn.club.tw/en-US/docs/Web/API/AudioContext

• 標題：AudioNode
• Slug：AudioNode
• URL：https://mdn.club.tw/en-US/docs/Web/API/AudioNode

• 我們文件化在實現此介面的物件原型上定義的方法（例項方法）以及在類本身上定義的方法（靜態方法）。在極少數情況下，它們同時存在於同一介面上時，您應該將它們列在頁面上的不同部分（靜態方法/例項方法）。通常只存在例項方法，在這種情況下，您可以將它們放在“方法”標題下。
• 我們不文件化介面的繼承屬性和方法：它們列在各自的父介面上。但我們確實會提示它們的存在。
• 我們確實文件化 mixin 中定義的屬性和方法。有關更多詳細資訊，請參閱mixin 的貢獻指南。
• 如果存在，也會列出特殊的方言化器（toString()）和 JSON 化器（toJSON()）方法。
• 如果相關，也會列出命名建構函式（例如 HTMLImageElement 的 Image()）。

建構函式頁

每個介面有零個或一個建構函式，記錄在介面頁面的子頁面上。它描述了建構函式的作用，並顯示其語法外觀、使用示例、瀏覽器相容性資訊等。其 slug 是建構函式的名稱，與介面名稱完全相同，標題是介面名稱、點號、建構函式名稱，然後是括號。

示例

• 標題：AudioContext.AudioContext()
• Slug：AudioContext
• URL：https://mdn.club.tw/en-US/docs/Web/API/AudioContext/AudioContext

屬性頁

每個介面有零個或多個屬性，記錄在介面頁面的子頁面上。每個頁面描述了屬性的作用，並顯示其語法外觀、使用示例、瀏覽器相容性資訊等。其 slug 是屬性的名稱，標題是介面名稱、點號，然後是屬性名稱。

示例

• 標題：AudioContext.state
• Slug：state
• URL：https://mdn.club.tw/en-US/docs/Web/API/AudioContext/state

方法頁

每個介面有零個或多個方法，記錄在介面頁面的子頁面上。每個頁面描述了方法的作用，並顯示其語法外觀、使用示例、瀏覽器相容性資訊等。其 slug 是方法的名稱，標題是介面名稱、點號、方法名稱，然後是括號。

示例

• 標題：AudioContext.close()
• Slug：close
• URL：https://developer.mozilla.com/en-US/docs/Web/API/AudioContext/close

• 標題：AudioContext.createGain()
• Slug：createGain
• URL：https://mdn.club.tw/en-US/docs/Web/API/AudioContext/createGain

事件頁

將事件文件化為其目標介面的子頁面，並使用 slug eventname_event，標題設定為 Interface: eventName event。

不要為 on 事件處理程式屬性建立頁面。在 eventName_event 頁面上同時提及訪問事件的兩種方式。

示例

• 標題：XRSession: end event
• Slug：end_event
• URL：https://mdn.club.tw/en-US/docs/Web/XRSession/end_event

概念/指南頁

大多數 API 參考至少有一篇指南，有時還會附帶一篇概念頁面。最少，API 參考應包含一篇名為“使用 API 名稱”的指南，它將提供如何使用 API 的基本指南。更復雜的 API 可能需要多篇使用指南來解釋如何使用 API 的不同方面。

如果需要，您還可以包含一篇名為“API 名稱概念”的概念文章，它將解釋與 API 相關的任何概念的理論，開發人員應該理解這些概念才能有效地使用 API。

所有這些文章都應作為 API 概述頁面的子頁面建立。例如，Web Audio 有四篇指南和一篇概念文章：

• https://mdn.club.tw/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API
• https://mdn.club.tw/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API
• https://mdn.club.tw/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics
• https://mdn.club.tw/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.club.tw/en-US/docs/Web/API 的子頁面；例如，AudioContext 的文件將位於 https://mdn.club.tw/en-US/docs/Web/API/AudioContext。每個介面頁面都解釋了該介面的功能，並提供了組成該介面的方法和屬性列表。然後，每個方法和屬性都在其自己的頁面上進行文件化，該頁面作為其所屬介面的子頁面建立。例如，BaseAudioContext/currentTime 文件位於 https://mdn.club.tw/en-US/docs/Web/API/AudioContext/currentTime。

建立頁面

現在，根據以下結構建立您需要的頁面。我們的 MDN 內容 README 包含建立新文件的說明，我們的 頁面型別指南包含可能有用​​的更多示例和頁面模板。

概述頁面的結構

API 登陸頁面的長度差異很大，具體取決於 API 的大小，但它們都將具有基本相同的功能。請參閱 https://mdn.club.tw/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. 功能狀態：如果需要，將自動新增一個指示功能狀態（例如已棄用、非標準或實驗性）的橫幅。為此，您需要更新 browser-compat-data 倉庫中的狀態。

3. 描述：介面頁面的第一段應提供對介面總體目的的簡短簡潔描述。如果需要任何其他描述，您可能還想包含幾段。要包含的顯而易見的額外資訊是其預設/初始值，以及它是否是隻讀的。如果介面實際上是一個字典，您應該使用該術語而不是“介面”。

4. 繼承圖：使用 {{InheritanceDiagram}} 宏嵌入介面的 SVG 繼承圖。

5. 屬性列表、方法列表：這些部分應標題為“屬性”和“方法”，並提供指向（使用 {{domxref}} 宏）該介面的每個屬性/方法的參考頁面的連結，以及對每個屬性/方法功能的描述。這些應使用描述/定義列表進行標記。每個描述都應簡短簡潔——如果可能，一句話即可。請參閱“使用 {{domxref}} 宏引用其他 API 功能”部分，以更快地建立指向其他頁面的連結。

   在兩個部分的開頭，在屬性/方法列表的開頭之前，用斜體表示繼承，使用適當的句子：

   • 此介面未實現任何特定屬性，但繼承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的屬性。
   • 此介面也繼承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的屬性。
   • 此介面未實現任何特定方法，但繼承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的方法。
   • 此介面也繼承了 {{domxref("XYZ")}} 和 {{domxref("XYZ2")}} 的方法。

   注意： 只讀屬性應包含 {{ReadOnlyInline}} 宏，它會建立一個精美的“只讀”徽章，包含在其 {{domxref}} 連結的同一行（在 {{experimental_inline}}、{{non-standard_Inline}} 和 {{deprecated_inline}} 宏之後，如果需要這些宏）。

6. 示例：包含程式碼列表以展示 API 主要功能的典型用法。您不應該列出所有程式碼，而應該列出其有趣的部分。對於完整的程式碼列表，您可以引用包含完整示例的 GitHub 倉庫，並且還可以連結到使用 GitHub gh-pages 功能建立的即時示例（只要它只使用客戶端程式碼）。如果示例是視覺化的，您還可以使用 MDN 即時示例功能使其在頁面中即時可播放。

7. 規範表：此時您需要包含一個規範表——有關更多詳細資訊，請參閱“建立規範參考表”部分。

8. 瀏覽器相容性：現在您需要包含一個瀏覽器相容性表。有關詳細資訊，請參閱相容性表。

9. Polyfill：如果合適，請包含此部分，提供 polyfill 程式碼，即使在不支援 API 的瀏覽器上也能使用該 API。如果沒有 polyfill 或不需要，則完全省略此部分。

10. 另請參閱：“另請參閱”部分是包含在學習此技術時可能有用​​的更多連結的好地方，包括 MDN（和外部）教程、示例、庫等。我們對連結到外部來源的政策很寬鬆，但請注意：

    • 不要包含與 MDN 中另一個頁面資訊相同的頁面；請連結到該頁面。
    • 不要列出作者姓名——我們是一個作者中立的文件網站。連結到文件；作者姓名將在那裡顯示。
    • 特別注意部落格文章：它們往往會過時（舊語法、錯誤的相容性資訊）。僅當它們具有在維護的文件中找不到的明確附加價值時才連結到它們。
    • 不要使用“參閱……瞭解更多資訊”或“點選……”等動作動詞，您不知道您的讀者是否能夠看到或點選連結（例如在文件的紙質版本上）。

介面頁面示例

以下是介面頁面的示範性示例：

• 來自 Fetch API 的 Request。
• 來自 Web Speech API 的 SpeechSynthesis。

屬性頁面的結構

將您的屬性頁面建立為其所在介面的子頁面。複製另一個屬性頁面的結構作為新頁面的基礎。

編輯屬性頁面名稱以遵循 Interface.property_name 約定。

屬性頁面必須包含以下部分：

1. 標題：頁面的標題必須是 InterfaceName.propertyName。介面名稱必須以大寫字母開頭。儘管介面在 JavaScript 中是在物件原型上實現的，但我們不在標題中包含 .prototype.，就像我們在 JavaScript 參考中那樣。

2. {{APIRef}}：在每個屬性頁面的第一行包含 {{APIRef}} 宏，並以 API 名稱作為引數，例如 {{APIRef("Web Audio API")}}。此宏用於在介面頁面的左側構建一個參考選單，包括屬性和方法，以及 GroupData 宏中定義的其他快速連結（如果您的 API 尚未列出，請要求某人將其新增到現有 GroupData 條目中，或建立一個新條目）。選單將如下圖所示。

3. 功能狀態：如果需要，將自動新增一個指示功能狀態（例如已棄用、非標準或實驗性）的橫幅。為此，您需要更新 browser-compat-data 倉庫中的狀態。

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（和外部）教程、示例、庫等，儘管將其新增到介面參考頁面可能更有用。

屬性頁面示例

以下是屬性頁面的示範性示例：

• 來自 Fetch API 的 Request.method。
• 來自 Web Speech API 的 SpeechSynthesis.speaking。

方法頁面的結構

將您的方法頁面建立為其所在介面的子頁面。複製另一個方法頁面的結構作為新頁面的基礎。

方法頁面需要以下部分：

1. 標題：頁面的標題必須是 InterfaceName.method()（帶兩個末尾括號），但 slug（頁面 URL 的末尾）不得包含括號。此外，介面名稱必須以大寫字母開頭。儘管介面在 JavaScript 中是在物件原型上實現的，但我們不在標題中包含 .prototype.，就像我們在 JavaScript 參考中那樣。

2. {{APIRef}}：在每個方法頁面的第一行包含 {{APIRef}} 宏，並以 API 名稱作為引數，例如 {{APIRef("Web Audio API")}}。此宏用於在介面頁面的左側構建一個參考選單，包括屬性和方法，以及 GroupData 宏中定義的其他快速連結（如果您的 API 尚未列出，請要求某人將其新增到現有 GroupData 條目中，或建立一個新條目）。選單將如下圖所示。

3. 功能狀態：如果需要，將自動新增一個指示功能狀態（例如已棄用、非標準或實驗性）的橫幅。為此，您需要更新 browser-compat-data 倉庫中的狀態。

4. 描述：方法頁面的第一段應提供方法總體目的的簡短簡潔描述。如果需要任何其他描述，您可能還想包含幾段。要包含的顯而易見的額外資訊是其預設引數值、方法所依賴的任何理論以及引數值的作用。

   第一句話的開頭必須遵循以下結構：

   InterfaceName.method() 方法介面……

   注意： InterfaceName.method() 應以 <code> 標籤包裹，並且在第一次使用時還應加粗（<strong>）。

5. 語法：“語法”部分應包含 2-3 行示例——通常只是介面的構造，然後是介面方法的呼叫。

   語法應採用以下形式：

   method(param1, param2, …)

   “語法”部分應包含三個子部分（請參閱 SubtleCrypto.sign() 獲取示例）：

   • “引數”：這應包含一個定義列表（或無序列表），其中命名並描述了方法接受的不同引數。對於可選引數，您應該在引數名稱旁邊包含 Optional 宏。如果沒有引數，則應省略此部分。
   • “返回值”：這應說明該方法具有的返回值，無論是雙精度浮點數或布林值等簡單值，還是像另一個介面物件這樣更復雜的值，在這種情況下，您可以使用 {{domxref}} 宏連結到涵蓋該介面的 MDN API 頁面（如果存在）。方法可能不返回任何內容，在這種情況下，返回值應寫為“{{jsxref('undefined')}}”（在渲染頁面中將顯示為：undefined）。
   • “異常”：這應該列出在呼叫方法時可能引發的不同異常以及導致它們的情況。如果沒有異常，則應省略此部分。

6. 示例：包含程式碼列表以展示所討論方法的典型用法。您不應該列出所有程式碼，而應該列出其有趣的部分。對於完整的程式碼列表，您應該引用包含完整示例的 GitHub 倉庫，並且還可以連結到使用 GitHub gh-pages 功能建立的即時示例（只要它只使用客戶端程式碼）。如果示例是視覺化的，您還可以使用 MDN 即時示例功能使其在頁面中即時可播放。

7. 規範表：此時您需要包含一個規範表——有關更多詳細資訊，請參閱“建立規範參考表”部分。

8. 瀏覽器相容性：現在您需要包含一個瀏覽器相容性表。有關詳細資訊，請參閱相容性表。

方法頁面示例

以下是方法頁面的示範性示例：

• 來自 Web Animations API 的 Document.getAnimations。
• 來自 Fetch API 的 fetch()。

側邊欄

建立 API 參考頁面後，您需要插入正確的側邊欄以將頁面關聯起來。我們的API 參考側邊欄指南解釋瞭如何操作。