运行实例

MDN 支持将文章中的示例代码转化为读者可以实际查看的在线演示。这被称为运行实例,使得用户可以查看代码的实际输出。这使得文档变得更具动态性和指导性。

运行实例可以包括 HTML、CSS 和 JavaScript 的任意组合。注意,“运行”实例是非交互性的。但是,它们确保了示例展现的输出与示例代码相匹配,因为它仅仅由代码实例生成。

运行实例系统如何工作

运行实例系统将所有代码整合为一个集合,再将这个集合融合到一个 HTML 文件中,然后在内联框架 <iframe> 中渲染这个文件。一个运行实例由两个部分构成:

  • 一个代码块组成的集合
  • 一个调用(创建的框架或链接)以展示该代码块结果的宏

一个代码块的“集合”,在此上下文中,以标题或块级元素(类似 <div>)的 id 作为标识。

  • 如果 id 属于一个块级元素,该集合将包含此块级元素包含范围内的所有代码。
  • 如果 id 属于一个标题,该集合将包含此标题之后到下个同级标题之前的所有代码。请注意,子标题下的代码块也会被包含,如果不希望得到这样的效果,可以使用块级元素的 id。

宏使用一个特殊的 URL 来取得一个分组中的代码示例,例如:https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html。总体结构是 https://url-of-page/_sample_.group-id.html,其中的 group-id 指代码所在标题或者块级元素的 id。

用来展示运行结果的框架(或页面)会运行在沙盒中,在安全条件下实现任何想在 web 上实现的功能。当然,在实践中,代码需要针对包含它的页面,MDN 上运行的随意的内容会被社区移除。

备注: 必须使用宏来展示运行实例的输出。

每个包含示例代码的 <pre> 块都有一个 class 指示它由何种语言写成(HTML、CSS 或 JavaScript)。这些 class 的值是“brush: html”、“brush: css”或“brush: js”。这些 class 必须与对应的代码块匹配。

运行实例系统由很多可用选项,我们会分解开来讲解。

运行实例宏

你可以用两种宏来展示运行实例:

在很多情况下,可以很方便地在页面中使用 EmbedLiveSampleLiveSampleLink 宏。只要代码示例可以通过一个标题的 id 或一个块级元素的 id 的区分开,就可以简单的插入宏来实现功能。

页内运行实例(EmbedLiveSample)宏

{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
block_ID

必需。包含示例代码的标题或块级元素的 id。保证 id 正确的最好的办法是在页面的内容列表中查看 URL,也可以通过查看网页源码的方式检查。

width

可选。创建的 <iframe> 元素的宽度,以 px 为单位。若忽略该项,系统会使用一个合理的默认宽度。请注意,如果需要指定该项,那么必须同时指定高度。

height

可选。创建的 <iframe> 元素的高度,以 px 为单位。若忽略该项,系统会使用一个合理的默认高度。请注意,如果需要指定该项,那么必须同时指定宽度。如果仅仅指定了高度和宽度中的一个,那么系统会应用默认尺寸。

screenshot_URL

可选。屏幕截图的 URL,显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用,他们就可以看到结果的快照。如果指定该项,屏幕截图会带着相关标题显示在运行实例旁边。

page_slug

可选。包含示例的页面的代称。若忽略该项,示例将会从宏所在页面获取。

警告: 这个参数已被弃用。请不要再新的示例中使用它,并将其从你找到的示例中移除。我们正在主动移除对这个参数的使用,在移除了所有的使用后,我们将会移除对它的支持。

链接运行实例(LiveSampleLink)宏

{{LiveSampleLink(block_ID, link_text)}}
block_ID

必需。包含示例代码的标题或块级元素的 id。保证使用正确 id 的最好的办法是在页面的内容目录中查找 URL,也可以通过查看网页源码的方式检查。

链接文本。

使用运行实例系统

以下部分描述了一些运行实例系统的常见用例。

将代码片段转为运行实例

一个常见的用例是将 MDN 中已有代码片段转为运行实例。

准备代码示例

第一步是添加代码片段,或根据内容和标记确认已有片段可以成为运行实例。代码片段必须组成一个完整可运行的示例。比如,如果已有 CSS 片段,那么需要添加一段 HTML

每段代码都需要包含在正确标记其语言的 <pre> 块中,一个代码块只能包含一种语言。多数情况下,这些步骤都没问题,不过再检查一遍总是好的。当 <pre> 元素 class 的值为 brush:language-type,且 language-type 是该代码块的语言类型(如:htmlcssjs)时,说明这一步已经完成。

备注: 每种语言的代码可以分布在几个代码块里,所有代码会被拼接起来。这个特性允许一块代码对应一块简介。这样有利于制作教程,比如代码间夹杂着大量解释性的文本。

所以在确认 <pre> 块被正确标记为其所用语言以提供语言的语法高亮之后,你就可以继续了。

运行实例演示

这部分是使用“插入运行实例模板”按钮插入运行实例标题和代码块的结果。每种语言可以有不止一个代码块。同样也不需要有特定的顺序,所有代码会被混合匹配。

可以选择删除任何部分。如果不需要脚本,那么删掉脚本的标题和代码块就可以了。同样,也可以在不再被运行实例宏使用的情况下,删掉代码块的标题(“HTML”、“CSS”或“JavaScript”)。

代码模板插入之后,可以增加一些代码,也可以加入一些注释。

HTML

这段 HTML 代码创建了一个段落和几个块级元素(div)以定位和为信息添加样式。

<p>A simple example of the live sample system in action.</p>
<div class="box">
  <div id="item">Hello world! Welcome to MDN</div>
</div>

CSS

这段 CSS 代码为 box 和其中的文字添加样式。

.box {
  width: 200px;
  border-radius: 6px;
  padding: 20px;
  background-color: #ffaabb;
}

#item {
  font-weight: bold;
  text-align: center;
  font-family: sans-serif;
  font-size: 1.5em;
}

JavaScript

这段代码很简单,只是增加了一个点击事件处理器来弹出信息。

var el = document.getElementById('item');
el.onclick = function() {
  alert('Owww, stop poking me!');
}

结果

这是通过 {{EmbedLiveSample('运行实例演示')}} 来展示上面运行代码块的结果。

这是使用外链宏 {{LiveSampleLink('运行实例演示', '运行实例演示链接')}} 来展示实例运行的结果:

运行实例演示链接

关于运行实例的约定

代码块顺序

添加运行实例时,应对代码块进行排序,以便使第一个代码块对应该示例的主要语言(如果有的话)。例如,在 HTML 参考中添加运行实例时,第一个代码块应该是 HTML;在 CSS 参考中添加时,第一个代码块则应该是 CSS;以此类推。

标题命名

在没有歧义的情况下(如,例子位于“示例”部分中),标题应该简明扼要,仅使用相应语言的名称:HTML、CSS、CSS、JavasScript、SVG 等(见上文)。不应使用如“HTML 内容”或“JavaScript 内容”等标题。但是,如果这样的短标题无法明确内容,可以使用更具体的标题。

使用“结果”块

在不同的代码块之后,请在最后调用 EmbedLiveSample 宏之前使用“结果”块(见上文)。这样,示例的语义对于阅读器或其它解析页面的工具(如:屏幕阅读器、网络爬虫)都会变得更加清晰。