path: root/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html

---
title: 常用的宏
slug: MDN/Structures/Macros/Commonly-used_macros
tags:
- CSS
- 参考
- 宏
- 结构
translation_of: MDN/Structures/Macros/Commonly-used_macros
original_slug: MDN/Structures/Macros/Custom_macros
---
<div>{{MDNSidebar}}</div>

<p>本页列举了一些 MDN 中的常用宏命令。对于使用这些宏的入门信息，请阅读<a href="/zh-CN/docs/MDN/Structures/Macros">使用宏</a>这篇文章。</p>

<p>还有一些不常用或只在特定内容中适用，以及一些不赞成使用的宏的信息，参见<a href="/zh-CN/docs/MDN/Structures/Macros/Other">其它宏</a>。对于调整页面样式相关的宏，另见<a href="/zh-CN/docs/MDN/Guidelines/CSS_style_guide">CSS 样式指南</a>。

<h2 id="Linking">链接</h2>

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

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

<h3 id="Glossayr_links">链接到术语库</h3>

<p>正如{{TemplateLink("Glossary")}}这个宏的名字所示，它可用于创建指向 MDN 中<a
    href="/zh-CN/docs/Glossary">术语库</a>内一个具体词条的链接。调用这个宏时，有一个必需的参数和一个可选参数。</p>

<ol>
  <li>术语的名字，比如“HTML”。
    <ul>
      <li><code>\{{Glossary("HTML")}}</code>会指向{{Glossary("HTML")}}。</li>
    </ul>
  </li>
  <li>可选参数：使用参数中的文本内容，替代术语的名字显示在页面中。</li>
  <ul>
    <li><code>\{{Glossary("CSS", "Cascading Style Sheets")}}</code>会指向{{Glossary("CSS", "Cascading Style Sheets")}}。
    </li>
  </ul>
</ol>

<h3 id="Links_to_in-page_sections">链接到页内章节</h3>

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

<ul>
  <li><code>\{{anch("Linking to pages in references","链接到 MDN 的参考文档页面")}}</code></li>
  <li><p>实际效果：{{anch("Linking to pages in references","链接到 MDN 的参考文档页面")}}</p></li>
</ul>

<h3 id="Linking_to_pages_in_references">链接到 MDN 的参考文档页面</h3>

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

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

