AMP
JA
English Deutsch Français العربية Español Italiano Indonesia 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

アクションとイベント

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

このドキュメントでは、AMP ウェブサイト、ストーリー、および広告のアクションとイベントについて説明します。AMP メール形式については、「AMP メールのアクションとイベント」を参照してください。

on 属性は、要素にイベントハンドラをインストールするために使用されます。サポートされているイベントは、要素によって異なります。

構文の値は、フォームの単純なドメイン固有の言語です。

eventName:targetId[.methodName[(arg1=value, arg2=value)]]

構文の各部分の説明については、以下のテーブルを参照してください。

構文 必須？ 説明
eventName はい これは、要素が公開するイベントの名前です。
targetId はい これは要素の DOM id またはイベントのレスポンスとしてアクションを実行する事前定義済みの特殊ターゲットです。次の例では、targetId は amp-lightbox ターゲットの DOM id である photo-slides です。 
<amp-lightbox id="photo-slides"></amp-lightbox>
<button on="tap:photo-slides">Show Images</button>
methodName いいえ これは、デフォルトアクションを伴う要素に使用します。

ターゲット要素（targetId で参照）が公開しており、イベントがトリガされたときに実行するメソッドです。

AMP には、要素が実装できるデフォルトアクションの概念があるため、methodName を省略すると、AMP はそのメソッドを実行します。
arg=value いいえ 一部のアクションは引数を受け取ることができ、その場合はドキュメントに記されています。引数は、key=value 表記で括弧に囲んで定義されます。受け入れられる値は次のとおりです。
  • 引用符で囲まれていない単純な文字列: simple-value
  • 引用符で囲まれた文字列: "string value" または 'string value'
  • ブール値: true または false
  • 数値: 11 または 1.1
  • イベントデータへのドット構文参照: event.someDataVariableName

複数のイベントの処理

1 つの要素で複数のイベントをリスンすることができます。イベントの指定にはセミコロン ; 区切りを使用します。

例: on="submit-success:lightbox1;submit-error:lightbox2"

1 つのイベントに対する複数のアクション

同一のイベントに対し、複数のアクションを順に実行できます。アクションの指定にはカンマ ',' 区切りを使用します。

例: on="tap:target1.actionA,target2.actionB"

グローバル定義のイベントとアクション

AMP は、HTML 要素（AMP 要素を含む）でリスンできる tap イベントをグローバルに定義します。

また、AMP は HTML 要素でトリガできる hide、show、および toggleVisibility アクションもグローバルに定義します。

要素を表示できるのは、その要素が以前に hide または toggleVisibility アクションで、またはhidden 属性を使って非表示にされていた場合のみです。show アクションは、CSS display:none または AMP の layout=nodisplay で非表示にされた要素には使用できません。

たとえば、AMP では以下を行うことができます。

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

要素固有のイベント

* - すべての要素

イベント 説明
tap 要素がクリックまたはタップされたときに発行されます。

入力要素

イベント 説明 要素 データ
change 要素の値が変更されたりコミットされたりした場合に発行されます。

データプロパティは HTMLInputElement と HTMLSelectElement にミラーされます。

 input 
event.min
event.max
event.value
event.valueAsNumber
input[type="radio"],
input[type="checkbox"] 		event.checked
select 
event.min
event.max
event.value
input-debounced 要素の値が変更されると発行されます。これは、標準的な change イベントに似ていますが、入力の値が変化しなくなってから 300 ミリ秒後にのみ発行されます。 input イベントを発行する要素。 change イベントデータと同じ。
input-throttled 要素の値が変更されると発行されます。これは、標準的な change イベントに似ていますが、入力の値が変化する間に、最大 100 ミリ秒ごとに発行されます。 input イベントを発行する要素。 change イベントデータと同じ。

amp-accordion > セクション

イベント 説明 データ
expand アコーディオンセクションが展開されると発行されます。 なし。
collapse アコーディオンセクションが折り畳まれると発行されます。 なし。

amp-carousel[type="slides"]

イベント 説明 データ
slideChange カルーセルの現在のスライドが変化すると発行されます。 
// Slide number.
event.index

amp-lightbox

イベント 説明 データ
lightboxOpen ライトボックスが完全に可視化されると発行されます。 なし
lightboxClose ライトボックスが完全に閉じられると発行されます。 なし

amp-list

イベント 説明 データ
changeToLayoutContainer amp-list のレイアウトを layout="CONTAINTER" に更新し、動的なサイズ変更を行えるようにします。
fetch-error(低信頼) データのフェッチに失敗したときに発行されます。 なし

amp-selector

イベント 説明 データ
select オプションが選択または選択解除されると発行されます。 
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

イベント 説明 データ
sidebarOpen トランジションが終了した後にサイドバーが完全に開くと発行されます。 なし
sidebarClose トランジションが終了した後にサイドバーが完全に閉じると発行されます。 なし

