ライブサンプル

MDN は、記事に表示されるサンプルコードを、読者が実際に見ることができる実行サンプルにする機能に対応しています。これはライブサンプルと呼ばれ、ユーザーはコードの出力がどのようなものかを見ることができます。また、ドキュメントをよりダイナミックで有益なものにします。

これらのライブサンプルには、HTML、CSS、JavaScript を任意の組み合わせで含めることができます。「ライブ」サンプルはインタラクティブではありません。ただし、実際にコードサンプルによって生成されるため、サンプルの表示出力はサンプルのコードと正確に一致します。

ライブサンプルシステムの仕組み

ライブサンプルシステムは、グループ内のすべてのコードを集め、1 つの HTML ファイルにマージし、その HTML を <iframe> にレンダリングします。このためライブサンプルは 2 つの部分で構成されています。

  • コードブロックのグループ
  • コードブロックの結果を表示する（フレームまたはリンクを作成する）マクロ

このコンテキストでは、コードブロックの「グループ」は、見出しまたはブロック要素 (<div> など) の ID によって識別されます。

  • ID がブロック要素に属する場合、そのグループは、その ID が使用される囲むブロック要素内のすべてのコードブロックを含む。
  • ID が見出しに属する場合、その見出しの後ろで同じ見出しレベルの次の見出しの前にあるすべてのコードブロックがグループに含まれます。指定された見出しの小見出しのコードブロックはすべて使用されていることに注意してください。これが望ましい効果でない場合は、代わりにブロック要素に ID を使用してください。

このマクロは特別な URL を使用して、指定されたグループのサンプルコード、例えば https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html を取得します。一般的な構造は https://url-of-page/_sample_.group-id.html で、 group-id はコードが配置されている見出しまたはブロックの ID です。

結果として得られるフレーム（またはページ）はサンドボックスで保護されており、技術的にはウェブ上で動作するものすべてを行う可能性があります。もちろん、実際の問題として、そのコードがそのページの要点に貢献していなければなりません。無関係なものが MDN 上で実行されている場合は、編集者コミュニティが削除します。

メモ: ライブサンプルの出力を表示するには、マクロを使用する必要があります。

サンプルのコードを含む各 <pre> ブロックには、HTML、CSS、または JavaScript コードのいずれかを示すクラスがあり、それぞれ "brush: html"、"brush: css"、"brush: js" です。これらのクラスは、対応するコードブロック上になければなりません。

ライブサンプルシステムにはたくさんのオプションが用意されていますが、それらを少しずつ分解して見ていきたいと思います。

ライブサンプルのマクロ

ライブサンプルを表示するために使用できるマクロは 2 つあります。

  • EmbedLiveSample はライブサンプルをページに埋め込みます。
  • LiveSampleLink はライブサンプルを新しいページに開くリンクを作成します。

多くの場合、 EmbedLiveSample マクロや LiveSampleLink マクロは、追加の作業をほぼ全くすることなくページに追加することができます。サンプルが見出しの ID で識別されるか、ID を持つブロックに含まれていれば、マクロを追加するだけでその作業が行われるはずです。

EmbedLiveSample マクロ

