From 2543c30474e6613c73a5d9f15477fcdfb749aa9f Mon Sep 17 00:00:00 2001 From: PocketZ <45301505+pocketdr@users.noreply.github.com> Date: Tue, 24 Aug 2021 03:48:32 +0800 Subject: Update Content of MDN/Structures/Macros (#2173) * Update MDN/Structures/Macros/Commonly-used_macros * fix typo * Fix typo --- .../macros/commonly-used_macros/index.html | 307 ++++++++++++--------- files/zh-cn/mdn/structures/macros/index.html | 18 +- 2 files changed, 190 insertions(+), 135 deletions(-) diff --git a/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html index 15252fc83a..313dbd3a22 100644 --- a/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html +++ b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html @@ -2,213 +2,268 @@ title: 常用的宏 slug: MDN/Structures/Macros/Commonly-used_macros tags: - - CSS - - 参考 - - 宏 - - 结构 +- CSS +- 参考 +- 宏 +- 结构 translation_of: MDN/Structures/Macros/Commonly-used_macros original_slug: MDN/Structures/Macros/Custom_macros ---
{{MDNSidebar}}
-

本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见使用宏和使用链接宏。对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见其它宏。这里也有一份 MDN 上所有宏的完整列表。

+

本页列举了一些 MDN 中的常用宏命令。对于使用这些宏的入门信息，请阅读使用宏这篇文章。还有一些不常用或只在特定内容中适用，以及一些不赞成使用的宏的信息，参见其它宏。在我们的 GitHub Repo 中，可以找到MDN 上所有宏的完整列表。

-

对于适合你使用的样式，另见 CSS 样式指南。

+

对于调整页面样式相关的宏，另见 CSS 样式指南。

-

链接

+

链接

-

创建一个单独的超链接

+

为了简化一些常见超链接的创建工作——如指向站内的技术参考页面、术语库以及其他主题的链接——我们提供了丰富的宏来完成这些工作

-

通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的链接按钮创建链接。

+

我们推荐使用宏来创建这些常见的链接，这样不但简洁，对翻译工作也很友好——使用宏创建的术语库和技术参考链接不需要翻译者再做处理，这些宏可提供正确的链接，使其符合当前页面的语言。

- + -

链接到参考文档页面

+

链接到页内章节

-

有各种宏用来链接到 MDN 上特定参考区域里的页面。

+

{{TemplateLink("anch")}} 可用于创建指向当前文章中其他小节的链接。它和 Glossary 有一个相同作用的可选参数可在翻译时使用。

-

链接到漏洞和互联网中继聊天（IRC）

+

链接到 MDN 的参考文档页面

+ +

下面列出的宏可链接到 MDN 站内不同技术领域的参考文档，如 Javascript,、CSS、HTML、elements、SVG 等。

+ +

这些宏都很容易上手，大多数情况下只需一个参数——所涉及的 Web 组件的名字（如标签、对象、方法、属性等的名字）。在{{anch("Glossayrlinks","术语库")}}中提到的，可修改实际显示的文本的可选参数，也存在于下面大多数宏中。如果你想了解其他参数，表格中最左列的链接中可以查看相关宏的文档。

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
宏所归属的主题页面示例
{{TemplateLink("CSSxRef")}}CSS 参考文档 (/Web/CSS/Reference)\{{CSSxRef("cursor")}}会指向{{CSSxRef("cursor")}}.
{{TemplateLink("DOMxRef")}}DOM 参考文档 (/Web/API)\{{DOMxRef("Document")}}或\{{DOMxRef("document")}}都指向{{DOMxRef("Document")}}。
+ \{{DOMxRef("document.getElementsByName()")}}会指向{{DOMxRef("document.getElementsByName()")}}
+ \{{DOMxRef("Node")}}会指向{{DOMxRef("Node")}}.
+ 你可以使用第二个参数控制在页面上实际显示的文本：\{{DOMxRef("document.getElementsByName()","getElementsByName()")}}会生成{{DOMxRef("document.getElementsByName()","getElementsByName()")}} +
{{TemplateLink("HTMLElement")}} + HTML 元素参考文档 (/Web/HTML/Element)\{{HTMLElement("select")}}会指向{{HTMLElement("select")}}
{{TemplateLink("HTMLAttrxRef")}}如果只指明了属性的名字，链接会跳转到 HTML 全局属性页面对应属性的位置。
如果同时指明 HTML 元素和属性名，则会跳转到元素页面下对应属性的位置。		 + \{{HTMLAttrxRef("lang")}} 会指向{{HTMLAttrxRef("lang")}}.
\{{HTMLAttrxRef("type","input")}}生成的链接则会跳转到{{HTMLElement("input")}}元素页面下的{{HTMLAttrxRef("type","input")}}属性。 +
{{TemplateLink("JSxRef")}}JavaScript 参考文档（/Web/JavaScript/Reference）.\{{JSxRef("Promise")}}会指向{{JSxRef("Promise")}}
{{TemplateLink("SVGAttr")}}SVG 属性参考 (/Web/SVG/Attribute).\{{SVGAttr("d")}}会指向{{SVGAttr("d")}}
{{TemplateLink("SVGElement")}}SVG 元素参考 (/Web/SVG/Element).\{{SVGElement("view")}}会指向{{SVGElement("view")}}
{{TemplateLink("HTTPHeader")}}HTTP 消息头 (/Web/HTTP/Headers).\{{HTTPHeader("ACCEPT")}}会指向{{HTTPHeader("ACCEPT")}}
{{TemplateLink("HTTPMethod")}}HTTP 请求方法 (/Web/HTTP/Methods).\{{HTTPMethod("HEAD")}}会指向{{HTTPMethod("HEAD")}}
{{TemplateLink("HTTPStatus")}}HTTP 响应代码 (/Web/HTTP/Status)\{{HTTPStatus("404")}}会指向{{HTTPStatus("404")}}
{{TemplateLink("event")}}事件参考 (/Web/Events) +
+

注意

+

因为事件关联在具体的元素下，这个宏不是特别有用。例如想指向 wheel 事件的页面，需要使用 + \{{DOMxRef("Document.wheel_event")}}：{{DOMxRef("Document.wheel_event")}} +

+
+
+ +

关联到某个 Bug

-

用于多页面指南的导航帮助

+

多页面间的导航栏

-

{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。

+

+ {{TemplateLink("Previous")}}、{TemplateLink("Next")}}、{{TemplateLink("PreviousNext")}}、{{TemplateLink("PreviousMenuNext")}}这几个宏可以在页面中创建导航栏，帮助读者按照文章的先后顺序阅读。其中的参数需要填入目标页面在 MDN 中的位置，你可以在页面的网址中找到所需的信息。例如 JavaScript 中的继承这个页面，链接地址为“https://developer.mozilla.org/zh-CN/docs/Learn/JavaScript/Objects/Inheritance”，那么它在 MDN 中的位置就可以用Learn/JavaScript/Objects/Object_prototypes描述。

-

代码示例

+

代码示例

-

实样

+

动态示例

-

附上的示例文件

+ - - -

侧边栏组

- -

There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。

+

一些有海量子条目的主题，比如技术参考、指南、教程等，通常需要一个单独的主页面提供导航。对于这些主题中的页面，顶部的面包屑导航就显得比较简陋，下面这些模板，可以在页面的左侧，生成对应主题的侧边导航栏。

-

（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）

- -

通用格式化

+

通用的文章格式化工具

-

API 文档的行内指示器

+

API 文档的行内指示器

-

{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。

+

{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常可以用来描述一个对象的属性是只读的或一个函数的参数是可省略的。 +

-

用法: \{{optional_inline()}} 或 \{{ReadOnlyInline()}} 。示例：

+

用法: \{{optional_inline}} 或 \{{ReadOnlyInline}} 。示例：

-
isCustomObject {{ReadOnlyInline()}}
-
如果为真，指示该对象是一个自定义对象。
-
parameterX {{ optional_inline() }}
-
Blah blah blah...
+
isCustomObject {{ReadOnlyInline}}
+
如果此项值为 true，表明该对象是一个自定义对象。
+
某项参数{{optional_inline}}
+
参数描述
-

状态和兼容性指示器

+

状态和兼容性指示器

-

没有附加参数的行内指示器

+

无需参数的行内指示器

-

非标准的

+

非标准

-

{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。

+

{{TemplateLink("non-standard_inline")}} 指示当前 API 还没有被标准化，也没有进入标准化议程。

-
语法
+
语法

\{{non-standard_inline}}

-
示例
+
示例
-

实验性的

+

实验性的

-

{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。

+

{{TemplateLink("experimental_inline")}} 指示当前 API 没有被广泛支持，且将来可能会有所修改。

-
语法
+
语法

\{{experimental_inline}}

-
示例
+
示例
-

提供明确技术的指示器

- -

在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。

+

代表明确技术参考的行内指示器

-

不赞成的

+

不赞成的

-

{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。注意：“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。

+

{{TemplateLink("deprecated_inline")}}会插入一个带有“不赞成”的行内指示器，即{{Deprecated_Inline}}。这表示不鼓励使用该 API ，或其已经被移除。

-

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+
语法
-
语法
+

\{{deprecated_inline}}>

-

\{{deprecated_inline}} 或 \{{deprecated_inline("gecko5")}}

- -
示例
+
示例
-

已废弃的

- -

{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。

+

页面或章节头部的指示器

-

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+

下列指示器的含义，类似于上述的内联指示器。这些组件应直接放置在技术参考页面的标题（或面包屑导航栏）下，也可以用于标记页面上的某个小节。

-
语法
+