MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

MDN 支持将文章中的示例代码转化为运行实例。运行实例可以包括 HTML、CSS、 JavaScript 的任意组合。注意,“运行”的实例是 非交互性 的。它们仅仅由代码示例生成,只是用来展示示例的输出效果。本文在JavaScript语法的基础上说明了该系统的集体使用。

运行实例系统如何工作

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

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

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

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

宏使用一个特殊的 URL 来取得一个分组中的代码示例:http://url-of-page$samples/group-idgroup-id 指代码所在行级或者块级元素的id。用来展示运行结果的框架(或页面)会运行在沙盒中,在安全条件下实现任何想在网络上实现的功能。当然,在实践中,代码需要针对于包含它的页面,否则会被社区编辑移除。

注意:必须使用宏来展示运行实例的输出。为保安全,MDN 编辑器将会移除直接使用 <iframe> 标签的地方。

每个包含示例代码的 <pre>  段落都有一个 class 指示它由何种语言写成(HTML、CSS 或 JavaScript)。这些 class 的值是“brush: html”、“brush: css”或“brush: js”。这些 class 必须与代码匹配以被维基正确使用。一般情况下,当你在使用编辑器工具栏的语法高亮时候,这些属性会被自动添加。

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

运行实例宏

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

在很多情况下,可以很便捷地使用以上两种宏 EmbedLiveSample 或 LiveSampleLink 。只要代码示例可以通过一个行级元素的id 或一个块级元素的id 的区分开,就可以简单的插入宏来实现功能。

页内运行实例宏

 {{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(block_ID, link_text)}}
block_ID
必需。根据标题或段落的 ID 识别示例。保证正确使用 ID 最好的办法是在页面的目录中查找 URL。
link_text
链接地址文本。

使用运行实例系统

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

在所有这些用例中,必须点击编辑器的“保存更改”(将关闭编辑模式)才能看到运行实例。“预览变更”功能不可展示运行实例。

将片段转为运行实例

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

准备代码示例

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

每段代码都需要包含在正确标记其语言的 <pre> 块中,每块中只能包含一种语言。多数情况下,这些步骤都没问题,不过再检查一遍总是好的。工具栏中 PRE 图标旁的按钮是一个提供选择语法的下拉框(语法高亮)。该选项除了设置语法高亮以外,还标记了代码片段在运行实例系统中的语言。

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

所以确认代码块被正确标记为其所用语言,然后你可以继续了。

注意:当向MDN中粘贴内容时,请注意在粘贴带样式的内容时,可能会带来不需要的样式(比如复制高亮代码)。请尽量避免粘贴带样式的内容,在必须的情况下,请在源码模式中删除不需要的样式,或者使用“粘贴为纯文本”。

插入运行实例宏

当代码准备好并被正确标记之后,需要插入宏来创建 iframe

  1. 点击“插入运行实例框架”按钮(),将会打开一个对话框可以配置。
  2. Document 下方,输入包含实例的文章标题。默认是当前正被编辑的文章,但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。(如果输入文字,将会出现一个部分匹配输入内容文章列表,可以从中选取需要的文章。)

  3. 在 Sections in Document 选项中,选取需要将包含实例的部分。
  4. 点击 OK 按钮,生成并将宏插入到文章中,宏调用代码看起来是这样的:
    {{ EmbedLiveSample('Live_sample_demo') }}

增加新的运行实例

在编辑一个新的一页需要插入运行实例时,编辑器做更多工作。

  1. 点击 Insert Code Sample Template 按钮(),将会出现这样的对话框。
  2. 输入运行实例的标题,请确保标题对于当前页面是有意义的。
  3. 点击 OK。会创建一个新的标题,还有一个空的代码框,可以输入 HTML、CSS 或 JavaScript。
  4. 删除不需要的标题的代码框。
  5. 输入代码

查找需要更新的示例

当查询实例的时候,有三种可能的更新方式。

  • 将一个非运行实例转为运行实例
  • 解决运行实例的缺陷或错误
  • 在技术有变更时,提升或更新运行实例

注意:如果发现包含需要更新到运行实例系统的文章,请为文章增加标签“ NeedsLiveSample ”。

查找需要转为运行实例的示例

MDN 上有很多老版本的并且使用运行实例系统的示例。我们希望可以将多数示例更新到运行实例。这将会提升网站的一致性和可用性。在访问 MDN 时,你一定经常看到这些例子。然而,很难如果你想要找到某个特定的例子来更新,不过有一些方法可以试一试。

运行实例演示

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

可以选取删除任何部分。如果不需要脚本,那么删掉脚本的标题和代码块就可以了。同样,也可以删掉其余任何代码块。

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

HTML

这段 HTML 代码创建了一个段落和几个 DIV 可以展示信息。

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

CSS

这段 CSS 代码为信息增加样式。

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

#item {
  width: 100%;
  font-weight: bold;
  text-align: center;
  font-size: 2em;
}

JavaScript

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

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

这里通过{{EmbedLiveSample('Live_sample_demo')}}来展示上面实例运行的结果。

这是使用外链宏{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}来展示实例运行的结果。

Live sample demo link的集合

文档标签和贡献者

 此页面的贡献者: mhy, jiahui, chrisdavidmills
 最后编辑者: mhy,