語法部分

API 參考語法

API 參考頁面的語法部分是手動編寫的，並且可能因所文件的功能而略有不同。該部分以標題（通常是二級標題 ##）開頭，名為“語法”，並且必須包含在參考頁面頂部（緊鄰介紹性材料下方）。標題下方是一個程式碼塊，顯示功能的精確語法，使用程式碼圍欄 ```[標記語言] 類分隔。

以下示例顯示了典型語法部分（用於 JavaScript 函式）的 Markdown 程式碼

## Syntax

```js-nolint
slice()
slice(start)
slice(start, end)
```

一般樣式規則

關於語法塊內標記的幾條規則

• 請勿以分號 ; 結束一行。語法部分不旨在顯示可執行的程式碼。因此，顯示分號沒有意義。

• 請勿在語法塊內（或 MDN 上的任何程式碼示例塊內）使用 <code>。它不僅通常無用，而且我們的標記不希望它，如果您包含它，它將不會以您想要的方式呈現。

• 僅指定函式和引數。以下顯示“已更正”示例

  js

  querySelector(selector)
  // responseStr = element.querySelector(selector)
  
  new IntersectionObserver(callback, options)
  // const observer = new IntersectionObserver(callback, options)
  

建構函式和方法

語法塊

以語法塊開頭，如下所示（來自 IntersectionObserver() 建構函式頁面）

new IntersectionObserver(callback, options)

或如下所示（來自 Document.hasStorageAccess()）

hasStorageAccess()

當方法是靜態的時，例如 URL.createObjectURL()，也提供其介面

URL.createObjectURL(object)

多行/可選引數

可以以多種不同方式使用的方法應擴充套件為多行，顯示所有可能的變體。

每個選項都應單獨成行，省略每個選項的註釋和賦值。例如，Array.prototype.slice() 有兩個可選引數，將如下所示進行文件編寫

slice()
slice(begin)
slice(begin, end)

同樣，對於 CanvasRenderingContext2D.drawImage

drawImage(image, dx, dy)
drawImage(image, dx, dy, dWidth, dHeight)
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

同樣，對於 Date 建構函式

new Date()
new Date(value)
new Date(dateString)
new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

正式語法

語法部分不應使用正式語法符號（使用 BNF）——而應使用上面描述的擴充套件多行格式。

雖然正式符號提供了描述複雜語法的簡潔機制，但許多開發人員並不熟悉它，並且可能與特定程式語言的有效語法衝突。例如，[ ] 既表示“可選引數”又表示 JavaScript Array。您可以在下面 Array.prototype.slice() 的正式語法中看到這一點

arr.slice([begin[, end]])

對於被認為有益的特定情況，可以使用正式通知宣告單獨的正式語法部分。

簡潔語法塊

目的是使語法塊儘可能純粹和明確地定義功能的語法——不要包含任何不相關的語法。例如，您可能會在網站上的許多地方看到這種語法形式來描述 Promise

caches.match(request, options).then((response) => {
  // Do something with the response
})

但是這個版本更簡潔，並且不包含多餘的 Promise.prototype.then() 方法呼叫

match(request, options)

回撥語法塊

對於接受回撥函式的方法，將回調顯示為引數，而不是箭頭函式或 function 表示式。

filter(callbackFn)
filter(callbackFn, thisArg)

然後，在“引數”部分，列出回撥函式的引數及其預期返回值。

- `callbackFn`
  - : A function to execute for each element in the array. It should return a [truthy](/en-US/docs/Glossary/Truthy) value to keep the element in the resulting array, and a [falsy](/en-US/docs/Glossary/Falsy) value otherwise. The function is called with the following arguments:
    - `element`
      - : The current element being processed in the array.
    - `index`
      - : The index of the current element being processed in the array.
    - `array`
      - : The array `filter()` was called upon.

任意數量引數的語法

對於接受任意數量引數的方法，語法塊的編寫方式如下

unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

傾向於從 1 開始編號，這允許編寫諸如“unshift 將 N 個元素新增到陣列開頭”以及“第一個元素”（而不是“第零個元素”）之類的描述。

請注意，始終包含傳遞零個剩餘引數的情況，即使這沒有多大意義。然後，在“引數”部分，這樣寫

- `element1`, …, `elementN`
  - : The elements to add to the front of the array.

當傳遞零個剩餘引數有意義時，在此處新增 {{optional_inline}}。

另一個在剩餘引數之前帶有一些位置引數的示例

splice(start)
splice(start, deleteCount)
splice(start, deleteCount, item1)
splice(start, deleteCount, item1, item2)
splice(start, deleteCount, item1, item2, /* …, */ itemN)

引數部分

接下來，包含一個“引數”子部分，其中以描述列表的形式解釋每個引數應是什麼。包含多個成員的物件引數可以包含巢狀的描述列表，其本身包含對每個成員應是什麼的解釋。可選引數應在其名稱旁邊的描述項中標記為 {{optional_inline}} 宏呼叫。

列表中每個引數的名稱應包含在 Markdown 程式碼圍欄符號 ` ` 中。

返回值部分

接下來，包含一個“返回值”子部分，其中解釋建構函式或方法的返回值是什麼。參見上面的連結作為示例。

如果沒有返回值，請使用以下文字

無 ({{jsxref("undefined")}})。

異常部分

最後，包含一個“異常”子部分，其中解釋了在呼叫建構函式/方法時遇到問題（例如，引數名稱拼寫錯誤或給定錯誤資料型別的值，因為呼叫環境存在問題（例如，嘗試在非安全上下文中執行僅限安全上下文的功能），或由於其他原因）時可能丟擲的異常。