{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
block_ID

必須: コードを描画する見出しまたは囲みブロックの ID。適切な ID であるかどうかを確認する最善の方法は、ページの目次でそのセクションの URL を見ることです。ページのソースを見ることで確認することもできます。

width

作成する <iframe> の幅で、px で指定します。これは省略可能で、省略すると合理的な既定の幅が使用されます。特定の幅を使用する場合は、height 引数も指定する必要があります。

height

作成する <iframe> の高さで、px で指定します。これは省略可能で、省略すると合理的な既定の高さが使用されます。特定の高さを使用する場合は、width 引数も指定する必要があります。どちらか一方しか使用しない場合は、既定のフレームサイズが使用されます。

screenshot_URL

ライブサンプルの外観を示すスクリーンショットの URL。これは省略可能ですが、新しい技術が動作しないユーザーのブラウザーではサンプルがブラウザーでサポートされている場合の様子を確認できるので有用です。この引数を含めると、ライブサンプルの横に、適切な見出し付きのスクリーンショットが表示されます。

page_slug

サンプルが入っているページのスラッグです。これは省略可能で、指定されていない場合、サンプルはマクロが使用されたのと同じページから取得されます。

警告: この引数は非推奨です。新しいサンプルでは使用せず、既存のサンプルで見かけたら削除してください。私たちは積極的にその使用を削除しており、使用されなくなった時点でサポートを終了する予定です。

{{LiveSampleLink(block_ID, link_text)}}
block_ID

コードの引用元となる見出しまたは囲みブロックの ID。正しい ID であるかどうかを確認する最善の方法は、ページの目次でそのセクションの URL を見ることです。ページのソースを見ることで確認することもできます。

link_text

リンクテキストとして使用する文字列。

ライブサンプルシステムの使用

以下のセクションでは、ライブサンプルシステムの一般的な使用例をいくつか説明します。

スニペットをライブサンプルにする

よく使用されるケースの 1 つは、既に MDN に表示されている既存のコードスニペットを実際のサンプルに変換することです。

コードサンプルを準備する

最初のステップでは、コードスニペットを追加するか、既存のサンプルをコンテンツやマークアップの観点からライブサンプルとして使用できるようにします。コードスニペットは、まとめて実行可能な完全な例を構成する必要があります。たとえば、既存のスニペットに CSS のみが表示されている場合は、 CSS が操作する HTML のスニペットを追加する必要があります。

それぞれのコードは <pre> ブロックにあり、各ブロックはブロックごとに言語ごとに適切にマークされていなければなりません。ほとんどの場合、これは既に行われていますが、コードの各部分が正しい構文で構成されていることを確認することは、常に二重チェックしておく価値があります。これは、 <pre> 要素の brush:language-type というクラスで行います。 language-type は、ブロックに含まれる言語の種類で、 html、css、js などがあります。

メモ: 言語ごとに複数のブロックを設置することができます。その場合はすべて連結されます。これによって、コードの塊を置き、その後でその動作の説明を置き、さらに別な塊を置くというようなことができます。これにより、ライブサンプルと説明文を組み合わせたチュートリアルなどを簡単に作成することができます。

HTML、CSS、JavaScript コードの <pre> ブロックがそれぞれの言語の構文強調表示に対して正しく設定されていることを確認してください。

ライブサンプルのデモ

このセクションは、ライブサンプルテンプレートボタンを使用してメイン見出し（「ライブサンプルデモ」）だけでなく、HTML、CSS、および JavaScript コンテンツのサブ見出しも作成した結果です。それぞれのブロックに限定されませんし、さらに、特定の順序である必要はありません。

削除したいものを削除することもできます。スクリプトが必要ない場合は、その見出しとその <pre> ブロックを削除してください。コードブロック（HTML、CSS、または JavaScript）の見出しは、ライブサンプルマクロでは使用されないため、削除することもできます。

テンプレートが挿入されたので、いくつかのコード、さらには説明テキストを挿入することができます。

HTML

この HTML は、メッセージの配置とスタイルに役立つ段落とブロックを作成します。

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

CSS

CSS コードは、ボックスとその内部のテキストのスタイルを設定します。

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

#item {
  font-weight: bold;
  text-align: center;
  font-family: sans-serif;
  font-size: 1.5em;
}

JavaScript

このコードはとても簡単です。クリックすると警告が表示されるテキスト "Hello world!" にイベントハンドラーを割り当てるだけです。

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

結果

下記は {{EmbedLiveSample('Live_sample_demo')}} を通じて、上のコードブロックを実行した結果です。

下記は {{LiveSampleLink('Live_sample_demo', 'ライブサンプルデモへのリンク')}} を通じて、これらのコードブロックを経由して呼び出される結果のリンクです。

ライブサンプルデモへのリンク

ライブサンプルに関する取り決め

コードブロックの順序

ライブサンプルを追加する場合、コードブロックは最初のものがこのサンプルのメイン言語に対応するようにソートする必要があります。たとえば、HTML リファレンスのライブサンプルを追加する場合、最初のブロックは HTML でなければならず、CSS リファレンスのライブサンプルを追加するときは CSS でなければなりません。

見出しの名前付け

曖昧さがない場合 (例: サンプルが「例」セクションの下にある場合)、見出しは対応する言語の唯一の名前である HTML、CSS、JavaScript、SVG など（上記参照）で直接的に表します。「HTML コンテンツ」や「JavaScript コンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。

「結果」ブロックを使用する

異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「結果」ブロックを使用してください（上記参照）。このようにすると、この例の意味は、読者とページを解析するツール（画面リーダー、ウェブクローラーなど）の両方にとってより明確になります。