<table class="standard-table">
  <thead>
    <tr>
      <th>宏</th>
      <th>所归属的主题页面</th>
      <th>示例</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{TemplateLink("CSSxRef")}}</td>
      <td><a href="/zh-CN/docs/Web/CSS/Reference">CSS 参考文档</a> (/Web/CSS/Reference)</td>
      <td><code>\{{CSSxRef("cursor")}}</code>会指向{{CSSxRef("cursor")}}.</td>
    </tr>
    <tr>
      <td>{{TemplateLink("DOMxRef")}}</td>
      <td><a href="/zh-CN/docs/Web/API">DOM 参考文档</a> (/Web/API)</td>
      <td><code>\{{DOMxRef("Document")}}</code>或<code>\{{DOMxRef("document")}}</code>都指向{{DOMxRef("Document")}}。<br>
        <code>\{{DOMxRef("document.getElementsByName()")}}</code>会指向{{DOMxRef("document.getElementsByName()")}}<br>
        <code>\{{DOMxRef("Node")}}</code>会指向{{DOMxRef("Node")}}. <br>
        你可以使用第二个参数控制在页面上实际显示的文本：<code>\{{DOMxRef("document.getElementsByName()","getElementsByName()")}}</code>会生成{{DOMxRef("document.getElementsByName()","getElementsByName()")}}
      </td>
    </tr>
    <tr>
      <td>{{TemplateLink("HTMLElement")}}</code>
      </td>
      <td><a href="/zh-CN/docs/Web/HTML/Element">HTML 元素参考文档</a> (/Web/HTML/Element)</td>
      <td><code>\{{HTMLElement("select")}}</code>会指向{{HTMLElement("select")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("HTMLAttrxRef")}}</td>
      <td>如果只指明了属性的名字，链接会跳转到 <a href="/zh-CN/docs/Web/HTML/Global_attributes">HTML 全局属性</a>页面对应属性的位置。<br/>如果同时指明 HTML 元素和属性名，则会跳转到元素页面下对应属性的位置。</td>
      <td>
        <code>\{{HTMLAttrxRef("lang")}} </code>会指向{{HTMLAttrxRef("lang")}}.<br /><code>\{{HTMLAttrxRef("type","input")}}</code>生成的链接则会跳转到{{HTMLElement("input")}}元素页面下的{{HTMLAttrxRef("type","input")}}属性。
      </td>
    </tr>
    <tr>
      <td>{{TemplateLink("JSxRef")}}</td>
      <td><a href="/zh-CN/docs/Web/JavaScript/Reference">JavaScript 参考文档</a>（/Web/JavaScript/Reference）.</td>
      <td><code>\{{JSxRef("Promise")}}</code>会指向{{JSxRef("Promise")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("SVGAttr")}}</td>
      <td><a href="/zh-CN/docs/Web/SVG/Attribute">SVG 属性参考</a> (/Web/SVG/Attribute).</td>
      <td><code>\{{SVGAttr("d")}}</code>会指向{{SVGAttr("d")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("SVGElement")}}</td>
      <td><a href="/zh-CN/docs/Web/SVG/Element">SVG 元素参考</a> (/Web/SVG/Element).</td>
      <td><code>\{{SVGElement("view")}}</code>会指向{{SVGElement("view")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("HTTPHeader")}}</td>
      <td><a href="/zh-CN/docs/Web/HTTP/Headers">HTTP 消息头</a> (/Web/HTTP/Headers).</td>
      <td><code>\{{HTTPHeader("ACCEPT")}}</code>会指向{{HTTPHeader("ACCEPT")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("HTTPMethod")}}</td>
      <td><a href="/zh-CN/docs/Web/HTTP/Methods">HTTP 请求方法</a> (/Web/HTTP/Methods).</td>
      <td><code>\{{HTTPMethod("HEAD")}}</code>会指向{{HTTPMethod("HEAD")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("HTTPStatus")}}</td>
      <td><a href="/zh-CN/docs/Web/HTTP/Status">HTTP 响应代码</a> (/Web/HTTP/Status)</td>
      <td><code>\{{HTTPStatus("404")}}</code>会指向{{HTTPStatus("404")}}</td>
    </tr>
    <tr>
      <td>{{TemplateLink("event")}}</td>
      <td><a href="/zh-CN/docs/Web/Events">事件参考</a> (/Web/Events)</td>
      <td>
        <div class="notecard note">
          <h4>注意</h4>
          <p>因为事件关联在具体的元素下，这个宏不是特别有用。例如想指向 wheel 事件的页面，需要使用
            <code>\{{DOMxRef("Document.wheel_event")}}</code>：{{DOMxRef("Document.wheel_event")}}
          </p>
        </div>
      </td>
    </tr>
  </tbody>
</table>

<h3 id="Linking_to_bugs">关联到某个 Bug</h3>

<ul>
  <li>Bugs
    <ul>
      <li>通过编号，{{TemplateLink("bug")}}宏可以指向<a href="bugzilla.mozilla.org">bugzilla.mozilla.org</a>站内相应的 bug，<code>\{{Bug(123456)}}</code>会指向{{Bug(123456)}}.</li>
      <li>类似的，{{TemplateLink("WebkitBug")}}宏同样可以借助编号，指向 WebKit bug 库里对应的 bug。例如，<code>\{{WebkitBug(31277)}}</code>会指向{{WebkitBug(31277)}}.</li>
    </ul>
  </li>
</ul>

<h3 id="Navigation_aids_for_multi-page_guides">多页面间的导航栏</h3>

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

<h2 id="Code_samples">代码示例</h2>

<h3 id="Live_samples">动态示例</h3>

<ul>
  <li>{{TemplateLink("EmbedLiveSample")}} 可嵌入一个在<a href="/zh-CN/docs/MDN/Structures/Live_samples">在线示例</a>中描述的代码示例到当前页面上。</li>
  <li>{{TemplateLink("LiveSampleLink")}} 创建指向包含页面上代码示例输出的页面的链接，如<a href="/zh-CN/docs/MDN/Structures/Live_samples">在线示例</a> 中所述。</li>
  <li>{{TemplateLink("EmbedGHLiveSample")}} 提供了一种新的动态示例编写和使用方式，你可以在<a href="/zh-CN/docs/MDN/Structures/Code_examples#github_live_samples">Github动态示例</a>中了解更多信息。</li>
