From d5df18417aee4db99e6c36cf14a68a6b7dbcf341 Mon Sep 17 00:00:00 2001 From: Jason Ren <40999116+jasonren0403@users.noreply.github.com> Date: Tue, 19 Sep 2023 14:29:09 +0800 Subject: [PATCH] [zh-cn]: init the translation of 'syntax sections' (#15857) Co-authored-by: A1lo --- .../page_structures/syntax_sections/index.md | 312 ++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 files/zh-cn/mdn/writing_guidelines/page_structures/syntax_sections/index.md diff --git a/files/zh-cn/mdn/writing_guidelines/page_structures/syntax_sections/index.md b/files/zh-cn/mdn/writing_guidelines/page_structures/syntax_sections/index.md new file mode 100644 index 00000000000000..bda54bfa38a55c --- /dev/null +++ b/files/zh-cn/mdn/writing_guidelines/page_structures/syntax_sections/index.md @@ -0,0 +1,312 @@ +--- +title: 语法小节 +slug: MDN/Writing_guidelines/Page_structures/Syntax_sections +--- + +{{MDNSidebar}} + +MDN 参考页面的语法小节包含一个语法框，其定义了某个特性的确切语法（例如，它可以接受哪些参数，哪些参数是可选的）。本文将解释如何编写参考页面的语法框。 + +## API 参考语法 + +API 参考页面的语法小节是手工书写的，并且通常根据所记录特性的不同有所区别。语法小节以命名为“语法”的标题开头（且通常是二级标题 `##`），并且必须在参考页面的顶部包含此小节（在介绍性文字下方）。标题下方是展示该特性准确语法的代码块，以围栏式代码语法 ` ```[标记语言] ` 标记。 + +下面的示例显示了一个典型语法部分（JavaScript 函数）的 Markdown 代码： + +````md +## 语法 + +```js-nolint +slice() +slice(start) +slice(start, end) +``` +```` + +> **备注：** 这里使用的标记语言是 `js-nolint`，其中 `js` 指示了应使用 JavaScript 语法进行高亮。对于 JavaScript 语法部分，也需要指定 `nolint`，因为该部分并不是完全的合法 JavaScript 代码，我们并不想让 linter“修正”它（这里省略了返回值和行尾分号）。 + +### 通用风格规则 + +语法块内的标记应遵循一些规则： + +- **不要**用分号 `;` 结束每行。语法小节不是用来显示可运行代码的。因此，显示分号毫无意义。 +- **不要**在语法块（或在 MDN 的任意示例代码块）内使用 \。它不仅通常毫无用处，而且我们的标记也不需要它，如果包含它，就不会呈现你想要的效果。 +- 只指定函数及其参数，下方是一些“修正过”的示例 + + ```js-nolint + querySelector(selector) + // responseStr = element.querySelector(selector) + + new IntersectionObserver(callback, options) + // const observer = new IntersectionObserver(callback, options) + ``` + +### 构造函数和方法 + +#### 语法块 + +以语法块开头，就像这样（节选自 {{DOMxRef("IntersectionObserver.IntersectionObserver", "IntersectionObserver")}} 构造函数页）： + +```js-nolint +new IntersectionObserver(callback, options) +``` + +或这样（节选自 {{DOMxRef("Document.hasStorageAccess()")}} 页）： + +```js-nolint +hasStorageAccess() +``` + +如果是静态方法，如 {{DOMxRef("URL.createObjectURL()")}}，则一同提供它的接口： + +```js-nolint +URL.createObjectURL(object) +``` + +##### 多行/可选参数 + +可用于多种不同方法的方法应扩展为多行，显示所有可能的变化。 + +每个选项应独立成行，省略每个选项的注释和赋值。例如，{{jsxref("Array.prototype.slice()")}} 有两个可选参数，其文档如下所示： + +```js-nolint +slice() +slice(begin) +slice(begin, end) +``` + +类似的示例是 {{DOMxRef("CanvasRenderingContext2D.drawImage")}}： + +```js-nolint +drawImage(image, dx, dy) +drawImage(image, dx, dy, dWidth, dHeight) +drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) +``` + +{{jsxref("Date")}} 构造函数也是这样： + +```js-nolint +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) +``` + +##### 形式语法 + +语法部分不应使用形式语法符号（使用[巴科斯范式](https://zh.wikipedia.org/wiki/巴科斯范式)），而应使用[如上所述](#多行可选参数)的扩展多行格式。 + +虽然形式化符号为复杂语法的描述提供了一种简洁的机制，但它并不为许多开发人员所熟悉，而且可能与特定编程语言的有效语法相冲突。例如，“`[ ]`”既表示“可选参数”，也表示 JavaScript {{jsxref("Array")}} 。你可以从下面 {{jsxref("Array.prototype.slice()")}} 的形式语法中看到这一点： + +```js-nolint +arr.slice([begin[, end]]) +``` + +在认为有益的特定情况下，可使用形式通知声明单独的**形式语法**部分。 + +##### 使语法块简洁 + +目的是使语法块尽可能纯粹、明确地定义功能的语法，不要包含任何无关的语法。例如，你可能会在网站的许多地方看到这种用于描述 promise 的语法形式： + +```js-nolint +caches.match(request, options).then(function (response) { + // 使用 response 完成一些事情 +}) +``` + +但下面这个版本要简洁得多，而且不包含多余的 {{JSxRef("Promise.prototype.then()")}} 方法调用： + +```js-nolint +match(request, options) +``` + +##### 回调函数语法块 + +对于接受回调函数的方法，要将该回调作为参数展示，而不是箭头函数或 `function` 表达式。 + +```js-nolint +filter(callbackFn) +filter(callbackFn, thisArg) +``` + +然后，在“参数”小节，列出回调函数的参数和期望的返回类型。 + +```md +- `callbackFn` + - : 为数组中的每个元素执行的函数。它应该返回一个[真值](/zh-CN/docs/Glossary/Truthy)以将元素保留在结果数组中，否则返回一个[假值](/zh-CN/docs/Glossary/Falsy)。该函数被调用时将传入以下参数： + - `element` + - : 数组中当前正在处理的元素。 + - `index` + - : 正在处理的元素在数组中的索引。 + - `array` + - : 调用了 `filter()` 的数组本身。 +``` + +##### 接受任意数量参数的语法 + +对于接受任意数量参数的方法，语法块的写法如下： + +```js-nolint +unshift() +unshift(element1) +unshift(element1, element2) +unshift(element1, element2, /* …, */ elementN) +``` + +这里更倾向于从 1 开始编号，这样可以写出“`unshift` 在数组开头添加 N 个元素”这样的描述，也可以写成“第一个元素”（而不是“第零个元素”）。 + +请注意，这里总是包含没有传递剩余参数的情况（即使没有意义）。然后，在“参数”小节中，像这样记录： + +```md +- `element1`、…、`elementN` + - : 添加到数组开头的元素。 +``` + +如果不传递剩余参数具有意义，请在这里添加 `\{{optional_inline}}`。 + +另一个在剩余参数之前有一些位置参数的示例： + +```js-nolint +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 参考页面相同的基本规则，例如方法和属性。你可能会发现一些不同之处： + +- 对于只有一个构造函数的内置对象，构造函数语法通常包含在对象着陆页面中。例如，请参见 {{JSxRef("Date")}}。你会注意到，静态方法（存在于 `Date` 对象本身的方法）列在“方法”（Methods）下，而实例方法列在“Date.prototype 方法”（Date.prototype methods）下。 +- 你还会注意到，没有参数/异常的方法更有可能在 JavaScript 参考页面中完全不包含这些小节。请参见 {{JSxRef("Date.getDate()")}} 和 {{JSxRef("Date.now()")}} 以了解示例。 + +## CSS 参考语法 + +### 属性 + +CSS 属性参考页面包括“语法”小节，该小节过去位于页面顶部，但现在越来越多地位于包含代码块的部分下方，代码块显示了该特性的典型用法，另外还有一个示例来说明该特性的作用（例如，请参见 {{CSSxRef("animation")}}）。 + +> **备注：** 这样做是因为 CSS 的形式语法非常复杂，MDN 的许多读者都不会使用，而且对初学者来说很不方便。真实的语法和示例对大多数人更有用。 + +在该小节中你会找到以下内容。 + +#### 可选说明文字 + +有些 CSS 属性不言自明，无需额外解释（例如 {{CSSxRef("color")}}）。另一方面，有些属性比较复杂，需要解释语法顺序、包含多个值等（参见 {{CSSxRef("animation")}}）。在这种情况下，可以在任何小节之前添加额外的解释。 + +#### 值小节 + +接下来，你应该包含一个“值”小节——该小节包含一个说明列表，解释构成属性值的 CSS 值类型。每种值类型都应该用角括弧括起来，并链接到涵盖该值类型的 MDN 参考页面（如果有相关页面的话）。例如，请参阅 {{CSSxRef("border")}} 属性参考——该属性参考了三种值类型，其中只有一种是链接的（{{CSSxRef("<color>")}}）。 + +#### 形式语法 + +最后一部分，“形式语法”，是根据 [MDN data 仓库](https://github.com/mdn/data)的 CSS 目录中的数据自动生成的。你只需在标题下方加入一个 `CSSSyntax` 宏调用，剩下的就交给它了。 + +唯一的复杂之处在于要确保所需的数据都已存在。[properties.json](https://github.com/mdn/data/blob/main/css/properties.json) 文件需要包含你要记录的属性的条目，而 [types.json](https://github.com/mdn/data/blob/main/css/types.json) 文件需要包含该属性值中使用的所有值类型的条目。 + +为此，你需要分叉 [MDN data 仓库](https://github.com/mdn/data)，在本地克隆你的分叉，在新分支中进行修改，然后向上游仓库提交拉取请求。你可以[在这里找到关于使用 Git 的更多细节](/zh-CN/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables)。 + +### 选择器 + +与属性页面相比，选择器参考页面的“语法”部分要简单得多。它包含一个使用“语法框”样式的块，显示了选择器的基本语法，无论是一个简单的关键字（例如 {{CSSxRef(":hover")}}），还是一个需要参数的更复杂的函数值（例如 {{CSSxRef(":not", ":not()")}}）。有时，参数会在语法块内的另一个条目中进行解释（以 {{CSSxRef(":nth-last-of-type", ":nth-last-of-type()")}} 为例）。 + +该代码块由 [MDN data 仓库](https://github.com/mdn/data)的 CSS 目录中的数据自动生成。你只需在标题下方加入一个 `CSSSyntax` 宏调用，剩下的就交给它了。 + +唯一的复杂之处在于确保你需要的数据已经存在。[selectors.json](https://github.com/mdn/data/blob/main/css/selectors.json) 文件需要包含你要记录的选择器的条目。 + +为此，你需要分叉 [MDN data 仓库](https://github.com/mdn/data)，在本地克隆你的分叉，在新分支中进行修改，然后向上游仓库提交拉取请求。你可以[在这里找到更多关于使用 Git 的细节](/zh-CN/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables)。 + +## HTML 参考语法 + +HTTP 参考语法全部是手工创建的，并根据要记录的 HTTP 特性类型而有所不同。 + +### HTTP 标头/内容安全策略标头 + +HTTP 标头语法（和内容安全策略）在页面的两个独立部分——“语法”和“指令”中进行了说明。 + +#### 语法小节 + +“语法”小节通过使用“语法框”样式的语法块来显示页眉的语法，包括显示值中可以包含哪些指令、顺序如何等的正式语法。例如，{{HTTPHeader("If-None-Match")}} 标头信息的语法块如下所示： + +```http +If-None-Match: +If-None-Match: , , … +If-None-Match: * +``` + +有些标头有单独的请求指令、响应指令和扩展语法。如果有的话，这些语法必须包含在单独的语法块中，每个语法块都有自己的小节。请参阅 {{HTTPHeader("Cache-Control")}} 以了解示例。 + +#### 指令小节 + +“指令”小节包含一个说明列表，其中包含语法中可能出现的所有指令的名称和说明。 + +### HTTP 请求方法 + +请求方法的语法非常简单，只包含一个使用“语法框”样式的语法块，显示方法语法的结构。[GET 方法](/zh-CN/docs/Web/HTTP/Methods/GET)的语法如下： + +```http +GET /index.html +``` + +### HTTP 响应状态码 + +同样，HTTP 响应状态代码的语法非常简单——一个包含代码和名称的语法块。例如： + +```http +404 Not Found +``` + +## SVG 参考语法 + +### SVG 元素 + +SVG 元素语法部分是不存在的——就像 HTML 元素语法部分一样。每个 SVG 元素的参考页面都只是列出了适用于该元素的属性列表。请参见 {{SVGElement("feTile")}} 为例。 + +### SVG 属性 + +SVG 属性参考页面也不包含语法小节。 + +## 参见 + +- [MDN 中的 Markdown 语法](/zh-CN/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#示例代码块)