此页面由社区从英文翻译而来。了解更多并加入 MDN Web Docs 社区。

常用的宏

本页列举了一些 MDN 中的常用宏命令。对于使用这些宏的入门信息，请阅读使用宏这篇文章。

还有一些不常用或只在特定内容中适用，以及一些弃用的宏的信息，参见其它宏。

链接

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

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

链接到术语库

Glossary 这个宏可用于创建指向 MDN 中术语库内一个具体词条的链接。调用这个宏时，有一个必需的参数和一个可选参数。

  1. 术语的名字（比如“HTML”）：{{Glossary("HTML")}} 会指向 HTML。
  2. 可选参数：使用参数中的文本内容，替代术语的名字显示在页面中：{{Glossary("CSS", "层叠样式表")}} 会生成 层叠样式表。

链接到 MDN 的参考文档页面

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

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

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

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

链接到某个 Bug

  • Bugs
    • 通过编号，bug 宏可以指向 bugzilla.mozilla.org 站内相应的 bug，{{Bug(123456)}} 会指向 bug 123456。
    • 类似的，WebkitBug 宏同样可以借助编号，指向 WebKit bug 库里对应的 bug。例如，{{WebkitBug(31277)}} 会指向 WebKit bug 31277。

多页面间的导航栏

Previous、Next 和 PreviousNext 这几个宏可以在页面中创建导航栏，帮助读者按照文章的先后顺序阅读。其中的参数需要填入目标页面在 MDN 中的位置，你可以在页面的网址中找到所需的信息。对于 PreviousNext，需要的两个参数是相应文章的 Wiki 位置。第一个参数用于上一篇文章，第二个参数用于下一篇文章。

代码示例

运行实例

添加侧边栏

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

  • CSSRef 生成 CSS 参考页面的侧边栏。
  • HTMLRef 生成 HTML 参考页面的侧边栏。
  • APIRef 生成 Web API 参考页面的侧边栏。

通用的文章格式化工具

API 文档的内联指示器

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

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

  • isCustomObject 只读
    • 如果此项值为 true，表明该对象是一个自定义对象。
  • parameterX 可选
    • 参数描述

状态和兼容性指示器

无需参数的行内指示器

非标准的

non-standard_inline 插入一个内联标记，表示 API 尚未标准化并且不在标准轨道上。

语法

{{Non-standard_Inline}}

示例
  • 图标：

实验性的

experimental_inline 插入一个内联标记，表示当前 API 没有被广泛地实现，并且在以后可能会改变。

语法

{{Experimental_Inline}}

示例
  • 图标：

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

已弃用

deprecated_inline 会插入一个带有（ ）的标记以不鼓励使用官方已弃用（或已删除）的 API。

语法

{{Deprecated_Inline}}

示例
  • 图标：

页面或章节头部的指示器

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

  • non-standard_header 语法：{{Non-standard_Header}}

    非标准: 该特性是非标准的，请尽量不要在生产环境中使用它！

  • SeeCompatTable 对于一些介绍实验性功能 (en-US)的内容，应当在这些内容前放置此指示器。语法：{{SeeCompatTable}}

    Experimental: 这是一个实验中的功能
    此功能某些浏览器尚在开发中，请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订，所以在未来版本的浏览器中该功能的语法和行为可能随之改变。

  • deprecated_header: {{Deprecated_Header}}

    已废弃: 该特性已经从 Web 标准中删除，虽然一些浏览器目前仍然支持它，但也许会在未来的某个时间停止支持，请尽量不要使用该特性。

  • secureContext_header：应该用于界面页面、API 概览页面和 API 入口点（例如 navigator.xyz）等主要页面，但通常不在方法和属性页面等子页面上使用。语法：{{SecureContext_Header}}

    安全上下文: 此项功能仅在安全上下文(HTTPS), 一些 支持的浏览器.

表明某个功能在 Web Worker 中可用的指示器

AvailableInWorkers 宏插入一个本地化的注释框，表明一个功能在 Web worker 上下文中可用。它还有一个可选参数，当带有 notservice 时，表示该功能在 Web Worker 中可用但在 Servcie Worker 中不可用。

语法
{{AvailableInWorkers}}
{{AvailableInWorkers("notservice")}}
示例

Note: 此特性在 Web Worker 中可用

Note: This feature is available in Web Workers, except for Service Workers