常用的宏
链接
为了简化一些常见超链接的创建工作——如指向站内的技术参考页面、术语库以及其他主题的链接,我们提供了丰富的宏来完成这些工作。
我们推荐使用宏来创建这些常见的链接,这样不但简洁,而且对翻译工作也很友好——使用宏创建的术语库和技术参考链接不需要翻译者再做处理,这些宏可提供正确的链接,使其符合当前页面的语言。
链接到术语库
链接到 MDN 的参考文档页面
下面列出的宏可链接到 MDN 站内不同技术领域的参考文档,如 Javascript、CSS、HTML 元素、SVG 等。
这些宏都很容易上手,大多数情况下只需一个参数——链接的组件的名称。大多数宏也接受第二个可选的、用于修改实际显示的文本的参数(相关的文档可在下方表格中最左列的链接中找到)。
宏 | 所归属的主题页面 | 示例 |
---|---|---|
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 。 |
多页面间的导航栏
Previous
、Next
和 PreviousNext
这几个宏可以在页面中创建导航栏,帮助读者按照文章的先后顺序阅读。其中的参数需要填入目标页面在 MDN 中的位置,你可以在页面的网址中找到所需的信息。对于 PreviousNext
,需要的两个参数是相应文章的 Wiki 位置。第一个参数用于上一篇文章,第二个参数用于下一篇文章。
代码示例
运行实例
EmbedLiveSample
可以在当前页面中嵌入一个代码示例的实际展示效果(使用方法参见运行实例)。LiveSampleLink
创建指向包含页面上代码示例输出的页面的链接,如运行实例中所述。EmbedGHLiveSample
提供了一种新的运行实例编写和使用方式,你可以在 Github 运行实例 (en-US)中了解更多信息。
添加侧边栏
一些有海量子条目的主题,比如技术参考、指南、教程等,通常需要一个单独的主页面提供导航。对于这些主题中的页面,顶部的面包屑导航就显得比较简陋,下面这些模板,可以在页面的左侧,生成对应主题的侧边导航栏。
CSSRef
生成 CSS 参考页面的侧边栏。HTMLSidebar
生成 HTML 参考页面的侧边栏。APIRef
生成 Web API 参考页面的侧边栏。
通用的文章格式化工具
API 文档的内联指示器
optional_inline
和 ReadOnlyInline
被用于 API 文档,通常可以用来描述一个对象的属性是只读的或一个函数的参数是可省略的。
用法:{{optional_inline}}
或 {{ReadOnlyInline}}
。示例:
isCustomObject
只读-
如果此项值为
true
,表明该对象是一个自定义对象。 parameterX
可选-
参数描述
状态和兼容性指示器
无需参数的行内指示器
非标准的
non-standard_inline
插入一个内联标记,表示 API 尚未标准化并且不在标准轨道上。
语法
{{Non-standard_Inline}}
示例
- 图标: 非标准
实验性的
experimental_inline
插入一个内联标记,表示当前 API 没有被广泛地实现,并且在以后可能会改变。
语法
{{Experimental_Inline}}
示例
- 图标: 实验性
代表明确技术参考的行内指示器
页面或章节头部的指示器
下列指示器的含义,类似于上述的内联指示器。这些组件应直接放置在技术参考页面的标题(或面包屑导航栏)下,也可以用于标记页面上的某个小节。
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")}}
示例
备注: 此特性在 Web Worker 中可用
备注: 此特性在 Web Worker(不包括 Service Worker)中可用