AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-mustache

Description

Mustache.js テンプレートのレンダリングを可能にします。

 

Required Scripts

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

Mustache.js のレンダリングを可能にします。

必須のスクリプト
<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>
AMP By Example のアノテーション付き amp-mustache サンプルをご覧ください。

バージョン履歴

バージョン 説明
0.2 <svg> 要素がサポートされ、バンドルサイズが縮小されました(20.5 KB から 12.2 KB へ。gzip 形式で圧縮)。最新の HTML サニタイズ ライブラリに移行しました(Caja から DOMPurify へ)。タグと属性のホワイトリストが変更されるため、マイナー変更が発生する可能性があります。生成されるマークアップの変更が機能に影響を与えないか確認するため、本番環境に進む前に、まずページをテストしておくことをおすすめします。
0.1 初期実装。

構文

Mustache は、ロジックレスのテンプレート構文です。細については、Mustache.js ドキュメントをご覧ください。主な Mustache タグは次のとおりです。

  • {{variable}}: 変数タグ。HTML エスケープした変数の値を出力します。
  • {{#section}}{{/section}}: セクションタグ。変数の存在をテストし、配列の場合は反復処理を行うことができます。
  • {{^section}}{{/section}}: 逆タグ。変数の非存在をテストできます。
  • {{{unescaped}}}: エスケープなしの HTML。出力できるマークアップには制限があります(下記の「制限事項」を参照)。

使用方法

amp-mustache テンプレートは、AMP テンプレート仕様に沿って定義、使用する必要があります。

まず、以下のように amp-mustache を宣言して読み込む必要があります。

<script src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js" async="" custom-template="amp-mustache"></script>

次に、Mustache テンプレートを script タグか template タグ内で以下のように定義します。

<!-- Using template tag. -->
<template type="amp-mustache">
  Hello {{world}}!
</template>

あるいは、以下のように定義します。

<script type="text/plain" template="amp-mustache">
  Hello {{world}}!
</script>

可能な限り template タグを使用してください。AMP 検証によって有用な dev-x ヒントを得ることができます。テーブルのコンテキストでテンプレートを使用する際のエッジケースや問題に関しては、script テンプレートを使用してください。詳細については、下記の「テーブル」をご覧ください。

テンプレートの検出方法や、レンダリングのタイミング、データの提供方法は、このテンプレートを使用してコンテンツをレンダリングするターゲット AMP 要素によってすべて決定されます(amp-listamp-form など)。

制限事項

検証

すべての AMP テンプレートと同様、amp-mustache テンプレートは、適切な形式の DOM フラグメントである必要があります。そのため、amp-mustache を使用して次のことを行うことはできません。

  • タグ名の計算。たとえば、<{{tagName}}> は使用できません。
  • 属性名の計算。たとえば、<div {{attrName}}=something> は使用できません。

「triple-mustache」の出力はサニタイズされ、使用できるタグは、abbrcaptioncolgroupcodedeldivemiinslimarkolpqssmallspanstrongsubsuptabletbodytimetdththeadtfoottruul だけに限られます。

サニタイズ

セキュリティを強化し AMP 有効性を維持するため、Mustache 出力はサニタイズされます。これにより、一部の要素や属性が暗黙的に削除されることがあります。

注意事項

ネスト テンプレート

AMP 検証の仕様により、<template> 要素を他の <template> 要素の子にすることはできません。この状況は、テンプレートを使用する 2 つのコンポーネントをネストするときに発生することがあります(amp-listamp-form など)。

対応策としては、コンポーネントの template 属性を使用して、id に基づいて <template> 要素を参照する方法があります。たとえば、次のようになります。

<amp-list id="myList" src="https://foo.com/list.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-list>

次のように指定することもできます。

<!-- Externalize templates to avoid nesting. -->
<template type="amp-mustache" id="myTemplate">
  <div>{{title}}</div>
</template>

<amp-list id="myList" src="https://foo.com/list.json" template="myTemplate">
</amp-list>

テーブル

AMP テンプレート文字列は <template> 要素内で指定する必要があるため、ブラウザの解析によって予期しない動作が発生する可能性があります。たとえば、<table> 要素が、テキストのフォスター ペアレンティングを引き起こすことがあります。次の例をご覧ください。

<template type="amp-mustache">
  <table>
    <tr>
      {{#foo}}<td></td>{{/foo}}
    </tr>
  </table>
</template>

ブラウザが、テキストノードの {{#foo}}{{/foo}} のフォスター ペアレンティングを行います。

{{#foo}}
{{/foo}}
<table>
  <tr>
    <td></td>
  </tr>
</table>

対応策としては、HTML コメント内に Mustache セクションをラップする方法があります(例: <!-- {{#bar}} -->)。<div> などの非 table 要素を使用するか、<script type="text/plain"> タグを使用してテンプレートを定義してください。

<script type="text/plain" template="amp-mustache">
  <table>
    <tr>
      {{#foo}}<td></td>{{/foo}}
    </tr>
  </table>
</script>

引用符のエスケープ

amp-mustache を使用して属性値を計算する場合、引用符のエスケープが問題になることがあります。たとえば、次のようになります。

<template type="amp-mustache">
  <!-- A double-quote (") in foo will cause malformed HTML. -->
  <amp-img alt="{{foo}}" src="example.jpg" width=100 height=100></amp-img>

  <!-- A single-quote (') or double-quote (") in bar will cause an AMP runtime parse error. -->
  <button on="tap:AMP.setState({foo: '{{bar}}'})">Click me</button>
</template>

{{foo}} 変数や {{bar}} 変数内で HTML 文字コードを使用した場合、Mustache が &; 文字を HTML エスケープするため(例: &quot; -> &amp;quot;)、正常に機能しません。対応策としては、ファクシミリ文字を使用する方法があります(例: ′(&prime;)、″(&Prime;)。

amp-mustache 内でこの置換を実行できるようにするためのオープン プロポーザルもあります。賛成の方は、コメントしてください。

HTML エンティティ

HTML エンティティは、<template> 要素内で保持されません。

これは、ユーザーが作成したテキストを含む <template> を、サーバーサイドでレンダリングする場合に問題になる可能性があります。ユーザーが作成したテキストに {{}}{{{}}} が含まれる場合、Mustache セクションとして扱われます。たとえば、{{ を HTML エンティティの {{ に置換しても、ブラウザが <template> を解析するときには保持されていないため、正常に機能しません。

対応策としては、{{ のような文字列を別の文字に置換する方法や、ユーザー作成コンテンツからすべて削除する方法などがあります。

検証

AMP 検証ツール仕様の amp-mustache ルールをご覧ください。

さらに支援が必要ですか?

このドキュメントを何度読み返しても、ご質問のすべてを完全に解消することができませんか?他にも同じ事を感じた人がいるかもしれません。Stack Overflow で問い合わせてみましょう。

Stack Overflow にアクセスする
バグや不足している機能がありますか?

AMP プロジェクトでは皆さんの参加と貢献を強くお勧めしています!当社はオープンソースコミュニティに継続的にご参加いただくことを希望しますが、特に熱心に取り組んでいる問題があれば1回限りの貢献でも歓迎します。

GitHub にアクセスする