視覚コンテンツでユーザー対話を有効にする

視覚コンテンツでユーザー対話を有効にする

Alexa Presentation Language（APL）には、ユーザーが視覚コンテンツを操作するための複数の方法が用意されています。たとえば、画面上のボタンをタップしたり、コンテンツをスクロールしたりできます。このような対話操作は、特定のコンポーネント、イベントハンドラー、コマンドを使用することで有効にします。

このドキュメントでは、有効化できるさまざまなユーザー対話の概要について説明します。

ユーザー対話のしくみ

ほとんどのユーザー対話には、ユーザーアクションをキャプチャできるイベントハンドラーと、イベントが発生したときに実行される1つ以上のコマンドが必要です。APLでは、イベントハンドラーはコンポーネントやドキュメントのプロパティとして提供されます。たとえば、TouchWrapperなどのタッチ可能なコンポーネントには、ユーザーがコンポーネントをタップしたときに押下イベントを生成するonPressプロパティがあります。ユーザーがコンポーネントをタップしたときに実行するアクションを定義するには、onPressにコマンドを割り当てます。

イベントへの応答として実行するコマンドを通じて、画面上の表示を変更したり、スキルにリクエストを送信したりできます。たとえば、SetValueコマンドを使用して、ボタンが押されたときに画面に表示されているコンテンツを変更できます。必要に応じてスキルで追加の処理を実行できるようにするには、SendEventコマンドを使用して、ボタン押下の情報を含むUserEventリクエストをスキルに送信します。スキルでは、Alexa.Presentation.APL.ExecuteCommandsディレクティブを使用して、画面上のドキュメントにコマンドを送信できます。

一部のコンポーネントでは、対話機能が自動的に提供されます。たとえば、Sequenceでは、表示されたコンテンツがコンポーネントのサイズを超えると、タッチ操作によるスクロールが自動的に有効になります。

利用可能なユーザー対話

特定の対話操作を有効にするには、その対話操作をサポートするコンポーネントを使用し、該当するイベントハンドラーのプロパティで、適切なコマンドが実行されるように定義します。

次の表は、APLドキュメントで有効にできるユーザー対話をまとめたものです。それぞれの対話操作の詳細については、表の後に続くセクションを参照してください。

対話操作 説明 コンポーネントとハンドラー

コンテンツをスクロールする

コンテンツがコンポーネントのサイズを超えたときに、ユーザーがスクロールできるようにします。

次のコンポーネントでは、基本的なスクロール機能が自動的に有効になります。

コンテンツのスクロール時にコマンドを実行するにはonScrollプロパティを使用します。

コンテンツのページ間を移動する

一連のページを表示して、ユーザーがページ間を移動できるようにします。

Pagerコンポーネントでは、コンテンツのページングが自動的に行われます。ページングの動作をカスタマイズするには、オプションのハンドラーを使用します。

  • handlePageMove - カスタムのページ遷移を作成します。
  • onPageChanged - ページの変更後にコマンドを実行します。

ボタンや画像をタップする

ユーザーが画面上のボタンをタップしてアクションを開始できるようにします。

すべてのタッチ可能なコンポーネントは、次のプロパティをサポートします。

  • onPress - ユーザーがコンポーネントをタップしたときにコマンドを実行します。
  • onDown - ユーザーがコンポーネントをタップしたまま保持したときにコマンドを実行します。
  • onMove - ユーザーがコンポーネントをタップしてドラッグしたときにコマンドを実行します。
  • onUp - ユーザーがコンポーネントをタップしたまま保持または移動した後、コンポーネントを放したときにコマンドを実行します。

その他のタッチジェスチャーを使用する

ユーザーが長押しやダブルタップなどの追加のタッチジェスチャーを実行できるようにします。

すべてのタッチ可能なコンポーネントは、次のジェスチャーハンドラーをサポートします。

  • DoublePress
  • LongPress
  • SwipeAway
  • Tap

ジェスチャーハンドラーを定義するには、コンポーネントのgesturesプロパティを使用します。

コンポーネントの上にカーソルを合わせる

ユーザーがコンポーネントの上にカーソルを合わせたときにコマンドを実行します。

