APLの視覚応答を構成する要素

APLの視覚応答を構成する要素

以下のセクションでは、Alexa Skills Kit（ASK）を使って作成したカスタムスキルにAlexa Presentation Language（APL）を組み込むための主要な概念について説明します。

コンポーネントとレイアウトから視覚テンプレートを作成する

APLドキュメントは、テンプレートを定義するJSONオブジェクトであり、応答の構造とレイアウトを提供します。ドキュメントは、コンポーネントとレイアウトから作成します。

  • APLコンポーネントは、Viewportに表示されるプリミティブなUI要素です。たとえば、テキストボックスなどがあります。コンポーネントは、ドキュメントを構築する基本的な構成要素です。
  • レイアウトは、視覚コンポーネントを組み合わせて再利用可能なテンプレートに統合したもので、名前を付けることができます。その名前を参照することで、ドキュメントにレイアウトを配置できます。これにより、モジュール化された管理しやすいデザインを実現できます。

APLでは、視覚応答における再利用やモジュール化されたデザインを促進するその他の構造もサポートしています。

  • スタイルは、色やフォントサイズなど、視覚要素の一連の特性に名前を割り当てます。その後、スタイルをコンポーネントに割り当てることができます。スタイルを使用すると、一貫性のある視覚要素のデザインになります。スタイルは、状態の変化にも対応できます。たとえば、スタイルを使ってユーザーがボタンを押したときの視覚的な変化を定義できます。
  • リソースは、値をハードコーディングすることなく使用できる、名前付きの定数です。たとえば、赤の特定の色調を定義するmyRedというリソースを作成して、コンポーネントの色を指定するときにそのリソース名を使用できます。

  • パッケージは、すべてのドキュメント要素をまとめて複数のAPLドキュメントで使用できるようにしたものです。このパッケージをドキュメントに読み込みます。

    APL向けAlexaデザインシステムには、一連のレスポンシブ対応コンポーネントとレスポンシブ対応テンプレートが用意されています。これらは、APLのコンポーネント、スタイル、リソースをモジュール化したレスポンシブ対応レイアウトに統合したものです。これを使用することで、さまざまなViewportで機能するドキュメントを作成できます。また、独自の再利用可能なレイアウトを作成し、それらをパッケージにまとめて複数のドキュメントで使用することもできます。

APLドキュメントの複雑さは、それぞれに異なります。以下は、緑色の背景、ヘッダー、Textコンポーネントを表示するドキュメントの例です。このドキュメントでは、Containerコンポーネントを使用して3つのコンポーネントを配置しています。Containerは、複数の項目を含めることのできるコンポーネントです。

これらの概念の詳細については、以下のトピックを参照してください。

表示するコンテンツをデータソースに指定する

APLはデータバインディングをサポートしています。これにより、ドキュメントは、指定した別のデータソースからデータを取得できます。データバインディングを使用すると、ソースデータからプレゼンテーションロジック（APLドキュメント）を分離できます。

先ほどの「Hello World」ドキュメントの例では、表示するテキストはドキュメントでハードコーディングされています。しかし、データを別のデータソースに配置し、ドキュメントからそのデータソースをポイントすることでメンテナンスを容易にできます。ドキュメントを表示するディレクティブを送信するときに、スキルコードでデータソースを指定します。ユーザーの入力内容やスキルコードのほかのロジックによって変化する可能性がある場合は必ず、ドキュメントではなくデータソースにコンテンツを渡す必要があります。

以下の例では、データソースを使用するように「Hello World」ドキュメントを更新しています。Data Sourcesタブをクリックすると、このデータソースの構造を確認できます。

ドキュメントのTextコンポーネントのtextプロパティの値に、ドル記号（$）で始まり中かっこ（{ }）が続く式が含まれるようになりました。この構文は、データバインディング式です。この例の${helloworldData.properties.helloText}という式は、表示するテキストをhelloworldDataというデータソースから取得するようドキュメントに指示しています。表示するテキストはhelloworldDataのproperties.helloTextプロパティにあります。

データソースとデータバインディングの詳細については、以下を参照してください。

コマンドでドキュメントを対話型にする

APLは、視覚要素を対話的に操作できるタッチ可能なコンポーネントをサポートしています。ユーザーが画面上のコンポーネントをタップしたときにコマンドを実行するようにコンポーネントを設定できます。APLコマンドは以下の処理を実行できます。

  • 画面上の視覚エクスペリエンスを変更する。たとえば、コマンドを使ってコンポーネントのプロパティの値を変更できます。これにより、コンポーネントの外観や動作が変更されます。
  • スキルに、リクエストの形式でメッセージを送信する。スキルは、コードがIntentRequestを処理するのと同じ方法でリクエストを処理します。スキルは、音声、表示する新規ドキュメント、別のAPLコマンドを実行するディレクティブのいずれかで応答できます。

次の例は、buttonDescriptionTextというIDを持つコンポーネントのtextプロパティを変更するように設定されたSetValueコマンドを示しています。

クリップボードにコピーされました。

{
  "type": "SetValue",
  "componentId": "buttonDescriptionText",
  "property": "text",
  "value": "「クリックして」ボタンが押されました"
}

