常用的宏
链接
为了简化一些常见超链接的创建工作——如指向站内的技术参考页面、术语库以及其他主题的链接,我们提供了丰富的宏来完成这些工作。
我们推荐使用宏来创建这些常见的链接,这样不但简洁,而且对翻译工作也很友好——使用宏创建的术语库和技术参考链接不需要翻译者再做处理,这些宏可提供正确的链接,使其符合当前页面的语言。
链接到术语库
链接到 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 事件的页面,需要使用
|
链接到某个 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 位置。第一个参数用于上一篇文章,第二个参数用于下一篇文章。
代码示例
运行实例
EmbedLiveSample
可以在当前页面中嵌入一个代码示例的实际展示效果(使用方法参见运行实例)。LiveSampleLink
创建指向包含页面上代码示例输出的页面的链接,如运行实例中所述。EmbedGHLiveSample
提供了一种新的运行实例编写和使用方式,你可以在 Github 运行实例 (en-US)中了解更多信息。
添加侧边栏
通用的文章格式化工具
API 文档的内联指示器
optional_inline
和 ReadOnlyInline
被用于 API 文档,通常可以用来描述一个对象的属性是只读的或一个函数的参数是可省略的。
用法: {{optional_inline}}
或 {{ReadOnlyInline}}
。示例:
isCustomObject
只读- 如果此项值为
true
,表明该对象是一个自定义对象。
- 如果此项值为
parameterX
可选- 参数描述
状态和兼容性指示器
无需参数的行内指示器
非标准的
non-standard_inline
插入一个内联标记,表示 API 尚未标准化并且不在标准轨道上。
语法
{{Non-standard_Inline}}
示例
- 图标: Non-Standard
实验性的
experimental_inline
插入一个内联标记,表示当前 API 没有被广泛地实现,并且在以后可能会改变。
语法
{{Experimental_Inline}}
示例
- 图标: Experimental
代表明确技术参考的行内指示器
已弃用
deprecated_inline
会插入一个带有(
Deprecated
)的标记以不鼓励使用官方已弃用(或已删除)的 API。
语法
{{Deprecated_Inline}}
示例
- 图标: Deprecated
页面或章节头部的指示器
下列指示器的含义,类似于上述的内联指示器。这些组件应直接放置在技术参考页面的标题(或面包屑导航栏)下,也可以用于标记页面上的某个小节。
non-standard_header
语法:{{Non-standard_Header}}
非标准: 该特性是非标准的,请尽量不要在生产环境中使用它!
SeeCompatTable
对于一些介绍实验性功能 (en-US)的内容,应当在这些内容前放置此指示器。语法:{{SeeCompatTable}}
Experimental: 这是一个实验中的功能
此功能某些浏览器尚在开发中,请参考浏览器兼容性表格以得到在不同浏览器中适合使用的前缀。由于该功能对应的标准文档可能被重新修订,所以在未来版本的浏览器中该功能的语法和行为可能随之改变。deprecated_header
:{{Deprecated_Header}}
已废弃: 该特性已经从 Web 标准中删除,虽然一些浏览器目前仍然支持它,但也许会在未来的某个时间停止支持,请尽量不要使用该特性。
secureContext_header
:应该用于界面页面、API 概览页面和 API 入口点(例如navigator.xyz
)等主要页面,但通常不在方法和属性页面等子页面上使用。语法:{{SecureContext_Header}}
表明某个功能在 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