すべてのコンポーネントは、次のプロパティをサポートします。

  • onCursorEnter - カーソルがコンポーネントのアクティブな領域に入ったときにコマンドを実行します。
  • onCursorExit - カーソルがコンポーネントのアクティブな領域から出たときにコマンドを実行します。

オンスクリーンキーボードでコンテンツを入力する

画面上にテキスト入力フィールドを定義して、ユーザー入力を収集します。

テキスト入力はEditTextコンポーネントによってサポートされます。このコンポーネントには、入力をキャプチャする次のプロパティがあります。

  • onTextChange - ユーザーがコンポーネントにテキストを入力したときにコマンドを実行します。
  • onSubmit - ユーザーが更新されたテキストを送信したときにコマンドを実行します。

キーボード入力に応答する

外部キーボードからのキー押下をキャプチャし、コマンドを実行します。

すべてのアクション可能なコンポーネントは、次のキーボードイベントハンドラーをサポートします。

  • handleKeyDown
  • handleKeyUp

音声で項目を選択する

ユーザーが「3番目を選択して」や「これを選択して」などと発話することで画面上の項目を選択できるようにします。

対話モデルでビルトインインテントのAMAZON.SelectIntentを使用し、スキルコードでリクエストを処理します。

ビデオプレーヤーを制御する

ビデオの再生時に、ボタンなどのオンスクリーンコントロールを提供できます。音声インテントでユーザーが再生を制御できるようにすることも可能です。

Videoコンポーネントには、onEnd、onPause、onPlayなど、ビデオの状態の変更に応答するために使用できるハンドラーがいくつかあります。ボタンの押下や音声コマンドに応答してビデオの状態を変更するには、PlayMediaコマンドとControlMediaコマンドを使用します。

このドキュメントの残りのセクションでは、利用可能な対話操作の種類と、それらを有効にするために使用する必要のあるコンポーネントおよびハンドラーについて説明します。

コンテンツをスクロールする

スクロール可能なコンポーネントに長いコンテンツを表示すると、スクロールが自動的に有効になります。コンテンツがコンポーネントのサイズを超えた場合、ユーザーはタッチしてドラッグすることでコンテンツをスクロールできます。スクロールインテントを有効にすれば、音声でコンテンツをスクロールすることもできます。

スクロールをサポートするコンポーネントは次のとおりです。

  • FlexSequence - 子項目のリストを、折り返されるスクロールリストとして表示します。子項目のサイズを不均一にすることができます。
  • GridSequence - 子項目のリストを、スクロールするグリッド形式で表示します。
  • ScrollView - 子コンポーネントを表示し、垂直方向にスクロールします。通常、長いテキストコンテンツに使用されます。
  • Sequence - 子項目のリストを、スクロールする垂直方向または水平方向のリストとして表示します。

基本的なスクロールはAPLによって自動的に処理されるため、イベントハンドラーを使用する必要はありません。必要に応じて、次のような処理を実装できます。

  • スクロール可能なコンポーネントのonScrollプロパティを使用して、コンテンツのスクロール時にコマンドを実行する。
  • Scroll、ScrollToIndex、ScrollToComponentのいずれかのコマンドを使用して、プログラムによってコンテンツをスクロールする。

スクロール可能なコンポーネントにidプロパティを設定し、次のビルトインインテントをスキルの対話モデルに追加すると、ユーザーが音声でコンテンツをスクロールできるようになります。

  • AMAZON.ScrollDownIntent
  • AMAZON.ScrollUpIntent
  • AMAZON.PageUpIntent
  • AMAZON.PageDownIntent
  • AMAZON.MoreIntent

これにより、「アレクサ、下にスクロールして」などの音声コマンドを使用してコンテンツをスクロールできます。

ビルトインインテントの詳細については、画面付きのAlexa搭載デバイスで使用できる標準ビルトインインテントを参照してください。

以下は、コンテンツのスクロールをサポートするレスポンシブ対応テンプレートの例です。

コンテンツのページ間を移動する

スライドショーのような一連のページを表示するには、Pagerコンポーネントを使用します。ユーザーはスワイプしてページ間を移動できます。

