语法部分

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(function (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 内置对象参考页面遵循与 API 参考页面相同的基本规则；例如，对于方法和属性。你可能会观察到一些差异

• 对于只有一个构造函数的内置对象，构造函数语法通常包含在对象主页上。例如，参见 Date。你会注意到，静态方法（存在于 Date 对象本身上的方法）列在“方法”下，而实例方法列在“Date.prototype 方法”下。
• 你还会注意到，没有参数/异常的方法更有可能在 JavaScript 参考页面上完全不包含这些小节。例如，参见 Date.getDate() 和 Date.now()。

CSS 属性参考页面包含一个“语法”部分，该部分以前位于页面顶部，但现在越来越常见地位于包含显示功能典型用法的代码块的部分下方，以及一个演示功能的实时示例（例如参见 animation）。

在“语法”部分中，你会找到以下内容。

可选的解释文本

有些 CSS 属性是不言自明的，不需要额外的解释（例如 color）。另一方面，有些属性比较复杂，需要解释语法顺序，包括多个值等等（参见 animation）。在这种情况下，你可以在任何小节之前添加额外的解释。

值部分

接下来，你应该包含一个“值”部分——它包含一个描述列表，解释构成属性值的 CSS 值类型。每种值类型应该用尖括号括起来，并链接到涵盖该值类型的 MDN 参考页面（如果存在页面）。例如，参见 border 属性参考——它引用了三种值类型，其中只有一个链接 (<color>)。

正式语法

最后一个部分“正式语法”是从 MDN 数据仓库 的 CSS 目录中的数据自动生成的。你只需要在标题下方包含一个 CSSSyntax 宏调用，它会处理剩下的工作。

唯一的问题是确保你需要的數據存在。 properties.json 文件需要包含你要记录的属性的条目，而 types.json 文件需要包含属性值中使用的所有值类型的条目。

你需要为此分叉 MDN 数据仓库，在本地克隆你的分叉，在新分支中进行更改，然后向 upstream 仓库提交拉取请求。你可以 在这里找到有关使用 Git 的更多详细信息。

选择器参考页面的“语法”部分比属性页面的“语法”部分简单得多。它包含一个使用“语法框”样式的块，显示选择器的基本语法，无论它只是一个简单的关键字（例如 :hover），还是一个采用参数的更复杂的函数值（例如 :not()）。有时参数在语法块中的另一个条目中解释（例如，参见 :nth-last-of-type()）。

此块是从 MDN 数据仓库 的 CSS 目录中的数据自动生成的。你只需要在标题下方包含一个 CSSSyntax 宏调用，它会处理剩下的工作。

唯一的问题是确保你需要的數據存在。 selectors.json 文件需要包含你要记录的选择器的条目。

你需要为此分叉 MDN 数据仓库，在本地克隆你的分叉，在新分支中进行更改，然后向 upstream 仓库提交拉取请求。你可以 在这里找到有关使用 Git 的更多详细信息。

HTML 参考页面没有“语法”部分——语法始终只是用尖括号括起来元素名称，因此不需要它。关于 HTML 元素，你需要了解的主要内容是它们接受哪些属性以及它们的属性值可以是什么，这一点在单独的“属性”部分中介绍。例如，参见 <ol> 和 <video>。

HTTP 参考语法都是手动创建的，并且根据你正在记录的 HTTP 功能类型而有所不同。

HTTP 标头语法（和内容安全策略）在页面上的两个单独的部分中记录——“语法”和“指令”。

语法部分

“语法”部分使用“语法框”样式的语法块显示标头的语法，包括正式语法以显示哪些指令可以包含在值中，以什么顺序等等。例如， If-None-Match 标头的语法块如下所示

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

某些标头将有单独的请求指令、响应指令和扩展语法。如果有，这些必须包含在单独的语法块中，每个块都在它自己的小节下。参见 Cache-Control 以获取示例。

指令部分

“指令”部分包含一个描述列表，其中包含所有可能出现在语法中的指令的名称和描述。

请求方法语法非常简单，只包含一个使用“语法框”样式的语法块，显示方法语法是如何构建的。 GET 方法 的语法如下所示

GET /index.html

同样，HTTP 响应状态码的语法也非常简单——一个包含代码和名称的语法块。例如

404 Not Found

SVG 元素语法部分不存在——就像 HTML 元素语法部分一样。每个 SVG 元素参考页面只包含一个列表，列出可以应用于该元素的属性。例如，参见 <feTile>。

SVG 属性参考页面也不包含语法部分。

• MDN 中的 Markdown