1. MDN Web 文件
  2. 寫作指南
  3. 頁面結構
  4. 程式碼示例

MDN 上的程式碼示例

在 MDN 上，您會看到大量程式碼示例，用於演示我們所記錄的 Web 平臺功能的使用方法。本文件將介紹您可以向頁面新增程式碼示例的方式，以及您可以使用的型別以及何時使用它們。

注意： 本頁面介紹程式碼如何包含在 MDN 頁面中。如果您想了解在 MDN 頁面中新增程式碼的語法檢查和樣式提示，請參閱我們的 程式碼風格指南。

MDN 上有哪些型別的程式碼示例？

有四種類型的程式碼示例可供使用

  • 靜態示例 — 在頁面上顯示原始碼的程式碼塊。
  • 即時示例 — 一個宏將頁面中的程式碼塊組合成一個 <iframe>，並將 iframe 嵌入頁面以顯示結果。釋出後的頁面將並排顯示原始碼塊和結果。
  • 互動式示例 — 一個宏將原始碼渲染到頁面上，並在原始碼旁邊的一個面板中渲染結果。讀者可以編輯原始碼並重新執行示例，以檢視其更改的效果。
  • GitHub 嵌入 — 一個宏從 MDN 組織的 GitHub 倉庫中獲取文件，將其放入一個 <iframe> 中，並將其嵌入頁面以顯示結果。

何時應使用每種示例？

每種型別的程式碼示例都有其自身的用例

  • 如果您需要展示程式碼，並且在已釋出的頁面上展示程式碼結果並不重要，或者您正在文章中展示一箇中間步驟，那麼靜態示例會很有用。讀者通常會查詢這些顯示功能用法的程式碼塊，以便他們可以將一個最小化的示例複製並貼上到他們的專案中。此外，您可能需要一個靜態程式碼塊來演示一個 API 或一項功能，該功能作為即時示例效果不佳。
  • 如果您想展示原始碼，然後展示其執行效果，並且不太在意它是否是一個獨立的示例，那麼即時示例會很有用。它們很有用，因為您只需要更新一次程式碼，就可以更新頁面上的程式碼塊和並排顯示的即時結果。
  • 互動式示例用於參考頁面。每頁僅限使用一次，並且必須位於頁面介紹之後的特定位置。它們對於展示某個功能的常見或實際用途非常有用。
  • 當您有一個想要嵌入的現有示例，但不想顯示其原始碼，並且/或您想確保該示例以獨立形式提供時，GitHub 嵌入會很有用。因為頁面上的程式碼和原始碼在兩個不同的位置，所以維護成本更高。

一般準則

在新增或更新 MDN 上的示例時，需要牢記樣式和內容方面的考慮因素。

  • 在頁面上放置示例時，請儘量確保涵蓋您正在撰寫的 API 或概念的所有功能或選項。至少，應演示最常見選項或屬性。
  • 在每個示例之前，請解釋該示例的作用以及它為何有趣或有用。
  • 在每段程式碼之後，解釋其作用。
  • 如果可能，將大型示例分解成較小的部分。例如，“即時示例”系統會在執行示例之前自動將所有程式碼合併在一起，因此您可以實際將 JavaScript、HTML 和/或 CSS 分成更小的部分，並在每個部分之後新增描述性文字。這是幫助更清晰地解釋長篇或複雜程式碼的絕佳方法。
  • 超越演示 API 或技術中的每個部分如何工作。考慮您可能想嘗試演示的實際用例。

靜態示例

靜態示例是顯示功能在原始碼中外觀的程式碼塊。這些示例使用 Markdown 的“程式碼圍欄”新增到頁面中，如 示例程式碼塊中所述。在文件頁面中使用時，它們看起來像這樣

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

互動式示例

InteractiveExample 宏用於在 MDN 參考頁面的頂部嵌入互動式示例。它們適用於想要嘗試示例但又不想通讀整個主題或功能文章的讀者。

InteractiveExample 宏接受一個字串作為示例的標題，後跟一個關鍵字來指定示例的高度。要包含在示例中的程式碼塊出現在宏呼叫之後，並在程式碼塊語言後的資訊字串中包含關鍵字 interactive-example。JavaScript Array.concat() 的用法是此宏的一個很好的例子，在 markdown 原始碼中看起來像這樣

md
{{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> 插入到頁面中。

該宏有三個引數

  1. 要嵌入的文件的 URL — 此 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

瞭解如何貢獻

此頁面最後修改於 ，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.