语法小节

MDN 参考页面的语法小节包含一个语法框，其定义了某个特性的确切语法（例如，它可以接受哪些参数，哪些参数是可选的）。本文将解释如何编写参考页面的语法框。

API 参考语法

API 参考页面的语法小节是手工书写的，并且通常根据所记录特性的不同有所区别。语法小节以命名为“语法”的标题开头（且通常是二级标题 ##），并且必须在参考页面的顶部包含此小节（在介绍性文字下方）。标题下方是展示该特性准确语法的代码块，以围栏式代码语法 ```[标记语言] 标记。

下面的示例显示了一个典型语法部分（JavaScript 函数）的 Markdown 代码：

md
## 语法

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

备注： 这里使用的标记语言是 js-nolint，其中 js 指示了应使用 JavaScript 语法进行高亮。对于 JavaScript 语法部分，也需要指定 nolint，因为该部分并不是完全的合法 JavaScript 代码，我们并不想让 linter“修正”它（这里省略了返回值和行尾分号）。

通用风格规则

语法块内的标记应遵循一些规则：

  • 不要用分号 ; 结束每行。语法小节不是用来显示可运行代码的。因此，显示分号毫无意义。
  • 不要在语法块（或在 MDN 的任意示例代码块）内使用 <code>。它不仅通常毫无用处，而且我们的标记也不需要它，如果包含它，就不会呈现你想要的效果。
  • 只指定函数及其参数，下方是一些“修正过”的示例
    js
    querySelector(selector)
// responseStr = element.querySelector(selector)

new IntersectionObserver(callback, options)
// const observer = new IntersectionObserver(callback, options)

构造函数和方法

语法块

以语法块开头，就像这样（节选自 IntersectionObserver 构造函数页）：

js
new IntersectionObserver(callback, options)

或这样（节选自 Document.hasStorageAccess() 页）：

js
hasStorageAccess()

如果是静态方法，如 URL.createObjectURL()，则一同提供它的接口：

js
URL.createObjectURL(object)
多行/可选参数

可用于多种不同方法的方法应扩展为多行，显示所有可能的变化。

每个选项应独立成行，省略每个选项的注释和赋值。例如，Array.prototype.slice() 有两个可选参数，其文档如下所示：

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

类似的示例是 CanvasRenderingContext2D.drawImage：

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

Date 构造函数也是这样：

js
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)
形式语法

语法部分不应使用形式语法符号（使用巴科斯范式），而应使用如上所述的扩展多行格式。

虽然形式化符号为复杂语法的描述提供了一种简洁的机制，但它并不为许多开发人员所熟悉，而且可能与特定编程语言的有效语法相冲突。例如，“[ ]”既表示“可选参数”，也表示 JavaScript Array 。你可以从下面 Array.prototype.slice() 的形式语法中看到这一点：

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

在认为有益的特定情况下，可使用形式通知声明单独的形式语法部分。

使语法块简洁

目的是使语法块尽可能纯粹、明确地定义功能的语法，不要包含任何无关的语法。例如，你可能会在网站的许多地方看到这种用于描述 promise 的语法形式：

js
caches.match(request, options).then(function (response) {
  // 使用 response 完成一些事情
})

但下面这个版本要简洁得多，而且不包含多余的 Promise.prototype.then() 方法调用：

js
match(request, options)
回调函数语法块

对于接受回调函数的方法，要将该回调作为参数展示，而不是箭头函数或 function 表达式。

js
filter(callbackFn)
filter(callbackFn, thisArg)

然后，在“参数”小节，列出回调函数的参数和期望的返回类型。

md
- `callbackFn`
  - : 为数组中的每个元素执行的函数。它应该返回一个[真值](/zh-CN/docs/Glossary/Truthy)以将元素保留在结果数组中，否则返回一个[假值](/zh-CN/docs/Glossary/Falsy)。该函数被调用时将传入以下参数：
    - `element`
      - : 数组中当前正在处理的元素。
    - `index`
      - : 正在处理的元素在数组中的索引。
    - `array`
      - : 调用了 `filter()` 的数组本身。
