代码示例

MDN 上有四种类型的代码示例可用

• 静态示例 - 纯代码块，可能包含屏幕截图，以静态方式显示此类代码在运行时的结果。
• 交互式示例 - 我们创建 动态交互式示例 的系统，这些示例展示了代码的动态运行，同时还允许你动态更改代码以查看其效果并轻松复制结果。
• 传统的 MDN "动态样本" - 一个宏，它接收纯代码块，将它们动态地放入 <iframe> 元素内的文档中，并将其嵌入到页面中以显示代码的动态运行。
• GitHub "动态样本" - 一个宏，它接收 MDN 组织 内的 GitHub 仓库中的文档，将其放入 <iframe> 元素中，并将其嵌入到页面中以显示代码的动态运行。

我们将在后面的部分讨论每个示例。

每种类型的代码示例都有其自身的用例。何时使用每个示例？

• 静态示例在只需要展示一些代码且不需要展示动态结果的情况下很有用。有些人只是想要一些内容可以复制粘贴。也许你只是展示一个中间步骤，或者源代码就足够了。（例如，文章针对的是高级用户，他们只需要看到代码。）此外，你可能正在演示一个不能很好地用作嵌入示例的 API 功能，该功能可能需要其自己的单独页面进行链接。
• 交互式示例非常棒，因为读者可以动态修改值 - 这对于学习非常有价值。但是，与其他形式相比，它们的设置更加复杂，限制更多，并且适用于特定的目的。
• 传统的动态样本在你想在页面上展示源代码，然后展示其运行，并且你不太关心它作为独立示例的可访问性时很有用。这种方法的优势在于，如果你并排展示源代码和动态示例，你只需要更新一次代码即可更新两者。但是，它们可能难以编辑和调试。
• GitHub 动态样本在你有现有的示例想要嵌入，不想展示源代码，或者你想确保示例以独立形式提供时很有用。它们具有更好的贡献工作流程，但需要你了解 GitHub。此外，由于页面上的代码和源代码位于两个不同的地方，它们更容易不同步。

除了展示动态样本的特定系统之外，在 MDN 上添加或更新样本时，还需要考虑样式和内容方面的因素。

• 在页面上放置样本时，请尝试确保涵盖了你所编写的 API 或概念的所有功能或选项。至少，示例中应包含最常见的选项或属性。
• 在每个示例前面提供一个解释，说明示例的作用以及它为什么有趣或有用。
• 在每段代码之后提供一个解释，说明它做什么。
• 如果可能，将大型示例分解成更小的部分。例如，"动态样本"系统会自动将所有代码连接在一起，然后运行示例，因此你可以选择将 JavaScript、HTML 和/或 CSS 分解成更小的部分，并在每个部分之后添加描述性文本。这是一种非常好的方法，可以更清晰地解释较长或复杂的代码段。
• 不要仅仅演示 API 或技术的各个部分如何工作。请考虑你可能尝试演示的实际用例。

静态示例是指展示在代码中如何使用功能的静态代码块。这些代码块使用 Markdown "代码栅栏" 放在页面上，如 示例代码块 中所述。示例结果可能如下所示

// This is a JS example
const test = "Hello";
console.log(test);

可选地，你可能想要展示代码输出的静态图像。例如

交互式示例旨在用于 MDN 参考页面的顶部 - 我们的目标是提供这些示例以提高它们对初学者和其他读者的价值，这些读者希望在查看任何内容的所有细节之前快速获取和试用示例。关于交互式示例，有一些重要的限制需要说明

• 它们专门用于特定技术 - JavaScript 的 UI 与 CSS 的 UI 不同，它们只演示了一种技术，并且是孤立的。如果你想要展示如何组合特定的 HTML/CSS/JS 结构，它们就不合适。
• 当前，交互式动态示例仅设置为展示 CSS 和 JavaScript。对于其他技术，你只能等待。
• 与其他代码示例相比，UI 的性能要求更高；你应该避免在应用了它们的文章中放置多个示例。
• 它们不适用于大型代码示例 - UI 支持一系列固定大小，这些大小只适用于较短的示例（例如，10-15 行）。

如果你想提交一个示例，可以在 交互式示例存储库贡献指南 中找到如何提交。

如果你发现一个页面没有关联的交互式示例，欢迎你贡献一个示例！

使用 EmbedInteractiveExample 宏将完成的示例嵌入到 MDN 页面中。例如，宏调用 {{EmbedInteractiveExample("pages/js/array-push.html")}} 会显示以下代码示例

传统的动态样本使用 EmbedLiveSample 宏插入到页面中。{{EmbedLiveSample}} 调用会动态地获取与其在同一文档部分中的代码块，并将它们放入文档中，然后将其插入到页面中的 <iframe> 内。有关更多信息，请参见我们的 动态样本指南.

GitHub 动态样本使用 EmbedGHLiveSample 宏插入到页面中。{{EmbedGHLiveSample}} 调用会动态地获取指定 URL（必须位于 mdn GitHub 组织中）处的文档，并将它们插入到页面中的 <iframe> 内。

这些与传统的实时示例工作方式非常相似，但它们要简单得多。

您不必担心代码块在页面上的放置位置 - 它从 GitHub 存储库中获取一个 HTML 文档，并将其放入 <iframe> 中。

宏只有三个参数。

1. 要嵌入的文档的 URL - 这是相对于 MDN 组织而言的，其顶级目录位于 https://mdn.github.io/。因此，此参数需要包含该 URL 之后的部分，例如 my-subdirectory/example.html。如果您要嵌入的文档名为 index.html，则可以省略文件名。
2. <iframe> 的宽度，可以用百分比或像素表示。
3. <iframe> 的高度，可以用百分比或像素表示。

让我们看一个例子。假设我们要嵌入位于 https://mdn.github.io/learning-area/css/styling-boxes/backgrounds/ 的代码。我们可以使用以下调用。

{{EmbedGHLiveSample("learning-area/css/styling-boxes/backgrounds/", '100%', 100)}}

渲染后的效果如下：

• 您显然需要先将合适的代码示例放到 MDN GitHub 组织 中。这需要使用 Git 完成。如果您不熟悉 Git，请查看我们的 如何使用 GitHub Pages？ 文章，以及 准备添加数据 以了解更高级的使用方法。
• 您的代码示例需要适合展示您试图演示的内容 - 它应该包含一个简单的示例，能够很好地完成一项任务，不包含任何冒犯性内容，并应遵循 MDN 代码示例指南。