This page was translated from English by the community. Learn more and join the MDN Web Docs community.

ライブサンプル

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/_samples_/Cylon_Eye を取得します。一般的な構造は https://url-of-page_samples/group-id で、 group-id はコードが配置されている見出しまたはブロックの ID です。

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

注意: ライブサンプルの出力を表示するには、マクロを使用する必要があります。MDN のエディターは、セキュリティを確保するために <iframe> 要素の直接使用を取り除きます。

サンプルのコードを含む各 <pre> ブロックには、HTML、CSS、または JavaScript コードのいずれかを示すクラスがあり、それぞれ「brush:html」、「brush:css」、「brush:js」です。これらのクラスは、wiki が正しく使うために、対応するコードブロック上になければなりません。幸いにも、各クラスはエディターのツールバーで構文ハイライト機能を使用すると自動的に追加されます。

ライブサンプルシステムには多数のオプションが用意されており、少しずつ見ていきます。

ライブサンプルのマクロ

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

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

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

EmbedLiveSample マクロ

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

Note: 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、翻訳記事ではマクロが正しく動作するために、マクロ内で呼び出される block_ID の値を変更しなくていけません。

block_ID
必須: コードを描画する見出しまたは囲みブロックの ID。適切な ID であるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。注記: 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される block_ID の値を変更しなくていけません。 【訳注: 日本語では見出し要素には name 属性を追加して英語版と同じ ID となるようにしています。】
width
作成する <iframe> の幅で、px で指定します。これはオプションで、省略すると合理的なデフォルト幅が使用されます。特定の幅を使用する場合は、height パラメーターも指定する必要があります。
height
作成する <iframe> の高さで、px で指定します。これはオプションで、省略すると合理的なデフォルトの高さが使用されます。特定の高さを使用する場合は、width パラメーターも指定する必要があります。どちらか一方しか使用しない場合は、デフォルトのフレームサイズが使用されます。
screenshot_URL
ライブサンプルの外観を示すスクリーンショットの URL。これはオプションですが、新しいテクノロジが動作しないユーザのブラウザに対して役立つ可能性があるため、サンプルがブラウザーでサポートされている場合の様子を確認できます。このパラメータを含めると、ライブサンプルの横に、適切な見出し付きのスクリーンショットが表示されます。
page_slug

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

警告: あるコードを含むページのライブサンプルを別のターゲットページに表示するには、コードを含むページ自身が EmbedLiveSample マクロを使用して、そのページにライブサンプルを埋め込まなければなりません。そうしないと、コードを含むページが自身のページで EmbedLiveSample マクロを使用していない場合、ライブサンプルはターゲットページに全く表示されません。 (Yari issue #2243を参照してください。) 
 {{LiveSampleLink(block_ID, link_text)}}
block_ID
コードを引っ張ってくる見出しまたは囲みブロックの ID。正しいIDであるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。注記: 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される block_ID の値を変更しなくていけません。【訳注: 日本語では見出し要素には name 属性を追加して英語版と同じ ID となるようにしています。】
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;
  height: 100 px;
  border-radius: 6px;
  background-color: #ffaabb;
}

#item {
  width: 100%;
  font-weight: bold;
  text-align: center;
  font-size: 2em;
}

JavaScript

このコードは非常に簡単です。クリックすると警告が表示されるテキスト「Hello world!」にイベントハンドラーをアタッチするだけです。

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

結果

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

下記は {{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}} を通じて、これらのコードブロックを経由して呼び出される結果のリンクです。

Live sample demo link

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

コードブロックの順序
ライブサンプルを追加する場合、コードブロックは最初のものがこのサンプルのメイン言語に対応するようにソートする必要があります。たとえば、HTML リファレンスのライブサンプルを追加する場合、最初のブロックは HTML でなければならず、CSS リファレンスのライブサンプルを追加するときは CSS でなければなりません。
見出しの名前付け
曖昧さがない場合 (例: サンプルが「Examples」セクションの下にある場合)、見出しは対応する言語の唯一の名前である HTML、CSS、JavaScript、SVG など (上記参照) で直接的に表します。「HTML コンテンツ」や「JavaScript コンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。
「Result」ブロックを使用する
異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「Result」ブロックを使用してください (上記参照)。このようにすると、この例の意味は、読者とページを解析するツール (スクリーンリーダー、ウェブクローラーなど) の両方にとってより明確になります。