amp-state

イベント 説明 データ
fetch-error(低信頼) データのフェッチに失敗したときに発行されます。 なし

amp-video、amp-youtube

イベント 説明 データ
firstPlay(低信頼) ユーザーによって動画が初めて再生されたときに発行されます。自動再生動画では、ユーザーが動画と対話した時点で発行されます。このイベントは低信頼性であるため、ほとんどのアクションをトリガできません。amp-animation アクションなどの低信頼性アクションのみを実行できます。
timeUpdate（低信頼） 動画の再生位置が変更されると発行されます。イベントの頻度は AMP によって制御されており、現在 1 秒間隔に設定されています。このイベントは低信頼性であるため、ほとんどのアクションをトリガできません。amp-animation アクションなどの低信頼性アクションのみを実行できます。 {time, percent}time は、現在の時間を秒で示し、percent は、合計時間のパーセント率として現在の位置を示す、0 と 1 の間の数値です。

form

イベント 説明 データ
submit Fired when the form is submitted.
submit-success Fired when the form submission response is success. 
// Response JSON.
event.response
submit-error フォーム送信のレスポンスがエラーである場合に発行されます。 
// Response JSON.
event.response
valid フォームが有効である場合に発行されます。
invalid フォームが無効である場合に発行されます。

要素固有のアクション

* （すべての要素）

アクション 説明
hide ターゲット要素を非表示にします。
show ターゲット要素を表示します。autofocus 要素が可視状態になると、フォーカスが設定されます。
toggleVisibility ターゲット要素の可視性を切り替えます。autofocus 要素が可視状態になると、フォーカスが設定されます。
toggleClass(class=STRING, force=BOOLEAN) ターゲット要素のクラスを切り替えます。force はオプションです。true に設定すると、クラスは追加されるだけで削除されません。false に設定すると、削除されるだけで追加されません。
scrollTo(duration=INTEGER, position=STRING) スムーズなアニメーションで要素をビューにスクロールします。
duration はオプションで、アニメーションの長さをミリ秒で指定します。 指定されない場合、500 ミリ秒以下のスクロール差に相対する長さが使用されます。
position はオプションで、top、center、または bottom を指定します（デフォルトは top）。 スクロール後のビューポートに相対する要素の位置を指定します。
アクセシビリティのベストプラクティスとして、これと、focus() の呼び出しを組み合わせ、スクロール先の要素にフォーカスを設定するようにします。
focus ターゲット要素にフォーカスを設定します。フォーカスを解除するには、別の要素に focus します（通常、親要素）。アクセシビリティを考慮し、body/documentElement にフォーカスを設定することで解除することは強くお勧めしません。

amp-audio

アクション 説明
play オーディオを再生します。<amp-audio> 要素が <amp-story> の子である場合は no-op です。
pause オーディオを一時停止します。<amp-audio> 要素が <amp-story> の子である場合は no-op です。

amp-bodymovin-animation

アクション 説明
play アニメーションを再生します。
pause アニメーションを一時停止します。
stop アニメーションを停止します。
seekTo(time=INTEGER) アニメーションの currentTime を特定の値に設定し、アニメーションを一時停止します。
seekTo(percent=[0,1]) あるパーセント値を使用して特定の値に対するアニメーションの currentTime を判定し、アニメーションを一時停止します。

amp-accordion

アクション 説明
toggle(section=STRING) amp-accordion の expanded と collapsed 状態を切り替えます。引数なしで呼び出されると、アコーディオンのすべてのセクションを切り替えます。次のようにセクション ID を指定すると、特定のセクションでトリガされます。on="tap:myAccordion.toggle(section=
expand(section=STRING) アコーディオンのセクションを展開します。セクションがすでに展開済みである場合は、そのままになります。引数なしで呼び出されると、アコーディオンのすべてのセクションを展開します。次のようにセクション ID を指定すると、特定のセクションでトリガされます。on="tap:myAccordion.expand(section='section-id')"
collapse(section=STRING) アコーディオンのセクションを折り畳みます。すでに折り畳まれている場合は、そのままになります。引数なしで呼び出されると、アコーディオンのすべてのセクションを折り畳みます。次のようにセクション ID を指定すると、特定のセクションでトリガされます。on="tap:myAccordion.collapse(section='section-id')"

amp-carousel[type="slides"]

アクション 説明
goToSlide(index=INTEGER) 特定のスライドインデックスまでカルーセルを進めます。
toggleAutoplay(toggleOn=true|false) カルーセルの autoplay ステータスを切り替えます。 toggleOn はオプションです。

amp-image-lightbox

アクション 説明
open (default) アクションをトリガしたソース画像で、画像のライトボックスを開きます。

amp-lightbox