コンテンツのページングはAPLによって自動的に処理されるため、イベントハンドラーを使用する必要はありません。必要に応じて、次のような処理を実装できます。

  • PagerコンポーネントのhandlePageMoveハンドラーを使用して、カスタムのページ遷移を作成する。
  • PagerのonPageChangedプロパティを使用して、ページャーのページが完全に変更されたときにコマンドを実行する。
  • AutoPageコマンドやSetPageコマンドを使用して、プログラムによってページャーを制御する。

音声によるページ間の移動は自動的には有効になりません。音声によるページ移動に対応するには、次の手順を実行する必要があります。

  1. ページ移動用のインテントを作成します。カスタムインテントを作成することも、ビルトインインテントのAMAZON.NextIntentとAMAZON.PreviousIntentを使用することもできます。
  2. スキルコードに、ページ移動のインテントを処理するリクエストハンドラーを記述します。ハンドラーで音声リクエストに応答し、Alexa.Presentation.APL.ExecuteCommandsディレクティブとSetPageコマンドを使用してページャーのページ間を移動します。画面に表示されているページャーの情報を取得するには、スキルリクエストの視覚コンテキストを使用します。

視覚コンテキストの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。ビルトインインテントの詳細については、標準ビルトインインテントを参照してください。リクエストハンドラーの記述方法の詳細については、Alexaから送信されたリクエストを処理するを参照してください。

以下は、一連のページ間のナビゲーションをサポートするレスポンシブ対応コンポーネントの例です。

ボタンや画像をタップする

タッチ可能なコンポーネントを使用すると、ユーザーがタップしてアクションを呼び出すことができるターゲットを作成できます。ユーザーがタッチ可能なコンポーネントをタップしたときに実行するコマンドを定義できます。

すべてのタッチ可能なコンポーネントは、タップターゲットをサポートします。

  • TouchWrapper - 子コンポーネントをラップしてタッチ可能にします。TouchWrapperを使用してカスタムボタンを定義できます。また、TouchWrapperをSequenceやGridSequenceの表示項目として使用して、ユーザーがタップできる項目のリストを作成することもできます。
  • VectorGraphic - Alexa Vector Graphics（AVG）形式で定義されるScalable Vector Graphics画像を表示します。

すべてのタッチ可能なコンポーネントにはonPressハンドラーがあり、押下イベントが発生したときに実行するコマンドを定義します。押下イベントは、ユーザーがコンポーネントをタッチして放したときなど、ポインターダウンイベントの後にポインターアップイベントが続いたときに発生します。ユーザーがコンポーネントをタッチしてドラッグしたときにコマンドを実行するには、onDown、onMove、onUpの各ハンドラーを使用します。詳細については、タッチ可能なコンポーネントのプロパティを参照してください。

また、スタイル内でコンポーネントのpressed状態を使用すると、ユーザーが項目を押したときにコンポーネントの外観を変更できます。詳細については、APLスタイルの定義と評価を参照してください。

以下は、コマンドを実行するタップターゲットを提供するレスポンシブ対応コンポーネントの例です。

これらの例には、SliderとSliderRadialを除いて、実行するコマンドを指定するprimaryActionプロパティがあります。レスポンシブ対応コンポーネントは、primaryActionプロパティの値をonPressに渡します。

一部のレスポンシブ対応テンプレートには、次のようにタップターゲットもあります。

その他のタッチジェスチャーを使用する

「押下」以外の追加のジェスチャーのターゲットを作成するには、タッチ可能なコンポーネントを使用します。 サポートされるジェスチャーには、ダブルタップ、長押し、スワイプして移動や、より限定的な形式のタップがあります。

すべてのタッチ可能なコンポーネントは、次のジェスチャーをサポートします。

  • TouchWrapper - 子コンポーネントをラップしてジェスチャーのターゲットにします。
  • VectorGraphic - Alexa Vector Graphics（AVG）形式で定義されるScalable Vector Graphics画像を表示します。

すべてのタッチ可能なコンポーネントには、ジェスチャーハンドラーの配列を受け取るgesturesプロパティがあります。ジェスチャーハンドラーは、DoublePressなどのジェスチャーのタイプと、そのタイプのジェスチャーが行われたときに実行するコマンドの配列を定義します。コンポーネントのデフォルトのonPressイベントをオーバーライドするには、ジェスチャーハンドラーを使用します。

