语法部分

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