アクション 説明
open (default) ライトボックスを開きます。
close ライトボックスを閉じます。
アクション 説明
open ライトボックスギャラリーを開きます。次のように画像 ID を指定する場合、別の要素をタップしてトリガできます。 `on="tap:amp-lightbox-gallery.open(id='image-id')"`

amp-list

アクション 説明
refresh src のデータを再読み込みし、リストをレンダリングし直します。

amp-live-list

アクション 説明
update (default) DOM の項目を更新して、更新されたコンテンツを表示します。

amp-selector

アクション 説明
clear 定義された amp-selector からすべての選択をクリアします。
selectUp(delta=INTEGER) `delta` の値ずつ選択を上に移動します。デフォルトの `delta` は -1 に設定されています。オプションが選択されない場合、選択状態は最後のオプションの値になります。
selectDown(delta=INTEGER) `delta` の値ずつ選択を下に移動します。デフォルトの `delta` は 1 に設定されています。オプションが選択されない場合、選択状態は最初のオプションの値になります。
toggle(index=INTEGER, value=BOOLEAN) `selected` のアプリケーションを切り替えます。select 属性がない場合、このアクションによって追加されます。select 属性が存在する場合、このアクションによって削除されます。`value` 引数にブール値を指定すると、追加または削除を強制・維持することができます。`true` の場合は `selected` 属性を強制的に追加し、すでに存在する場合は削除しません。`false` の場合は属性を削除し、すでに存在しない場合は追加しません。

amp-sidebar

アクション 説明
open (default) サイドバーを開きます。
close サイドバーを閉じます。
toggle サイドバーの状態を切り替えます。

amp-state

アクション 説明
refresh ブラウザのキャッシュを無視して、`src` 属性にあるデータをフェッチし直します。

amp-user-notification

アクション 説明
dismiss (default) 参照されたユーザー通知要素を非表示にします。

動画要素

以下のアクションは、次の AMP 動画要素でサポートされています。amp-video、amp-youtube、amp-3q-player、amp-brid-player、amp-dailymotion、amp-delight-player、amp-ima-video

アクション 説明
play 動画を再生します。
pause 動画を一時停止します。
mute 動画をミュートします。
unmute 動画をミュート解除します。
fullscreencenter 動画を全画面表示にします。

form

アクション 説明
clear フォームの入力の値をすべてクリアします。
submit フォームを送信します。

特殊ターゲット

以下は、AMP システムが提供する、特殊な要件を持つターゲットです。

Target: AMP

AMP ターゲットは、AMP ランタイムによって提供され、ドキュメント全体に適用されるトップレベルのアクションを実装します。

アクション 説明
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

現在のウィンドウを指定された URL に移動し、指定されている場合はオプションのターゲットで開きます（現在、_top と _blank のみがサポートされています）。オプションの opener パラメータは _blank のターゲットが使用されている場合に指定し、新たに開いたページが window.opener にアクセスできるようにします。標準的な URL 置換 をサポートしています。

警告: できる限り通常の <a> リンクを使用することが推奨されます。これは、AMP.navigateTo がウェブクローラに認識されないためです。
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

許可された場合はウィンドウを閉じます。そうでない場合は navigateTo アクションと同様に移動させます。前のページから開かれた新規ウィンドウを「戻る」ボタンで閉じる必要がある場合や、開かれていなければ移動する場合の使用事例で役立ちます。

警告: できる限り通常の <a> リンクを使用することが推奨されます。これは、AMP.navigateTo がウェブクローラに認識されないためです。
goBack 履歴をさかのぼって移動します。
print 印刷ダイアログを開き、現在のページを印刷します。
scrollTo(id=STRING, duration=INTEGER, position=STRING) 現在のページの指定された要素 ID までスクロールします。
optoutOfCid 全スコープのクライアント ID をオプトアウトします。
setState({foo: 'bar'})1

amp-bind が必要です。

オブジェクトリテラルをバインド可能な状態にマージします。
pushState({foo: 'bar'})1

amp-bind が必要です。

オブジェクトリテラルをバインド可能な状態にマージし、新しいエントリをブラウザの履歴スタックにプッシュします。エントリを消去すると、変数の前の値に復元されます（この例では、foo）。

1複数のアクションとともに使用した場合、後続のアクションは、setState() または pushState() が完了するのを待ってから呼び出されます。1 つのイベント当たり、1 つの setState() または pushState() が許可されます。

Target: amp-access

amp-access ターゲットは、amp-access コンポーネントによって提供されます。

amp-access ターゲットが特別なのには、以下の理由があります。

  1. このターゲットには、任意の ID を指定できません。ターゲットは常に amp-access です。
  2. amp-access のアクションは、AMP Access 構成に応じて動的に変化します。

amp-access ターゲットの使用に関する詳細をご覧ください。