ジェスチャーの動作の詳細については、ジェスチャーを参照してください。特定のジェスチャーの詳細については、以下を参照してください。

以下は、ジェスチャーを使用するレスポンシブ対応コンポーネントの例です。

コンポーネントの上にカーソルを合わせる

カーソルまたはマウスポインターのあるデバイスでは、ユーザーはコンポーネントの上にカーソルを合わせる（ホバーする）ことができます。このホバー状態が発生したときに実行するコマンドを定義できます。多くのAlexaデバイスにはカーソルがないため、ホバーは常に利用できるとは限りません。

すべてのコンポーネントはホバーターゲットになることができます。どのコンポーネントにも、onCursorEnterイベントハンドラーとonCursorExitイベントハンドラーがあります。

  • onCursorEnterは、カーソルがコンポーネントのアクティブな領域に入ったときに実行するコマンドを定義します。
  • onCursorExitは、カーソルがコンポーネントのアクティブな領域から出たときに実行するコマンドを定義します。

スタイル内でコンポーネントのhover状態を使用して、ユーザーが項目の上にカーソルを合わせたときにコンポーネントの外観を変更することもできます。詳細については、APLスタイルの定義と評価を参照してください。

レスポンシブ対応コンポーネントとテンプレートでは、onCursorEnterハンドラーやonCursorExitハンドラーを使用してコマンドが実行されることはありません。ただし、一部のコンポーネントでは次のようにhover状態が使用されます。

  • AlexaImageListなどのリストテンプレートでは、各リスト項目の上にカーソルを合わせたときに、その項目が強調表示されます。
  • AlexaTextListで序数を表示するように設定すると（hideOrdinalがfalse）、各リスト項目の上にカーソルを合わせたときに、その項目の番号が強調表示されます。
  • AlexaCardコンポーネントでは、カードの上にカーソルを合わせたときに、そのカードが強調表示されます。

キーボードでコンテンツを入力する

ユーザーからの入力を収集するには、EditTextコンポーネントを使用します。ハードウェアキーボードのないデバイスでは、コンポーネントがフォーカスを受け取ると、オンスクリーンキーボードが表示されます。

EditTextコンポーネントには、次のイベントハンドラーがあります。

  • onTextChangeは、ユーザーがコンポーネントにテキストを入力したときに実行するコマンドを定義します。
  • onSubmitは、ユーザーが更新されたテキストを送信したときに実行するコマンドを定義します。

キーボード入力に応答する

キーの押下をキャプチャしてコマンドを実行するには、キーボードイベントハンドラーを使用します。

すべてのアクション可能なコンポーネントは、handleKeyUpプロパティとhandleKeyDownプロパティによってキーボードイベントハンドラーをサポートします。アクション可能なコンポーネントには以下があります。

これらのハンドラーは、ドキュメントレベルで定義することもできます。

KeyDownイベントとKeyUpイベントをキャプチャしてwhenを使用すると、特定のキーストロークに応答してコマンドを実行できます。

音声で項目を選択する

画面上の項目をユーザーが音声で選択できるようにするには、AMAZON.SelectIntentビルトインインテントを使用し、コードにハンドラーを記述します。次のような発話を有効にすることができます。

  • 項目のリストの場合： 「3番目を選択して」
  • APLドキュメントの場合： 「これを選択して」

このような発話が行われると、スキルには、画面上のコンテンツに関する情報を含むIntentRequestが送信されます。その後、スキルでユーザーのリクエストに基づいて適切なアクションを実行できます。スキルのコードにAMAZON.SelectIntentリクエストのハンドラーを追加して、次の処理を行います。

  • リクエストの視覚コンテキストを使用して、ユーザーが発話したときに表示されていたドキュメントを特定します。視覚コンテキストは、リクエストのトップレベルにあるcontextプロパティ内のAlexa.Presentation.APLプロパティで提供されます。tokenプロパティには、ドキュメントを表示したRenderDocumentディレクティブでドキュメントに使用されたトークンが含まれています。
  • AMAZON.SelectIntentで提供されたスロット値を使用してユーザーのリクエストを特定し、適切なアクションを実行します。