APLコマンドはさまざまな方法で実行できます。

  • タッチ可能なコンポーネントには、コマンドをトリガーできるイベントハンドラーがあります。たとえば、コマンドをタッチ可能なコンポーネントのonPressプロパティに割り当てることができます。コマンドは、ユーザーが画面上のコンポーネントを選択したときに実行されます。

    一部のレスポンシブ対応コンポーネントとテンプレートは、タッチ可能なコンポーネントを使用します。これらのコンポーネントには、コマンドの実行に使用できるプロパティがあります。たとえば、AlexaButtonレスポンシブ対応コンポーネントには、ユーザーがボタンを押したときに使用するコマンドを指定するprimaryActionプロパティがあります。

  • APLドキュメント自体には、ドキュメントの読み込み時にコマンドを実行するonMountプロパティがあります。このプロパティは、ユーザーがスキルを起動したときに再生されるウェルカムアニメーションを作成するときに役立ちます。
  • 各コンポーネントには、コンポーネントが画面上に読み込まれたときにコマンドを実行するonMountプロパティがあります。
  • ExecuteCommandsディレクティブは、スキルコードからAPLコマンドを送信します。

たとえば、次のようにAlexaButtonでprimaryActionプロパティを使用して、SetValueコマンドをトリガーできます。

クリップボードにコピーされました。

{
  "type": "AlexaButton",
  "id": "clickMeButton",
  "primaryAction": {
    "type": "SetValue",
    "componentId": "buttonDescriptionText",
    "property": "text",
    "value": "「クリックして」ボタンが押されました"
  }
}

以下の例は、AlexaButtonレスポンシブ対応コンポーネントを表示します。ボタンを押すと、SetValueコマンドがTextコンポーネントのtextプロパティを更新してメッセージを表示します。

コマンドの詳細については、以下のトピックを参照してください。

条件付きロジックでさまざまなデバイスに対応する

条件付きロジックを使って、APLドキュメントをさまざまな状況に適応させることができます。Viewportの特性やその他の要因に応じて、さまざまな方法でコンテンツを表示するAPLドキュメントを作成できます。たとえば、大きな画面では垂直方向に連続してスクロールできるリストを表示する一方、小さな画面では1つのページに各リスト項目を表示するリストを作成できます。

すべてのAPLコンポーネントとコマンドには、ブール値（true/false）を取るオプションのwhenプロパティがあります。この値は、デバイスがコンポーネントを表示するのか、それともコマンドを実行するのかを決定します。値を指定しない場合、whenプロパティのデフォルトはtrueです。

whenプロパティを使用するには、評価結果がtrueまたはfalseになるデータバインディング式を記述します。たとえば、次のステートメントでは、デバイスが小さく横長である場合に評価結果がtrueになります。

"when": "${@viewportProfile == @hubLandscapeSmall}"

この例の定数viewportProfileとhubLandscapeSmallは、alexa-viewport-profilesパッケージの一部として提供されるリソースです。アットマーク（@）は、リソースを参照する標準的な構文です。

データバインディング式を使用して、コンポーネントやコマンドにプロパティ値を条件付きで割り当てることもできます。たとえば、次の式では、小さい円形のデバイスの場合は文字列「center」を、その他の場合には文字列「left」を返します。

${@viewportProfile == @hubRoundSmall ? 'center' : 'left'}

条件付きロジックは、レスポンシブ対応のAPLドキュメントを作成する際の重要な要素です。レスポンシブ対応のAPLドキュメントは、Viewportの特性に合わせて調整できます。ユーザーはさまざまな画面サイズ、形状、アスペクト比のデバイスでスキルを呼び出すことができるため、優れたユーザーエクスペリエンスを作り出すにはレスポンシブ対応のAPLドキュメントが不可欠です。詳細と推奨事項については、レスポンシブ対応のAPLドキュメントを作成するを参照してください。

ドキュメントとデータソースをAlexaに送信する

AWS Lambda関数やウェブサービスでは、Alexa.Presentation.APLインターフェースで定義されたディレクティブとリクエストを使ってAPL関連の情報をやり取りします。

  • 応答でAlexa.Presentation.APL.RenderDocumentディレクティブを送信して、APLコンテンツを表示するようにデバイスに指示します。ドキュメントと関連データソースの両方をディレクティブの一部として含めます。
  • Alexa.Presentation.APL.ExecuteCommandsディレクティブを送信して、コマンドを実行します。これらのコマンドはドキュメントの特定の要素をターゲットとしています。たとえば、SpeakItemコマンドでは、特定のコンポーネント（Textコンポーネントなど）で定義されたテキストを読み上げるようにデバイスに指示します。
  • ドキュメントでSendEventコマンドを使用して、Alexa.Presentation.APL.UserEventリクエストを送信します。リクエストは、ユーザーがボタンをタップしたときなど、デバイス上で実行されるユーザーアクションをスキルに伝えます。コードには、これらのタイプのイベントを受け入れて処理するハンドラーを記述します。

ディレクティブとリクエストを使用して、音声とタッチの両方で機能するユーザーインターフェースを作成します。たとえば、トリビアゲームスキルでは、ユーザーがプレイしたいトリビアのカテゴリーを次の2つの方法で選択できます。

  • APLドキュメントが画面にカテゴリーのリストを表示する。ユーザーがプレイしたいカテゴリーをタップします。コマンドをタップすると、SendEventコマンドが実行されてスキルにゲーム開始のリクエストが送信されます。
  • スキルの対話モデルに「{category}カテゴリーをプレイしたい」などの発話が指定されたChooseCategoryIntentインテントがある。 ユーザーが音声でカテゴリーを選び、ゲームを開始します。

スキルコードにはAlexa.Presentation.APL.UserEventリクエストまたはChooseCategoryIntentのIntentRequestに応答するハンドラーが含まれます。ハンドラーが選択されたカテゴリーを取得し、ゲームを開始します。

ディレクティブとリクエストの詳細については、次を参照してください。

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

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