常用的宏

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

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

链接

创建一个单独的超链接

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

• Glossary 宏创建一个链接指向 MDN 术语汇编（glossary）里的一个具体的术语词条。这个宏接受一个必须的和两个可选的参数：
  1. 术语的名称（比如 "HTML"）。
  2. 代替术语名称显示在文章中的文本（此项应当尽可能少地使用）。可选
  3. 如果这个参数是明确的并且是非零的，一般用于术语汇编链接的自定义样式将不适用。可选

  示例：

  • {{Glossary("HTML")}} 生成 HTML
  • {{Glossary("CSS", "Cascading Style Sheets")}} 生成 Cascading Style Sheets
  • {{Glossary("HTML", "", 1)}} 生成 HTML

链接到参考文档页面

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

• cssxref 链接到 CSS 参考里的一个页面。
  示例： {{cssxref("cursor")}}，显示为：cursor 。
• domxref 链接到 DOM 参考里的页面；如果你在结尾列入了圆括号，这个模板会像一个函数名那样显示这个链接。例如，{{domxref("document.getElementsByName()")}} 显示为 document.getElementsByName() 而 {{domxref("Node")}} 显示为 Node 。
• event 链接到 DOM 事件参考，例如：{{event("change")}} 显示为 change 。
• HTMLElement 链接到 HTML 参考里的一个 HTML 元素。
• htmlattrxref 链接到一个 HTML 属性。如果你只指定属性名，它将是一个全局属性的描述。如果你指定一个属性名和一个元素名，它将是一个具体元素的一个属性名。例如，{{htmlattrxref("lang")}} 将创建链接：lang 。{{htmlattrxref("type","input")}} 将创建链接：type 。
• jsxref 链接到 JavaScript 参考里的一个页面。
• SVGAttr 链接到一个特定的 SVG 属性。例如，{{SVGAttr("d")}} 创建这样的链接： d 。
• SVGElement 链接到 SVG 参考里的一个 SVG 元素。

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

• 漏洞
  • 通过使用下面的语法 bug 可以让你轻松地链接到 bugzilla.mozilla.org 上的一个漏洞（页面）：{{Bug(123456)}} 。这将显示：bug 123456 。
  • WebkitBug 插入一条指向 WebKit 漏洞数据库中一个漏洞的链接。例如：{{WebkitBug(31277)}} 插入 WebKit bug 31277 。
• IRCLink 插入一条指向特定 IRC 频道的链接，它带有一个提示框标明它是做什么的以及它需要一个 IRC 客户端。

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

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

代码示例

实样

• EmbedLiveSample 让你嵌入一个如实样（Live samples）中描述的代码示例结果到页面上。
• LiveSampleLink 创建一个链接指向一个包含（当前）页面上如实样中描述的代码示例结果。

附上的示例文件

• Embed_text 模板允许你嵌入一份附加的文本文件到你的文章主体部分中。这将有助于你让代码段既可下载又能显示在文章内容中。你可以为语法高亮选择地指定一种语言。如果你不指定一种（语言），该文本将无格式化嵌入。第一个参数是被嵌入附件的文件名；第二个（参数），如果支持的话，是用于语法高亮的语言，比如 "javascript", "svg" 或 "cpp" 。
• EmbedSVG 嵌入一个附带 XML 文件作为一张 SVG 图像到页面当中。指定附带的 SVG 文件的文件名。你可以和 Embed_text 一同使用来展示源码和相同文件的渲染输出。

侧边栏组

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

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

（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的

通用格式化

API 文档的行内指示器

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

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

isCustomObject 只读

如果为真，指示该对象是一个自定义对象。

parameterX 可选

Blah blah blah...

注意为什么一些页面没有规范表格

大多数 Web 文档页面有规范表格来指示 API 是在哪个规范中明确规定的。然而，出于某些原因一些 API 术语没有规范。也许这些 API （出现的日期）早于正式的规范，或者这些 API 是浏览器特有的因此没有说明。

