MDN 上的代码示例
在 MDN 上，您会看到大量代码示例，用于演示我们所记录的 Web 平台功能的使用方法。本文档将介绍您可以向页面添加代码示例的方式，以及您可以使用的类型以及何时使用它们。
注意： 本页面介绍代码如何包含在 MDN 页面中。如果您想了解在 MDN 页面中添加代码的语法检查和样式提示，请参阅我们的 代码风格指南。
MDN 上有哪些类型的代码示例？
有四种类型的代码示例可供使用
何时应使用每种示例？
每种类型的代码示例都有其自身的用例
- 如果您需要展示代码，并且在已发布的页面上展示代码结果并不重要，或者您正在文章中展示一个中间步骤，那么静态示例会很有用。读者通常会查找这些显示功能用法的代码块，以便他们可以将一个最小化的示例复制并粘贴到他们的项目中。此外，您可能需要一个静态代码块来演示一个 API 或一项功能，该功能作为实时示例效果不佳。
- 如果您想展示源代码，然后展示其运行效果，并且不太在意它是否是一个独立的示例，那么实时示例会很有用。它们很有用，因为您只需要更新一次代码，就可以更新页面上的代码块和并排显示的实时结果。
- 交互式示例用于参考页面。每页仅限使用一次，并且必须位于页面介绍之后的特定位置。它们对于展示某个功能的常见或实际用途非常有用。
- 当您有一个想要嵌入的现有示例，但不想显示其源代码，并且/或您想确保该示例以独立形式提供时，GitHub 嵌入会很有用。因为页面上的代码和源代码在两个不同的位置，所以维护成本更高。
一般准则
在添加或更新 MDN 上的示例时，需要牢记样式和内容方面的考虑因素。
- 在页面上放置示例时，请尽量确保涵盖您正在撰写的 API 或概念的所有功能或选项。至少，应演示最常见选项或属性。
- 在每个示例之前，请解释该示例的作用以及它为何有趣或有用。
- 在每段代码之后，解释其作用。
- 如果可能，将大型示例分解成较小的部分。例如，“实时示例”系统会在运行示例之前自动将所有代码合并在一起，因此您可以实际将 JavaScript、HTML 和/或 CSS 分成更小的部分，并在每个部分之后添加描述性文本。这是帮助更清晰地解释长篇或复杂代码的绝佳方法。
- 超越演示 API 或技术中的每个部分如何工作。考虑您可能想尝试演示的实际用例。
静态示例
静态示例是显示功能在源代码中外观的代码块。这些示例使用 Markdown 的“代码围栏”添加到页面中，如 示例代码块中所述。在文档页面中使用时，它们看起来像这样
// This is a JS example
const test = "Hello";
console.log(test);
交互式示例
InteractiveExample 宏用于在 MDN 参考页面的顶部嵌入交互式示例。它们适用于想要尝试示例但又不想通读整个主题或功能文章的读者。
InteractiveExample 宏接受一个字符串作为示例的标题，后跟一个关键字来指定示例的高度。要包含在示例中的代码块出现在宏调用之后，并在代码块语言后的信息字符串中包含关键字 interactive-example。JavaScript Array.concat() 的用法是此宏的一个很好的例子，在 markdown 源代码中看起来像这样
{{InteractiveExample("JavaScript Demo: Array.concat()", "shorter")}}
```js interactive-example
const array1 = ["a", "b", "c"];
const array2 = ["d", "e", "f"];
const array3 = array1.concat(array2);
console.log(array3);
// Expected output: Array ["a", "b", "c", "d", "e", "f"]
```
交互式示例有一些限制
- 它们是针对特定技术专门设计的 — JavaScript 的 UI 与 CSS 的 UI 不同，并且它们仅能独立说明一项技术。如果您想演示如何结合使用特定的 HTML/CSS/JS 结构，则不适合。
- 它们不适用于大型代码示例 — UI 支持一系列固定高度，这对于简短（例如 10-15 行）的示例来说效果最好。
- 一个 MDN 页面只能有一个交互式示例。
实时示例
实时示例使用 EmbedLiveSample 宏插入到页面中。一个 {{EmbedLiveSample}} 宏从页面中获取代码块，将它们组合成一个 <iframe>，并将结果插入到页面中。有关更多信息，请参阅 实时示例指南。
GitHub 实时示例
GitHub 实时示例使用 EmbedGHLiveSample 宏嵌入到页面中。一个 {{EmbedGHLiveSample}} 获取指定 URL（必须是MDN GitHub 存储库）的内容，并将其作为一个 <iframe> 插入到页面中。
该宏有三个参数
- 要嵌入的文档的 URL — 此 URL 相对于 MDN 组织，其顶级目录位于
https://mdn.github.io/。因此，此参数需要包含该 URL 之后的部分，例如my-subdirectory/example.html。如果文件名是index.html，则可以省略。 <iframe>的宽度，可以表示为百分比或像素。<iframe>的高度，可以表示为百分比或像素。
让我们来看一个例子。假设我们想嵌入位于 https://mdn.github.io/learning-area/css/styling-boxes/backgrounds/ 的代码。我们可以使用以下调用
{{EmbedGHLiveSample("learning-area/css/styling-boxes/backgrounds/", '100%', 100)}}
渲染后看起来是这样的