From 37d4bce12ec037dfd56f85baad6ad7e7cb50d829 Mon Sep 17 00:00:00 2001 From: allo Date: Thu, 20 Jan 2022 23:00:22 +0800 Subject: mv to .md for live_samples --- files/zh-cn/mdn/structures/live_samples/index.html | 213 --------------------- files/zh-cn/mdn/structures/live_samples/index.md | 213 +++++++++++++++++++++ 2 files changed, 213 insertions(+), 213 deletions(-) delete mode 100644 files/zh-cn/mdn/structures/live_samples/index.html create mode 100644 files/zh-cn/mdn/structures/live_samples/index.md (limited to 'files/zh-cn') diff --git a/files/zh-cn/mdn/structures/live_samples/index.html b/files/zh-cn/mdn/structures/live_samples/index.html deleted file mode 100644 index f5e03c47ef..0000000000 --- a/files/zh-cn/mdn/structures/live_samples/index.html +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: 运行实例 -slug: MDN/Structures/Live_samples -tags: - - Guide - - Intermediate - - MDN Meta - - NeedsTranslation - - Structures - - TopicStub -translation_of: MDN/Structures/Live_samples ---- -
{{MDNSidebar}}

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

- -

运行实例系统如何工作

- -

运行实例系统将所有代码整合为一个集合，再将这个集合融合到一个 HTML 文件中，然后在 内联框架{{HTMLElement("iframe")}} 中渲染这个文件。一个运行实例由两个部分构成：

- - - -

一个代码块的集合，在此上下文中，以行级或块级元素（类似 {{HTMLElement("div")}} ）的 id作为标识。

- - - -

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

- -
-

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

-
- -

每个包含示例代码的 {{HTMLElement("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
-
可选。创建的 {{HTMLElement("iframe")}} 元素的宽度，以 px 为单位。若忽略该项，系统会使用一个合理的默认宽度。请注意，如果需要指定该项，那么必须同时指定高度。
-
height
-
可选。创建的 {{HTMLElement("iframe")}} 元素的高度，以 px 为单位。若忽略该项，系统会使用一个合理的默认高度。请注意，如果需要指定该项，那么必须同时指定宽度。如果仅仅指定了高度和宽度中的一个，那么系统会应用默认尺寸。
-
screenshot_URL
-
可选。截屏 URL 显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用，他们就可以看到结果的快照。如果指定该项，截屏会带着相关标题显示在运行实例之后。
-
page_slug
-
可选。包含示例的页面的代称。若忽略该项，示例将会从宏所在页面拉取。
-
- -
    -
- -

链接运行实例宏

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

使用运行实例系统

- -

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

- -

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

- -

将片段转为运行实例

- -

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

- -

准备代码示例

- -

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

- -

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

- -
-

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

-
- -

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

- -
-

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

-
- -

插入运行实例宏

- -

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

- -
    -
  1. 点击“插入运行实例框架”按钮（），将会打开一个对话框可以配置。
    2. -
  2. -

    在 Document 下方，输入包含实例的文章标题。默认是当前正被编辑的文章，但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。（如果输入文字，将会出现一个部分匹配输入内容文章列表，可以从中选取需要的文章。）

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

增加新的运行实例

- -

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

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

查找需要更新的示例

- -

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

- - - -
-

注意：如果发现包含需要更新到运行实例系统的文章，请为文章增加标签“ 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')}}来展示上面实例运行的结果。

- -

{{EmbedLiveSample('Live_sample_demo')}}

- -

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

- -

{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}的集合

diff --git a/files/zh-cn/mdn/structures/live_samples/index.md b/files/zh-cn/mdn/structures/live_samples/index.md new file mode 100644 index 0000000000..f5e03c47ef --- /dev/null +++ b/files/zh-cn/mdn/structures/live_samples/index.md @@ -0,0 +1,213 @@ +--- +title: 运行实例 +slug: MDN/Structures/Live_samples +tags: + - Guide + - Intermediate + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures/Live_samples +--- +
{{MDNSidebar}}

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

+ +

运行实例系统如何工作

+ +

运行实例系统将所有代码整合为一个集合，再将这个集合融合到一个 HTML 文件中，然后在 内联框架{{HTMLElement("iframe")}} 中渲染这个文件。一个运行实例由两个部分构成：

+ + + +

一个代码块的集合，在此上下文中，以行级或块级元素（类似 {{HTMLElement("div")}} ）的 id作为标识。

+ + + +

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

+ +
+

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

+
+ +

每个包含示例代码的 {{HTMLElement("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
+
可选。创建的 {{HTMLElement("iframe")}} 元素的宽度，以 px 为单位。若忽略该项，系统会使用一个合理的默认宽度。请注意，如果需要指定该项，那么必须同时指定高度。
+
height
+
可选。创建的 {{HTMLElement("iframe")}} 元素的高度，以 px 为单位。若忽略该项，系统会使用一个合理的默认高度。请注意，如果需要指定该项，那么必须同时指定宽度。如果仅仅指定了高度和宽度中的一个，那么系统会应用默认尺寸。
+
screenshot_URL
+
可选。截屏 URL 显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用，他们就可以看到结果的快照。如果指定该项，截屏会带着相关标题显示在运行实例之后。
+
page_slug
+
可选。包含示例的页面的代称。若忽略该项，示例将会从宏所在页面拉取。
+
+ +
    +
+ +

链接运行实例宏

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

使用运行实例系统

+ +

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

+ +

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

+ +

将片段转为运行实例

+ +

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

+ +

准备代码示例

+ +

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

+ +

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

+ +
+

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

+
+ +

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

+ +
+

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

+
+ +

插入运行实例宏

+ +

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

+ +
    +
  1. 点击“插入运行实例框架”按钮（），将会打开一个对话框可以配置。
    2. +
  2. +

    在 Document 下方，输入包含实例的文章标题。默认是当前正被编辑的文章，但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。（如果输入文字，将会出现一个部分匹配输入内容文章列表，可以从中选取需要的文章。）

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

增加新的运行实例

+ +

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

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

查找需要更新的示例

+ +

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

+ + + +
+

注意：如果发现包含需要更新到运行实例系统的文章，请为文章增加标签“ 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')}}来展示上面实例运行的结果。

+ +

{{EmbedLiveSample('Live_sample_demo')}}

+ +

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

+ +

{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}的集合

-- cgit v1.2.3-54-g00ecf