不管怎样，在这种情况下我们能够给出指示是重要的，所以我们用解释性的文本置于（原本）表格所在的位置。为了帮助工具理解这种情况，你需要使用 WhyNoSpecStart 和 WhyNoSpecEnd 宏来包裹那些文本，像这样：

{{WhyNoSpecStart}}Not part of any specification; this API is Firefox OS specific.

这些宏仅仅是一种对自动化工具（使用）的指南，在渲染内容上并没有可见性的影响。

状态和兼容性指示器

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

非标准的

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

语法

{{non-standard_inline}}

示例

• 图标：

实验性的

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

语法

{{experimental_inline}}

示例

• 图标：

提供明确技术的指示器

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

不赞成的

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

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

语法

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

示例

• 图标：
• 徽标：已废弃 Gecko 5

已废弃的

obsolete_inline 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。{{ js_obsolete_inline("1.8.5") }} 等同于 {{ obsolete_inline("js1.8.5") }} 。对于 js_obsolete_header 也是如此。

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

语法

{{obsolete_inline}} 或 {{obsolete_inline("js1.8.5")}}

示例

• 图标：
• 徽标：已废弃 JavaScript 1.8.5

模板徽标

这些宏大多数被用于 WebAPI 页面。见 Creating new badges 关于创建一个新徽标的信息。

特许的

PrivilegedBadge 被用于火狐系统（Firefox OS）文档来指示特许的 APIs 。

语法

{{PrivilegedBadge}}

示例

Privileged

Page or section header indicators

These templates have the same semantics as their inline counterparts described above. The templates should be placed directly underneath the main page title (or breadcrumb navigation if available) in the reference page. They can also be used to mark up a section on a page.

• non-standard_header: {{Non-standard_header()}}

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

• SeeCompatTable should be used on pages that provide a "Browser compatibility" section. Example: {{SeeCompatTable()}}

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

• deprecated_header: {{deprecated_header()}}

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

• deprecated_header with parameter: {{deprecated_header("gecko5")}}

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

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).
• obsolete_header: {{obsolete_header()}}

  已废弃
  This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

• obsolete_header with parameter: {{obsolete_header("gecko30")}}

  已废弃 Gecko 30 (Firefox 30 / Thunderbird 30 / SeaMonkey 2.27 / Firefox OS 1.4)
  This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Indicating that a feature is available in web workers

The AvailableInWorkers macro inserts a localised note box indicating that a feature is available in a Web worker context.

Version information macros

These macros are used to indicate that content is relevant only to specific versions of a product.

• gecko_minversion_inline: For example:
• fx_minversion_inline: For example:

Macros used on special pages

Download buttons

DownloadButton inserts a green "Download" button into the page. It accepts two parameters:

1. The URL of the destination link
2. The text for the button itself

For example, {{DownloadButton("https://nightly.mozilla.org/", "Download Nightly")}} results in: Download Nightly

FirefoxChannelLink inserts a link to download a specific Firefox channel. The link can be either textual or the channel's icon. The idea behind this macro is that it provides an easy way to link to download Firefox without having to deal with potentially changing "best sources" for these downloads, and lets you use icon buttons without worrying about the icon changing. We can just update the macro and all places using the icons will be updated.

It accepts these parameters:

1. The name of the channel. This is a case-insensitive string, and must be one of "nightly", "aurora", "beta", or "release" (the last one can also be "firefox").
2. The icon size, in pixels. The width of the icon will be set to this, with the height horizontally adjusted to match. If this is zero, the link will be presented as a textual link instead.
3. The text for the link. You can leave this parameter out if you specify an icon size, thereby asking for your link to be an icon.

For example, {{FirefoxChannelLink("aurora", 96)}} results in:

And {{FirefoxChannelLink("beta", 0, "Download Firefox Beta")}} results in: Download Firefox Beta