From 7ab429f4f603e0f850d852c13d2b87936bfc81d9 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sat, 1 May 2021 01:20:34 +0900 Subject: MDN/Structures/Live_samples を更新 (#530) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 2021/02/20 時点の英語版に同期 --- files/ja/mdn/structures/live_samples/index.html | 161 ++++++------------------ 1 file changed, 40 insertions(+), 121 deletions(-) (limited to 'files/ja') diff --git a/files/ja/mdn/structures/live_samples/index.html b/files/ja/mdn/structures/live_samples/index.html index b45feb16a9..7bc8972e8a 100644 --- a/files/ja/mdn/structures/live_samples/index.html +++ b/files/ja/mdn/structures/live_samples/index.html @@ -12,7 +12,7 @@ translation_of: MDN/Structures/Live_samples

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

-

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

+

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

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

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

    このマクロでは、特別な URL を使用して、http://url-of-page$samples/group-id (group-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> 要素の直接使用を取り除きます。

    @@ -40,25 +40,23 @@ translation_of: MDN/Structures/Live_samples

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

    -

    ライブサンプルのマクロ

    +

    ライブサンプルのマクロ

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

    -

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

    +

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

    -

    EmbedLiveSample マクロ

    +

    EmbedLiveSample マクロ

    -
     \{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
    +
     \{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
    -
    -
    -
    見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される block_ID の値を変更しなくていけません。{{訳注("日本語では見出し要素には name 属性を追加して英語版と同じ ID となるようにしています。")}}
    -
    +
    +

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

    @@ -71,15 +69,17 @@ translation_of: MDN/Structures/Live_samples
    screenshot_URL
    ライブサンプルの外観を示すスクリーンショットの URL。これはオプションですが、新しいテクノロジが動作しないユーザのブラウザに対して役立つ可能性があるため、サンプルがブラウザーでサポートされている場合の様子を確認できます。このパラメータを含めると、ライブサンプルの横に、適切な見出し付きのスクリーンショットが表示されます。
    page_slug
    -
    サンプルが入っているページのスラグ。これはオプションで、指定されていない場合はマクロが使用されている同じページからサンプルが引き出されます。
    +
    +

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

    +
    + 警告: あるコードを含むページのライブサンプルを別のターゲットページに表示するには、コードを含むページ自身が EmbedLiveSample マクロを使用して、そのページにライブサンプルを埋め込まなければなりません。そうしないと、コードを含むページが自身のページで EmbedLiveSample マクロを使用していない場合、ライブサンプルはターゲットページに全く表示されません。 (Yari issue #2243を参照してください。) +
    +
    -
      -
    - - + -
     \{{LiveSampleLink(block_ID, link_text)}}
    +
     \{{LiveSampleLink(block_ID, link_text)}}
    block_ID
    @@ -88,108 +88,27 @@ translation_of: MDN/Structures/Live_samples
    リンクテキストとして使用する文字列。
    -

    ライブサンプルシステムを使用する

    +

    ライブサンプルシステムを使用する

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

    -

    これらのすべてのケースでライブサンプルの結果を表示するには、エディターで公開をクリックする必要があります (編集モードから離れます)。ライブサンプルにはインセプションのように再帰的な性質があるため、プレビュー機能でライブサンプルを表示することはできません。

    - -

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

    +

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

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

    -

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

    +

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

    -

    最初のステップでは、コードスニペットを追加するか、既存のサンプルをコンテンツやマークアップの観点からライブサンプルとして使用できるようにします。コードスニペットは、まとめて実行可能な完全な例を構成する必要があります。たとえば、既存のスニペットに CSS のみが表示されている場合は、CSS が操作する HTML のスニペットを追加する必要があります。
    -
    - それぞれのコードは {{HTMLElement("pre")}} ブロックにあり、各ブロックはブロックごとに言語ごとに適切にマークされていなければなりません。ほとんどの場合、これは既に行われていますが、コードの各部分が正しい構文で構成されていることを確認することは、常に二重チェックしておく価値があります。ツールバーの PRE アイコンの隣には、MDN が構文強調表示を行うさまざまな言語のドロップダウンメニューアイコン (ツールヒント: 構文ハイライター) があります。構文の強調表示のためにブロックの言語を設定することで、ライブサンプルシステムの目的のための言語と関連付けられます。

    +

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

    -
    -

    注意: 複数の言語のブロックが独立していて、すべて一緒に連結する場合があるかもしれません。コードの塊りに続いて、動作原理の説明があって、また次の塊り、…という構成ができます。これにより、説明テキストを交えたライブサンプルを利用するチュートリアルなどを作成することがより容易になります。

    -
    +

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

    -

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

    - -
    -

    注意: MDN にコンテンツを貼り付ける際には、意図せず不要なスタイルやクラスを取り込む可能性のあるスタイル付きコンテンツ (たとえば、別のサイトからコピーされたコードの構文強調を含む) を貼り付けることを意識してください。こうならないように注意してください。必要に応じて、ソースモードで編集内容を確認し、不要なスタイルやクラスを削除してください (貼り付ける前に確認するか、代わりに「プレーンテキストとして貼り付け」オプションを使用してください)。

    +
    +

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

    -

    ライブサンプルマクロを挿入する

    - -

    コードが配置され、各ブロックの言語を識別するように適切に構成されたら、iframeを作成するマクロを挿入する必要があります。

    - -
      -
    1. ツールバーのコードサンプルの iFrame を挿入ボタン () をクリックします。
      - ライブサンプルフレームを設定するためのダイアログボックスが開きます
      -
      2. -
    2. ドキュメントに埋め込みたいサンプルが含まれている記事のタイトルを入力します。
      - デフォルトでは現在編集中の記事ですが、MDN の別の場所で記事を選択することもできます。これにより、必要に応じて複数ページのサンプルを再利用することができます。(このフィールドに新しいテキストを入力すると、部分的に一致するページのメニューが表示され、必要なページのタイトルを選択します)
      3. -
    3. ドキュメント内のセクションメニューで、埋め込みたいサンプルのコードブロックを含む記事のセクションを選択します
      4. -
    4. OKボタンをクリックして、サンプルフレームを作成するマクロ呼び出しを生成して挿入します。マクロ呼び出しは次のようになります
      - \{{ EmbedLiveSample('Live_sample_demo') }}
      5. -
    - -

    新規ライブサンプルを追加する

    - -

    新しいページを作成していて、ライブサンプルとして提示したいコードを挿入したい場合は、さらに多くの作業をエディターで行うことができます！

    - -
      -
    1. ツールバーのコードサンプルテンプレートを挿入ボタン () をクリックします。
      - ライブサンプルに名前を付けるよう求める簡単なダイアログが表示されます。
      -
      2. -
    2. サンプルのタイトルを入力します。これはサンプルの見出しとして使用されます。このタイトルがページの文脈の中で意味が通ることを確認してください。
      3. -
    3. 入力したタイトルの新しい見出しが、HTML、CSS、およびJavaScript用のサブ見出しと空のコードブロックとともに作成されます。
      4. -
    4. 必要のない見出しやコードブロックを削除してください。
      5. -
    5. 適切なコードブロックでサンプルを構成するコードを入力します。
      6. -
    6. 取り決めを確認します。
      7. -
    - -

    サンプルファインダーを使う

    - -

    前述のように、サンプルファインダーは、コードサンプルの iFrame を挿入アイコンをクリックするとアクティブになります。残念なことに、サンプルファインダーは編集しないと使用できないマクロを生成することがあります。必要に応じて慎重にチェックして編集すべき 2 つの問題エリアがあります。

    - -
      -
    1. ドキュメントフィールド。このフィールドは入力時に検索され、入力した文字列にマッチするドキュメントのリストが表示されます。しかし、提示されたリストにはサブページは含まれません。たとえば、メインページの @counter-style の下にある Negative のサブページで作業しているとします。サンプルファインダーでの検索では Negative は見つかりませんが、メインページの @counter-style が検索されます。@counter-style を選択すると、フィールドの背景が緑色に変わります。このことによる問題については以下を参照してください。
      2. -
    2. ドキュメントのセクション。ドキュメント内のプルダウンメニューのセクションに、必要なセクションが表示されないことがあります。例のように、ただ一つ選択して簡単な編集をすることで修正することができます。
      3. -
    - -

    サンプルファインダーは次のようになりました。

    - -
    \{{ EmbedLiveSample('Examples', '', '', '', 'Web/CSS/@counter-style') }}
    - -

    このマクロは動作しません。block_ID が Examples となっていますが、この場合は Example でなければなりません。(このセクションのソース ID を調べて、使用する必要のある block_ID を確認してください。) 同様に page_slug が @counter-style になっていますが、@counter-style/negative となるべきです。これらの修正は、編集ページで直接行うことができます。

    - -

    編集すると、マクロは次のようになります。

    - -
    \{{ EmbedLiveSample('Example', '', '', '', 'Web/CSS/@counter-style/negative') }}
    - -

    この編集されたマクロは動作します。マクロが正常に動作している場合は、Open in CodePen ボタンが表示されます。この例のサムネイルは、Open in CodePen ボタンの上に表示されます。ボタンがあるがサムネイルがない場合は、少し待ってください。サーバーがこれを生成するには時間がかかることがあります。

    - -

    更新が必要なサンプルを検索する

    - -

    既存のサンプルを探して更新する場合は、更新の主な 3 つの種類があります:

    - -
      -
    • 既存の非ライブサンプルスニペットをライブサンプルに変換。
      • -
    • 既存のライブサンプルのバグを修正。
      • -
    • 既存のライブサンプルを改善、または、技術の変化に基づいてサンプルを更新。
      • -
    - -
    -

    注意: ライブサンプルシステムを使用するために更新が必要なサンプルがある記事を見つけた場合は、タグ「NeedsLiveSample」をページに追加してください。

    -
    - -

    ライブサンプルに変換するサンプルを検索する

    - -

    MDN にはライブサンプルシステムをまだ使用していない古いサンプルがたくさんあります。私たちの目標は、これらのほとんどまたはすべてをライブサンプルに更新することです。これにより、一貫性とユーザビリティが向上します。MDN を日常的に使用するときには、これらの多くがほぼ確実に見つかるでしょう。しかし、あなたが特にそれらを更新しようと探している場合、それらを見つけることができますか？残念ながら簡単な方法はありません。ですが、それらを追跡するのに役立つガイドラインがいくつかあります：

    - - +

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

    -

    ライブサンプルのデモ

    +

    ライブサンプルのデモ

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

    @@ -197,21 +116,21 @@ translation_of: MDN/Structures/Live_samples

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

    -

    HTML

    +

    HTML

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

    -
    <p>A simple example of the live sample system in action.</p>
+
    <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
    
 
 
    CSS コードは、ボックスとその内部のテキストのスタイルを設定します。
    
 
-
    .box {
+
    .box {
   width: 200px;
   height: 100 px;
   border-radius: 6px;
@@ -226,27 +145,27 @@ translation_of: MDN/Structures/Live_samples
 }
 
    
 
-
    JavaScript
    
+
    JavaScript
    
 
 
    このコードは非常に簡単です。クリックすると警告が表示されるテキスト「Hello world!」にイベントハンドラーをアタッチするだけです。
    
 
-
    var el = document.getElementById('item');
+
    var el = document.getElementById('item');
 el.onclick = function() {
   alert('Owww, stop poking me!');
 }
 
    
 
-
    結果
    
+
    結果
    
+
+
    下記は \{{EmbedLiveSample('Live_sample_demo')}} を通じて、上のコードブロックを実行した結果です。
    
 
-
    下記は \{{EmbedLiveSample('Live_sample_demo')}} を通じて、上のコードブロックを実行した結果です。
    
- 
    
- {{EmbedLiveSample('Live_sample_demo')}}
    
+
    {{EmbedLiveSample('Live_sample_demo')}}
    
 
 
    下記は \{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}} を通じて、これらのコードブロックを経由して呼び出される結果のリンクです。
    
 
 
    {{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}
    
 
-
    ライブサンプルに関する取り決め
    
+
    ライブサンプルに関する取り決め
    
 
 
    
  
    コードブロックの順序
    
@@ -254,5 +173,5 @@ el.onclick = function() {
  
    見出しの名前付け
    
  
    曖昧さがない場合 (例: サンプルが「Examples」セクションの下にある場合)、見出しは対応する言語の唯一の名前である HTML、CSS、JavaScript、SVG など (上記参照) で直接的に表します。「HTML コンテンツ」や「JavaScript コンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。
    
  
    「Result」ブロックを使用する
    
- 
    異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「Result」ブロックを使用してください (上記参照)。このようにして、この例の意味は、読者とページを解析するツール (スクリーンリーダー、ウェブクローラーなど) の両方にとってより明確になります。
    
+ 
    異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「Result」ブロックを使用してください (上記参照)。このようにすると、この例の意味は、読者とページを解析するツール (スクリーンリーダー、ウェブクローラーなど) の両方にとってより明確になります。
    
 
    
-- 
cgit v1.2.3-54-g00ecf