確定方法丟擲哪些異常可能需要仔細查閱規範。通讀規範中關於功能如何操作的逐步解釋通常會提供一份可靠的異常列表以及導致它們丟擲的情況。

異常名稱和解釋應包含在描述列表中。

屬性

值部分

屬性不包含語法部分。相反，新增一個“值”部分，其中包含對屬性值的解釋。描述其資料型別和用途。

異常部分

如果訪問屬性可以丟擲異常，則包含一個“異常”子部分，解釋每個異常；這應該像上面為方法和建構函式描述的那樣設定。

JavaScript 參考語法

JavaScript 內建物件參考頁面遵循與 API 參考頁面相同的基本規則；例如，對於方法和屬性。您可能會注意到一些區別

• 對於具有單個建構函式的內建物件，建構函式語法通常包含在物件著陸頁上。例如，參見 Date。您會注意到靜態方法（存在於 Date 物件本身上的方法）列在“方法”下，而例項方法列在“Date.prototype 方法”下。
• 您還會注意到，在 JavaScript 參考頁面上，沒有引數/異常的方法更可能根本不包含這些子部分。例如，參見 Date.getDate() 和 Date.now()。

CSS 參考語法

屬性

CSS 屬性參考頁面包含一個“語法”部分，該部分以前位於頁面頂部，但現在越來越常見地位於一個包含顯示功能典型用法程式碼塊的部分下方，以及一個用於說明功能作用的即時示例（例如，參見 animation）。

在語法部分內部，您會找到以下內容。

可選解釋文字

一些 CSS 屬性是自解釋的，不需要額外的解釋（例如 color）。另一方面，有些則更復雜，需要解釋語法順序，包括多個值等（參見 animation）。在這種情況下，您可以在任何子部分之前包含額外的解釋。

值部分

接下來，您應該包含一個“值”部分——這包含一個描述列表，解釋構成屬性值的 CSS 值型別。每個值型別都應包含在尖括號中，並且如果存在該值型別的頁面，則連結到 MDN 參考頁面。例如，參見 border 屬性參考——它參考三種值型別，其中只有一種被連結（<color>）。

正式語法

最後一部分，“正式語法”，是使用 {{CSSSyntax}} 宏自動生成的。此宏使用 @webref/css npm 包從 CSS 規範中獲取資料。要在文件中包含正式語法

1. 新增標題，例如：## 正式語法。
2. 將 {{CSSSyntax}} 宏直接放置在此標題下方。

選擇器

選擇器參考頁面的“語法”部分比屬性頁面的語法部分簡單得多。它包含一個使用“語法框”樣式設計的塊，其中顯示了選擇器的基本語法，無論它是一個簡單的關鍵字（例如，:hover），還是一個更復雜的接受引數的函式值（例如，:not()）。有時引數會在語法塊中的後續條目中進行解釋（參見 :nth-last-of-type() 作為示例）。

此塊是根據 MDN 資料倉庫的 CSS 目錄中包含的資料自動生成的。您只需在標題下方包含 CSSSyntax 宏呼叫，它就會處理其餘部分。

唯一複雜之處在於確保所需資料存在。selectors.json 檔案需要包含您正在文件化的選擇器的條目。

您需要透過 fork MDN 資料倉庫，在本地克隆您的 fork，在新分支中進行更改，然後針對上游倉庫提交拉取請求來完成此操作。您可以在此處找到有關使用 Git 的更多詳細資訊。

HTML 參考語法

HTML 參考頁面沒有“語法”部分——語法總是用尖括號括起來的元素名稱，因此不需要它。您需要了解的關於 HTML 元素的主要事情是它們接受哪些屬性以及它們的值可以是什麼，這在單獨的“屬性”部分中介紹。例如，參見 <ol> 和 <video>。

HTTP 參考語法

HTTP 參考語法都是手動建立的，並且因您正在文件化的 HTTP 功能型別而異。

HTTP 標頭/內容安全策略

HTTP 標頭語法（和內容安全策略）在頁面上的兩個單獨部分中進行文件編寫——“語法”和“指令”。

語法部分

“語法”部分顯示標頭的語法外觀，使用“語法框”樣式設計的語法塊，包括正式語法以準確顯示可以在值中包含哪些指令，以什麼順序等。例如，If-None-Match 標頭的語法塊如下所示

If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, …
If-None-Match: *

某些標頭將具有單獨的請求指令、響應指令和擴充套件語法。如果可用，這些必須包含在單獨的語法塊中，每個塊都在自己的子部分下。例如，參見 Cache-Control。

指令部分

“指令”部分包含一個描述列表，其中包含可以在語法中出現的所有指令的名稱和描述。

HTTP 請求方法

請求方法語法非常簡單，只包含一個使用“語法框”樣式設計的語法塊，顯示方法語法的結構。 GET 方法的語法如下所示

GET /index.html

HTTP 響應狀態碼

同樣，HTTP 響應狀態碼的語法非常簡單——一個包含程式碼和名稱的語法塊。例如

404 Not Found

SVG 參考語法

SVG 元素

SVG 元素語法部分不存在——就像 HTML 元素語法部分一樣。每個 SVG 元素參考頁面只包含適用於該元素的屬性列表。例如，參見 <feTile>。

SVG 屬性

SVG 屬性參考頁面也不包含語法部分。

另見

• MDN 中的 Markdown