接受任意数量参数的语法

对于接受任意数量参数的方法，语法块的写法如下：

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

这里更倾向于从 1 开始编号，这样可以写出“unshift 在数组开头添加 N 个元素”这样的描述，也可以写成“第一个元素”（而不是“第零个元素”）。

请注意，这里总是包含没有传递剩余参数的情况（即使没有意义）。然后，在“参数”小节中，像这样记录：

md
- `element1`、…、`elementN`
  - : 添加到数组开头的元素。

如果不传递剩余参数具有意义，请在这里添加 {{optional_inline}}。

另一个在剩余参数之前有一些位置参数的示例：

js
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 对象本身的方法）列在“方法”（Methods）下，而实例方法列在“Date.prototype 方法”（Date.prototype methods）下。
  • 你还会注意到，没有参数/异常的方法更有可能在 JavaScript 参考页面中完全不包含这些小节。请参见 Date.getDate() 和 Date.now() 以了解示例。

CSS 参考语法

属性

CSS 属性参考页面包括“语法”小节，该小节过去位于页面顶部，但现在越来越多地位于包含代码块的部分下方，代码块显示了该特性的典型用法，另外还有一个示例来说明该特性的作用（例如，请参见 animation）。

备注： 这样做是因为 CSS 的形式语法非常复杂，MDN 的许多读者都不会使用，而且对初学者来说很不方便。真实的语法和示例对大多数人更有用。

在该小节中你会找到以下内容。

可选说明文字

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

值小节

接下来，你应该包含一个“值”小节——该小节包含一个说明列表，解释构成属性值的 CSS 值类型。每种值类型都应该用角括弧括起来，并链接到涵盖该值类型的 MDN 参考页面（如果有相关页面的话）。例如，请参阅 border 属性参考——该属性参考了三种值类型，其中只有一种是链接的（<color>）。

形式语法

最后一部分，“形式语法”，是根据 MDN data 仓库的 CSS 目录中的数据自动生成的。你只需在标题下方加入一个 CSSSyntax 宏调用，剩下的就交给它了。

唯一的复杂之处在于要确保所需的数据都已存在。properties.json 文件需要包含你要记录的属性的条目，而 types.json 文件需要包含该属性值中使用的所有值类型的条目。

为此，你需要分叉 MDN data 仓库，在本地克隆你的分叉，在新分支中进行修改，然后向上游仓库提交拉取请求。你可以在这里找到关于使用 Git 的更多细节。

选择器

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

该代码块由 MDN data 仓库的 CSS 目录中的数据自动生成。你只需在标题下方加入一个 CSSSyntax 宏调用，剩下的就交给它了。

唯一的复杂之处在于确保你需要的数据已经存在。selectors.json 文件需要包含你要记录的选择器的条目。

为此，你需要分叉 MDN data 仓库，在本地克隆你的分叉，在新分支中进行修改，然后向上游仓库提交拉取请求。你可以在这里找到更多关于使用 Git 的细节。

HTML 参考语法

HTTP 参考语法全部是手工创建的，并根据要记录的 HTTP 特性类型而有所不同。

HTTP 标头/内容安全策略标头

HTTP 标头语法（和内容安全策略）在页面的两个独立部分——“语法”和“指令”中进行了说明。

语法小节

“语法”小节通过使用“语法框”样式的语法块来显示页眉的语法，包括显示值中可以包含哪些指令、顺序如何等的正式语法。例如，If-None-Match 标头信息的语法块如下所示：

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

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

指令小节

“指令”小节包含一个说明列表，其中包含语法中可能出现的所有指令的名称和说明。

HTTP 请求方法

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

http
GET /index.html

HTTP 响应状态码

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

http
404 Not Found

SVG 参考语法

SVG 元素

SVG 元素语法部分是不存在的——就像 HTML 元素语法部分一样。每个 SVG 元素的参考页面都只是列出了适用于该元素的属性列表。请参见 <feTile> 为例。

SVG 属性

SVG 属性参考页面也不包含语法小节。

参见