amp-bind

<script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>

データ バインディングと式を使用して独自のインタラクティブ性を追加します。

概要

amp-bind コンポーネントを使用すると、データ バインディングと JS に似た式を使って独自のステートフルなインタラクティブ性を AMP ページに追加できます。

簡単な例

次の例では、ボタンをタップすると、<p> 要素のテキストが「Hello World」から「Hello amp-bind」に変わります。

<p [text]="'Hello ' + foo">Hello World</p>

<button on="tap:AMP.setState({foo: 'amp-bind'})">Say "Hello amp-bind"</button>

仕組み

amp-bind には以下の 3 つの主要なコンポーネントがあります。

1. 状態 : ドキュメント スコープの変更可能な JSON ステータス。上の例では、ボタンをタップする前の状態は空です。ボタンをタップした後の状態は {foo: 'amp-bind'}です。
2. 式 : 状態を参照可能な、JavaScript に似た式です。上の例の式'Hello ' + fooは、文字列リテラル 'Hello' とステータス変数 foo を連結します。式で使用できるオペランドには 100 個の制限があります。
3. バインディング: : 要素のプロパティを式にリンクする、[プロパティ] の形式の特別な属性です。上の例のバインディング [text] は、式の値が変化するたびに要素のテキストを更新します。

amp-bind `では、AMP ページの速度、セキュリティ、パフォーマンスを確保するために特別な措置が取られています。

少し複雑な例

<!-- Store complex nested JSON data in <amp-state> elements. -->
<amp-state id="myAnimals">
  <script type="application/json">
    {
      "dog": {
        "imageUrl": "/img/dog.jpg",
        "style": "greenBackground"
      },
      "cat": {
        "imageUrl": "/img/cat.jpg",
        "style": "redBackground"
      }
    }
  </script>
</amp-state>

<p [text]="'This is a ' + currentAnimal + '.'">This is a dog.</p>

<!-- CSS classes can also be added or removed with [class]. -->
<p class="greenBackground" [class]="myAnimals[currentAnimal].style">
  Each animal has a different background color.
</p>

<!-- Or change an image's src with the [src] binding. -->
<amp-img width="300" height="200" src="/img/dog.jpg" [src]="myAnimals[currentAnimal].imageUrl">
</amp-img>

<p><button on="tap:AMP.setState({currentAnimal: 'cat'})">Set to Cat</button>

ボタンを押すと、次のようになります。

1. 状態が更新されます（currentAnimal がd 'cat' に定義されます）。

2. currentAnimal に依存する式が評価されます。

   • 'This is a ' + currentAnimal + '.' => 'This is a cat.'
   • myAnimals[currentAnimal].style => 'redBackground'
   • myAnimals[currentAnimal].imageUrl => /img/cat.jpg

3. 変更された式に依存するバインディングが更新されます。

   • 1 つ目の <p> 要素のテキストが「This is a cat.」になります。
   • 2 つ目の <p> 要素の class 属性が「redBackground」になります。
   • amp-img 要素によって猫の画像が表示されます。

詳細

状態

amp-bind を使用する各 AMP ドキュメントでは、ドキュメント スコープの変更可能な JSON データ（状態）が作成されます。

amp-state による状態の初期化

amp-bind の状態は、amp-state コンポーネントを通じて初期化できます。

<amp-state id="myState">
  <script type="application/json">
    {
      "foo": "bar"
      }
  </script>
</amp-state>

式では、ドット構文によってステータス変数を参照できます。この例の myState.foo は "bar" として評価されます。

• <amp-state> 要素の子 JSON の最大サイズは 100 KB です。
• <amp-state> 要素では、子 JSON スクリプトの代わりに CORS URL を指定することもできます。詳しくは、付録をご覧ください。

状態の更新

状態コンポーネントでは refresh アクションがサポートされており、このアクションを使用して状態の内容を更新することができます。

<amp-state id="amp-state" ...></amp-state>
<!-- Clicking the button will refresh and refetch the json in amp-state. -->
<button on="tap:amp-state.refresh"></button>

AMP.setState() による状態の更新

AMP.setState() アクションは、オブジェクト リテラルを状態にマージします。たとえば、下のボタンを押すと、AMP.setState() によってオブジェクト リテラルが状態にディープマージされます。

<!-- Like JavaScript, you can reference existing
      variables in the values of the  object literal. -->
<button on="tap:AMP.setState({foo: 'bar', baz: myAmpState.someVariable})"></button>

一般に、ネストされたオブジェクトをマージする場合の最大深度は 10 です。変数（amp-state によって導入された変数を含む）はすべてオーバーライド可能です。

AMP.setState() は、特定のイベントによってトリガーされた場合、event プロパティでイベント関連のデータにアクセスすることもできます。

<!-- The "change" event of this <input> element contains
      a "value" variable that can be referenced via "event.value". -->
  <input type="range" on="change:AMP.setState({myRangeValue: event.value})">

AMP.pushState() による履歴の変更

AMP.pushState() アクションは、新しいエントリもブラウザの履歴スタックにプッシュすることを除き、AMP.setState() に似ています。この履歴エントリを（戻るなどの操作によって）ポップすると、AMP.pushState() で設定された以前の変数の値が復元されます。

例:

<button on="tap:AMP.pushState({foo: '123'})">Set 'foo' to 123</button>

• ボタンをタップすると、変数 foo が 123 に設定され、新しい履歴エントリがプッシュされます。
• 戻る操作を行うと、foo が以前の値 "bar" に復元されます（AMP.setState({foo: 'bar'}) を呼び出すのと同じ効果があります）。

式

式は JavaScript に似ていますが、重要な違いがいくつかあります。

JavaScript との違い

• 式は、含んでいるドキュメントの状態にのみアクセスできます。
• 式は、window や document などのグローバル変数にはアクセスできません。
• ホワイトリストに登録されている関数と演算子のみを使用できます。
• 一般に、独自の関数、クラス、ループは使用できません。arrow 関数はパラメータとして使用できます（例: Array.prototype.map）。
• 未定義の変数と array-index-out-of-bounds は、undefined を返したりエラーをスローしたりするのではなく、null を返します。
• パフォーマンスの向上のために、現在は 1 つの式で使用できるオペランドの数が 50 個に制限されています。不十分な場合はお問い合わせください。

式の文法と実装について詳しくは、bind-expr-impl.jison と bind-expression.js をご覧ください。

例

以下はすべて有効な式です。

1 + '1'           // 11
1 + (+'1')        // 2
!0                // true
null || 'default' // 'default'

ホワイトリストに登録されている関数

// Returns [1, 2, 3].
[3, 2, 1].sort()

// Returns [1, 3, 5].
[1, 2, 3].map((x, i) => x + i)

// Returns 6.
[1, 2, 3].reduce((x, y) => x + y)

// Returns 3.
                (3.14).toFixed()

// Returns '3.14'.
                  (3.14).toString()

// Returns 'abcdef'.
                      abc'.concat('def')

// Returns 1.
                          abs(-1)

// Returns ['a', 'b'].
                            keys({a: 1, b: 2})

// Returns [1, 2].
                              values({a: 1, b: 2}

// Returns 'Hello%20world'.
                                encodeURIComponent('Hello world')

¹ パラメータが 1 つだけの arrow 関数では、かっこは使用できません（例: (x) => x + 1 ではなく、x => x + 1 を使用します）。また、sort() と splice() は、in-place を操作するのではなく、変更されたコピーを返します。 ² 静的関数は名前空間化されません（例: Math.abs(-1) ではなく、abs(-1) を使用します）。

amp-bind-macro によるマクロの定義

amp-bind-macro を定義することにより、amp-bind の式フラグメントを再利用できます。amp-bind-macro 要素を使用すると、0 個以上の引数を取り、現在の状態を参照する式を定義できます。マクロは、ドキュメント内の任意の場所から id 属性の値を参照することで、関数のように呼び出すことができます。

<amp-bind-macro id="circleArea" arguments="radius" expression="3.14 * radius * radius"></amp-bind-macro>

<div>
  The circle has an area of <span [text]="circleArea(myCircle.radius)">0</span>.
</div>

マクロは、自身より前に定義された他のマクロを呼び出すこともできます。自身を再帰的に呼び出すことはできません。

バインディング

バインディングは、要素のプロパティを式にリンクする、[property] の形式の特別な属性です。代わりに、XML 互換の構文を data-amp-bind-property の形式で使用することもできます。

状態 が変わると式が再評価され、バインドされた要素のプロパティが新しい式の結果で更新されます。

amp-bind は、以下の 4 種類の要素の状態に基づいてデータ バインディングをサポートします

バインディングに関する注意事項:

• セキュリティ上の理由から、innerHTML へのバインドは禁止されています。
• 属性のバインディングは、安全でない値（javascript: など）の場合はすべてサニタイズされます。
• ブール式の結果によってブール値の属性が切り替えられます。たとえば、<amp-video [controls]="expr"...> では、expr の評価結果が true の場合、<amp-video> 要素に controls 属性が設定されます。expr の評価結果が false の場合、controls 属性が削除されます。
• DOM API で XML（XHTML、JSX など）や属性を書き込む場合に、属性名の角かっこ（[ と ]）が問題になることがあります。このような場合は、構文に [x]="foo" ではなく data-amp-bind-x="foo" を使用します。

要素固有の属性

以下のコンポーネントと属性へのバインディングのみが許可されています。

^* バインド可能な属性を示します（同等のバインド不可能な属性はありません）。

デバッグ

開発中に警告とエラーに焦点を当てたり、特殊なデバッグ関数を使用したりするには、開発モードで（URL フラグメント #development=1 を使用して）テストを実施します。

警告

開発モードでは、バインドされた属性のデフォルト値が対応する式の初期結果と一致しない場合、amp-bind によって警告が発行されます。これにより、他の状態変数の変化に伴って生じる意図しない変化を防止できます。以下に例を示します。

<!-- The element's default class value ('def') doesn't match the expression result for [class] ('abc'),
so a warning will be issued in development mode. -->

<p class="def" [class]="'abc'"></p>

開発モードでは、未定義の変数またはプロパティの参照を解除した場合にも、amp-bind によって警告が発行されます。これにより、null 式の結果が原因の意図しない変化も防止できます。以下に例を示します。

<amp-state id="myAmpState">
  <script type="application/json">
    { "foo": 123 }
</script>
</amp-state></p>

<!-- The amp-state#myAmpState does not have a `bar` variable, so a warning
  will be issued in development mode. -->
<p [text]="myAmpState.bar">Some placeholder text.</p>

エラー

amp-bind の使用時に発生する可能性があるランタイム エラーにはさまざまな種類があります。

状態のデバッグ

AMP.printState() を使用して、現在の状態をコンソールに出力します。

付録

<amp-state> の仕様

amp-state 要素には、子 <script> 要素、またはリモートの JSON エンドポイントの CORS URL を含む src 属性のいずれかを含めることができます。両方を含めることはできません。

<amp-state id="myLocalState">
  <script type="application/json">
    {
      "foo": "bar"
      }
  </script>
</amp-state></p>

<p><amp-state id="myRemoteState" src="https://data.com/articles.json">
</amp-state>

XHR のバッチ処理

AMP では、JSON エンドポイントに対する XMLHttpRequest（XHR）をバッチ処理します。つまり、AMP ページでは、複数のコンシューマー（複数の amp-state 要素など）のデータソースとして単一の JSON データ リクエストを使用できます。たとえば、amp-state 要素によってエンドポイントへの XHR が作成された場合、XHR の送信中は、同じエンドポイントに対する後続の XHR はトリガーされず、代わりに 1 つ目の XHR の結果を返します。

属性

AMP.setState() によるディープマージ

AMP.setState() が呼び出されると、amp-bind により、指定されたオブジェクト リテラルと現在の状態がディープマージされます。繰り返しマージされるネストされたオブジェクトを除き、オブジェクト リテラルの変数はすべて、状態に直接書き込まれます。状態に含まれているプリミティブと配列は必ず、オブジェクト リテラル内の同じ名前の変数によって上書きされます。

次の例をご覧ください。

{
  <!-- State is empty -->
  }

<button on="tap:AMP.setState({employee: {name: 'John Smith', age: 47, vehicle: 'Car'}})"...></button>
<button on="tap:AMP.setState({employee: {age: 64}})"...></button>

つ目のボタンを押すと、状態が次のように変わります。

{
  employee: {
    name: 'John Smith',
    age: 47,
    vehicle: 'Car',
    }
  }

つ目のボタンを押すと、amp-bind により、オブジェクト リテラルの引数 {employee: {age: 64}} が既存の状態に繰り返しマージされます。

{
  employee: {
    name: 'John Smith',
    age: 64,
    vehicle: 'Car',
    }
  }

employee.age は更新されていますが、employee.name キーと employee.vehicle キーは変更されていません。

循環参照を含むオブジェクト リテラルを指定して AMP.setState() を呼び出すと、amp-bind によってエラーがスローされます。

変数の削除

既存のステータス変数を削除するには、AMP.setState() でその値を null に設定します。前の例の状態から開始して、次のボタンを押します。

<button on="tap:AMP.setState({employee: {vehicle: null}})"...></button>

状態が次のように変わります。

{
  employee: {
    name: 'John Smith',
    age: 48,
    }
  }

同様に、次のボタンを押します。

<button on="tap:AMP.setState({employee: null})"...></button>

状態が次のように変わります。

{
  <!-- State is empty -->
  }

式の文法

amp-bind の式の文法は BNF に似ています。

expr:
  operation
  | invocation
  | member_access
  | '(' expr ')'
  | variable
  | literal

operation:
    !' expr
    | '-' expr
    | '+' expr
    | expr '+' expr
    | expr '-' expr
    | expr '*' expr
    | expr '/' expr
    | expr '%' expr
    | expr '&&' expr
    | expr '||' expr
    | expr '<=' expr
    | expr '<' expr
    | expr '>=' expr
    | expr '>' expr
    | expr '!=' expr
    | expr '==' expr
    | expr '?' expr ':' expr

invocation:
      expr '.' NAME args

args:
  (' ')'
  | '(' array ')'
    ;

member_access:
  expr member
    ;

member:
  .' NAME
  | '[' expr ']'

variable:
   NAME
  ;

literal:
    STRING
  | NUMBER
  | TRUE
  | FALSE
  | NULL
  | object_literal
  | array_literal

array_literal:
    ' ']'
    | '[' array ']'

array:
  expr
  | array ',' expr

object_literal:
  {' '}'
  '{' object '}'

object:
  key_value
  | object ',' key_value

key_value:
  expr ':' expr