</ul>

<h2 id="Sidebar_generation">添加侧边栏组</h2>

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

<ul>
  <li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li>
  <li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li>
  <li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li>
</ul>

<h2 id="General-purpose_formatting">通用的文章格式化工具</h2>

<h3 id="Inline_indicators_for_API_documentation">API 文档的行内指示器</h3>

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

<p>用法: <code>\{{optional_inline}}</code> 或 <code>\{{ReadOnlyInline}} 。</code>示例：</p>

<dl>
  <dt><code>isCustomObject</code> {{ReadOnlyInline}}</dt>
  <dd>如果此项值为 <code>true</code>，表明该对象是一个自定义对象。</dd>
  <dt>某项参数{{optional_inline}}</dt>
  <dd>参数描述</dd>
</dl>

<h2 id="Status_and_compatibility_indicators">状态和兼容性指示器</h2>

<h3 id="Inline_indicators_with_no_additional_parameters">无需参数的行内指示器</h3>

<h4 id="Non-standard">非标准的</h4>

<p>{{TemplateLink("non-standard_inline")}} 插入一个行内标记，表示 API 尚未标准化并且不在标准轨道上。</p>

<h5 id="Syntax">语法</h5>

<p><code>\{{Non-standard_Inline}}</code></p>

<h5 id="Examples">示例</h5>

<ul>
  <li>图标：{{Non-standard_Inline}}</li>
</ul>

<h4 id="Experimental">实验性的</h4>

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

<h5 id="Syntax_2">语法</h5>

<p><code>\{{Experimental_Inline}}</code></p>

<h5 id="Examples_2"><code>示例</code></h5>

<ul>
  <li>图标：{{Experimental_Inline}}</li>
</ul>

<h3 id="Inline_indicators_that_support_specifying_the_technology">代表明确技术参考的行内指示器</h3>

<h4 id="Deprecated">已弃用</h4>

<p>{{TemplateLink("deprecated_inline")}}会插入一个带有 ({{Deprecated_Inline}}) 的标记以阻止使用官方不推荐使用（或已删除）的 API。</p>

<h5 id="Syntax_3">语法</h5>

<p><code>\{{Deprecated_Inline}}</code></p>

<h5 id="Examples_3">示例</h5>

<ul>
  <li>图标：{{Deprecated_Inline}}</li>
</ul>

<h3 id="Page_or_section_header_indicators">页面或章节头部的指示器</h3>

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

<ul>
  <li>{{TemplateLink("non-standard_header")}}语法：<code>\{{Non-standard_Header}}</code> {{Non-standard_Header}}</li>
  <li>{{TemplateLink("SeeCompatTable")}} 对于一些介绍<a href="/zh-CN/docs/MDN/Guidelines/Conventions_definitions#experimental">实验性功能</a>的内容，应当在这些内容前放置此指示器。语法：<code>\{{SeeCompatTable}}</code> {{SeeCompatTable}}</li>
  <li>{{TemplateLink("deprecated_header")}}: <code>\{{Deprecated_Header}}</code> {{Deprecated_Header}}</li>
  <li>{{TemplateLink("secureContext_header")}}: 应该用于界面页面、API 概览页面和 API 入口点（例如 <code>navigator.xyz</code>）等主要页面，但通常不在方法和属性页面等子页面上使用。语法： <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li>
</ul>

<h3 id="Indicating_that_a_feature_is_available_in_web_workers">表明某个功能在 Web Worker 中可用的指示器</h3>

<p>{{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的注释框，指示一个功能在 <a href="/zh-CN/docs/Web/API/Web_Workers_API">Web worker</a> 上下文中可用。它还有一个可选参数，当带有<code>notservice</code>时，表示该功能在 Web Worker 中可用但在 Servcie Worker 中不可用。</p>

<h5 id="Syntax_4">语法</h5>

<pre>\{{AvailableInWorkers}}
\{{AvailableInWorkers("notservice")}}</pre>

<h5 id="Examples_5">Examples</h5>

<div>
  {{AvailableInWorkers}}
  {{AvailableInWorkers("notservice")}}
</div>