使用宏

MDN 运行的 Yari 平台提供了一个宏系统,KumaScript,它使自动化某些任务成为可能。本文提供了有关如何在文章中调用 MDN 的宏的信息。

KumaScript 指南 深入介绍了如何在 MDN 上使用宏,因此本节更多的是简要概述。

宏的实现方式

MDN 上的宏使用服务器执行的 JavaScript 代码实现,使用 Node.js 解释。除此之外,我们还实现了一些库,这些库提供了服务和功能,使宏能够与平台及其内容进行交互。

在内容中使用宏

要使用宏,您需要将对宏的调用用一对双大括号括起来,并带有其参数(如果有)。

{{macroname(parameter-list)}}

关于宏调用的几点说明

  • 宏名称区分大小写,但会尝试更正常见的首字母大写错误;即使宏名称在其中使用大写字母,您也可以使用全小写,并且您可以将名称通常以小写字母开头的宏的首字母大写。
  • 参数用逗号隔开。
  • 如果没有参数,您可以完全省略括号;{{macroname()}}{{macroname}} 是相同的。
  • 数值参数可以加引号,也可以不加引号。由您决定(但是,如果您有一个包含多个小数点的版本号,则需要用引号括起来)。
  • 如果您遇到错误,请仔细检查代码。如果您仍然无法弄清楚发生了什么,请参阅 KumaScript 错误排查 以获得帮助。

宏被大量缓存;对于任何一组输入值(包括参数和环境值,如运行宏的 URL),结果都会被存储并重复使用。这意味着宏实际上只在输入发生变化时才会运行。

宏可以很简单,比如只插入一个较大的文本块或从 MDN 的另一个部分替换内容,也可以很复杂,比如通过搜索网站的各个部分来构建一个完整的索引,对输出进行样式化并添加链接。

您可以在 常用宏 页面上了解我们最常用的宏;您也可以浏览 所有宏的完整源代码。大多数宏源代码在开头都包含注释形式的文档。

另请参阅