diff options
Diffstat (limited to 'files/zh-cn/mdn/structures/macros/custom_macros/index.html')
| -rw-r--r-- | files/zh-cn/mdn/structures/macros/custom_macros/index.html | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/files/zh-cn/mdn/structures/macros/custom_macros/index.html b/files/zh-cn/mdn/structures/macros/custom_macros/index.html new file mode 100644 index 0000000000..3809bb2094 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/custom_macros/index.html @@ -0,0 +1,222 @@ +--- +title: 常用的宏 +slug: MDN/Structures/Macros/Custom_macros +tags: + - CSS + - 参考 + - 宏 + - 结构 +translation_of: MDN/Structures/Macros/Commonly-used_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> |