1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
---
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><span class="seoSummary">本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见<a href="/en-US/docs/MDN/Contribute/Content/Macros">使用宏</a>和<a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_link_macros">使用链接宏</a>。</span>对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Other">其它宏</a>。这里也有一份 <a href="/en-US/docs/templates">MDN 上所有宏的完整列表</a>。</p>
<p>对于适合你使用的样式，另见 <a href="/en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 样式指南</a>。</p>
<h2 id="链接">链接</h2>
<h3 id="创建一个单独的超链接">创建一个单独的超链接</h3>
<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的<strong>链接</strong>按钮创建链接。</p>
<ul>
<li>{{TemplateLink("Glossary")}} 宏创建一个链接指向 MDN <a href="/en-US/docs/Glossary">术语汇编（glossary）</a>里的一个具体的术语词条。这个宏接受一个必须的和两个可选的参数：
<ol>
<li>术语的名称（比如 "HTML"）。</li>
<li>代替术语名称显示在文章中的文本（此项应当尽可能少地使用）。{{optional_inline}}</li>
<li>如果这个参数是明确的并且是非零的，一般用于术语汇编链接的自定义样式将不适用。{{optional_inline}}</li>
</ol>
<p>示例：</p>
<ul>
<li>\{{Glossary("HTML")}} 生成 {{Glossary("HTML")}}</li>
<li>\{{Glossary("CSS", "Cascading Style Sheets")}} 生成 {{Glossary("CSS", "Cascading Style Sheets")}}</li>
<li>\{{Glossary("HTML", "", 1)}} 生成 {{Glossary("HTML", "", 1)}}</li>
</ul>
</li>
</ul>
<h3 id="链接到参考文档页面">链接到参考文档页面</h3>
<p>有各种宏用来链接到 MDN 上特定参考区域里的页面。</p>
<ul>
<li>{{TemplateLink("cssxref")}} 链接到 <a href="/en-US/docs/CSS_Reference" title="en-US/docs/CSS_Reference">CSS 参考</a>里的一个页面。<br>
示例： <code>\{{cssxref("cursor")}}</code>，显示为：{{ cssxref("cursor") }} 。</li>
<li>{{TemplateLink("domxref")}} 链接到 DOM 参考里的页面；如果你在结尾列入了圆括号，这个模板会像一个函数名那样显示这个链接。例如，<span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span> 显示为 {{ domxref("document.getElementsByName()") }} <code>而 \{\{domxref("Node")\}\}</code> 显示为 {{ domxref("Node") }} 。</li>
<li>{{TemplateLink("event")}} 链接到 DOM 事件参考，例如：\{{event("change")}} 显示为 {{event("change")}} 。</li>
<li>{{TemplateLink("HTMLElement")}} 链接到 HTML 参考里的一个 HTML 元素。</li>
<li>{{TemplateLink("htmlattrxref")}} 链接到一个 HTML 属性。如果你只指定属性名，它将是一个全局属性的描述。如果你指定一个属性名和一个元素名，它将是一个具体元素的一个属性名。例如，<code>\{\{htmlattrxref("lang")\}\} </code>将创建链接：{{htmlattrxref("lang")}} 。<code>\{\{htmlattrxref("type","input")\}\}</code> 将创建链接：{{htmlattrxref("type","input")}} 。</li>
<li>{{TemplateLink("jsxref")}} 链接到 <a href="/en-US/docs/Web/JavaScript/Reference" title="en-US/docs/Web/JavaScript/Reference">JavaScript 参考</a>里的一个页面。</li>
<li>{{TemplateLink("SVGAttr")}} 链接到一个特定的 SVG 属性。例如，<code>\{\{SVGAttr("d")\}\}</code> 创建这样的链接： {{SVGAttr("d")}} 。</li>
<li>{{TemplateLink("SVGElement")}} 链接到 SVG 参考里的一个 SVG 元素。</li>
</ul>
<h3 id="链接到漏洞和互联网中继聊天（IRC）">链接到漏洞和互联网中继聊天（IRC）</h3>
<ul>
<li>漏洞
<ul>
<li>通过使用下面的语法 {{TemplateLink("bug")}} 可以让你轻松地链接到 bugzilla.mozilla.org 上的一个漏洞（页面）：<code>\{\{Bug(123456)\}\}</code> 。这将显示：{{ Bug(123456) }} 。</li>
<li>{{TemplateLink("WebkitBug")}} 插入一条指向 WebKit 漏洞数据库中一个漏洞的链接。例如：<code>\{\{WebkitBug(31277)\}\}</code> 插入 {{ WebkitBug(31277) }} 。</li>
</ul>
</li>
<li>{{TemplateLink("IRCLink")}} 插入一条指向特定 IRC 频道的链接，它带有一个提示框标明它是做什么的以及它需要一个 IRC 客户端。</li>
</ul>
<h3 id="用于多页面指南的导航帮助">用于多页面指南的导航帮助</h3>
<p>{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。</p>
<h2 id="代码示例">代码示例</h2>
<h3 id="实样">实样</h3>
<ul>
<li>{{TemplateLink("EmbedLiveSample")}} 让你嵌入一个如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样（Live samples）</a>中描述的代码示例结果到页面上。</li>
<li>{{TemplateLink("LiveSampleLink")}} 创建一个链接指向一个包含（当前）页面上如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样</a>中描述的代码示例结果。</li>
</ul>
<h3 id="附上的示例文件">附上的示例文件</h3>
<ul>
<li>{{TemplateLink("Embed_text")}} 模板允许你嵌入一份附加的文本文件到你的文章主体部分中。这将有助于你让代码段既可下载又能显示在文章内容中。你可以为语法高亮选择地指定一种语言。如果你不指定一种（语言），该文本将无格式化嵌入。第一个参数是被嵌入附件的文件名；第二个（参数），如果支持的话，是用于语法高亮的语言，比如 "javascript", "svg" 或 "cpp" 。</li>
<li>{{TemplateLink("EmbedSVG")}} 嵌入一个附带 XML 文件作为一张 SVG 图像到页面当中。指定附带的 SVG 文件的文件名。你可以和 {{TemplateLink("Embed_text")}} 一同使用来展示源码和相同文件的渲染输出。</li>
</ul>
<h2 id="侧边栏组">侧边栏组</h2>
<p>There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。</p>
<ul>
<li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li>
<li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li>
<li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li>
</ul>
<p>（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）</p>
<h2 id="通用格式化">通用格式化</h2>
<h3 id="API_文档的行内指示器">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>如果为真，指示该对象是一个自定义对象。</dd>
<dt>parameterX {{ optional_inline() }}</dt>
<dd>Blah blah blah...</dd>
</dl>
<h2 id="状态和兼容性指示器">状态和兼容性指示器</h2>
<h3 id="没有附加参数的行内指示器">没有附加参数的行内指示器</h3>
<h4 id="非标准的">非标准的</h4>
<p>{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。</p>
<h5 id="语法"><strong>语法</strong></h5>
<p><code>\{{non-standard_inline}}</code></p>
<h5 id="示例">示例</h5>
<ul>
<li>图标：{{non-standard_inline}}</li>
</ul>
<h4 id="实验性的">实验性的</h4>
<p>{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。</p>
<h5 id="语法_2">语法</h5>
<p><code>\{{experimental_inline}}</code></p>
<h5 id="示例_2"><code>示例</code></h5>
<ul>
<li>图标：{{experimental_inline}}</li>
</ul>
<h3 id="提供明确技术的指示器">提供明确技术的指示器</h3>
<p>在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。</p>
<h4 id="不赞成的">不赞成的</h4>
<p>{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。<strong>注意：</strong>“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。</p>
<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p>
<h5 id="语法_3">语法</h5>
<p><code>\{{deprecated_inline}}</code> <code>或 \{{deprecated_inline("gecko5")}}</code></p>
<h5 id="示例_3">示例</h5>
<ul>
<li>图标：{{deprecated_inline}}</li>
<li>徽标：{{deprecated_inline("gecko5")}}</li>
</ul>
<h4 id="已废弃的">已废弃的</h4>
<p>{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。</p>
<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p>
<h5 id="语法_4">语法</h5>
<p><code>\{{obsolete_inline}}</code> 或<code> \{{obsolete_inline("js1.8.5")}}</code></p>
<h5 id="示例_4">示例</h5>
<ul>
<li>图标：{{obsolete_inline}}</li>
<li>徽标：{{obsolete_inline("js1.8.5")}}</li>
</ul>
<h3 id="模板徽标">模板徽标</h3>
<p>这些宏大多数被用于 <a href="/en-US/docs/WebAPI">WebAPI</a> 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。</p>
<h3 id="页面或区域标头指示">页面或区域标头指示</h3>
<p>这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。</p>
<ul>
<li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li>
<li>{{TemplateLink("SeeCompatTable")}} 应该被放置在介绍实验性功能或兼容性的区域。 示例: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li>
<li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li>
<li>{{TemplateLink("deprecated_header")}} 搭配变量: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li>
<li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li>
<li>{{TemplateLink("obsolete_header")}} 搭配变量: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li>
<li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li>
</ul>
<h3 id="指示一个功能在Web_workers中可用">指示一个功能在Web workers中可用</h3>
<p> {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在<a href="/en-US/docs/Web/API/Web_Workers_API">Web worker</a> 上下文中可用。</p>
<h2 id="版本信息宏">版本信息宏</h2>
<p>这些宏被用来指示这个语段只与一个产品的特定版本有关。</p>
<ul>
<li>{{TemplateLink("gecko_minversion_inline")}}: 示例: {{ gecko_minversion_inline("9.9") }}</li>
<li>{{TemplateLink("fx_minversion_inline")}}:示例: {{ fx_minversion_inline("9.9") }}</li>
</ul>
<ol>
</ol>
<ol>
</ol>
|