以下は、AMAZON.SelectIntentリクエストを示すIntentRequestの例です。この例では、デバイスにリストが表示されていて、ユーザーが「3番目を選択して」と言ったものとします。 ドキュメントを識別するtokenはlaunchRequestDocumentです。ListPositionは、ユーザーが3番目の項目を指定したことを示しています。簡潔にするために、この例ではいくつかのリクエストプロパティを省略しています。

以下の例は、ユーザーが同じドキュメントで「これを選択して」と言った場合のIntentRequestを示しています。Anaphorスロットの値は「これ」になります。 ここでもtokenを使用して、ユーザーが発話時に表示していたドキュメントを特定します。

視覚コンテキストの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。AMAZON.SelectIntentの詳細については、項目選択のためのAPLサポートを参照してください。リクエストハンドラーの記述方法の詳細については、Alexaから送信されたリクエストを処理するを参照してください。

AMAZON.SelectIntentは、複数の項目を番号順に表示するAPLドキュメントで最適に動作します。ほかの項目（ボタンやその他のコントロール）を音声対応にするには、ユーザーのリクエストを受け取るカスタムインテントを作成します。視覚コンテキストを使用して、ユーザーに表示されていたコンテンツと、ユーザーがリクエストで参照した項目を特定します。

ビデオプレーヤーを制御する

単一のビデオまたは一連のビデオを再生するには、Videoコンポーネントを使用します。ユーザーがビデオ再生を制御できるように、ボタンや音声コントロールを提供することもできます。

  • ドキュメントの読み込み時に自動的に再生を開始するには、autoplayプロパティをtrueに設定します。
  • 再生を開始するには、PlayMediaコマンドを使用します。
  • 再生を制御するには、ControlMediaコマンドを使用して、play、pause、rewindなどのサブコマンドを指定します。

Videoコンポーネントには、プレーヤーの状態が変更されたときに実行されるイベントハンドラーがいくつか含まれています。

  • onEnd - 最後のビデオトラックの再生が終わったときに実行されます。
  • onPause - ビデオが再生中から一時停止に切り替えられたときに実行されます。
  • onPlay - ビデオが一時停止から再生中に切り替えられたときに実行されます。
  • onTimeUpdate - 再生位置が変更されたときに実行されます。
  • onTrackUpdate - 現在のビデオトラックが変更されたときに実行されます。
  • onTrackReady - 現在のトラックの状態がreadyに変更されたときに実行されます。
  • onTrackFail - エラーの発生によってビデオプレーヤーがメディアを再生できないときに実行されます。

たとえば、onPlayハンドラーとonPauseハンドラーは、画面上の「再生／一時停止」ボタンの状態を更新するために使用されるのが一般的です。Videoハンドラーを使用すると、ユーザーがボタンをタップしたか音声コマンドを使用したかにかかわらず、ボタンとビデオの状態の同期を保つことができます。

音声によるビデオの制御は自動的には有効になりません。音声コントロールを提供するには、次の手順を実行する必要があります。

  1. ビデオコントロール用のインテントを追加します。ビルトインインテントの中には、AMAZON.PauseIntent、AMAZON.ResumeIntent、AMAZON.NextIntentなど、一般的な発話に使用できるものがいくつかあります。
  2. スキルコードに、インテントを処理するリクエストハンドラーを記述します。ハンドラーでは、Alexa.Presentation.APL.ExecuteCommandsディレクティブとControlMediaコマンドを使用して音声リクエストに応答できます。画面に表示されているビデオの情報を取得するには、スキルリクエストの視覚コンテキストを使用します。

視覚コンテキストの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。ビルトインインテントの詳細については、標準ビルトインインテントを参照してください。リクエストハンドラーの記述方法の詳細については、Alexaから送信されたリクエストを処理するを参照してください。

AlexaTransportControlsレスポンシブ対応コンポーネントは、ビデオプレーヤーコントロールのセットを提供します。このコンポーネントには、ドキュメント内のVideoコンポーネントの識別子を指定します。

このページは役に立ちましたか？

最終更新日: 2025 年 12 月 17 日