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

Note: Sign in to the developer console to build or publish your skill.

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は、複数の項目を含めることのできるコンポーネントです。

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

{
  "type": "APL",
  "version": "1.9",
  "description": "ハローワールドAPLドキュメント。",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.5.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100%",
        "height": "100%",
        "items": [
          {
            "type": "AlexaBackground"
          },
          {
            "type": "AlexaHeader",
            "headerTitle": "Alexa Presentation Languageへようこそ。",
            "headerSubtitle": "この例ではプリミティブとレスポンシブ対応の両方のコンポーネントを使用しています"
          },
          {
            "type": "Text",
            "height": "100%",
            "shrink": 1,
            "textAlign": "center",
            "textAlignVertical": "center",
            "text": "ハローワールド"
          }
        ]
      }
    ]
  }
}

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

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

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

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

以下の例では、「ハローワールド」ドキュメントをデータソースを使用するように更新しています。

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

{
  "type": "APL",
  "version": "1.9",
  "description": "ハローワールドAPLドキュメント。",
  "theme": "dark",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.5.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "helloworldData"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100%",
        "height": "100%",
        "items": [
          {
            "type": "AlexaBackground"
          },
          {
            "type": "AlexaHeader",
            "headerTitle": "${helloworldData.properties.title}",
            "headerSubtitle": "${helloworldData.properties.subTitle}"
          },
          {
            "type": "Text",
            "height": "100%",
            "shrink": 1,
            "textAlign": "center",
            "textAlignVertical": "center",
            "text": "${helloworldData.properties.helloText}"
          }
        ]
      }
    ]
  }
}

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

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

{
  "helloworldData": {
    "properties": {
      "title": "Alexa Presentation Languageへようこそ。",
      "subTitle": "この例ではプリミティブとレスポンシブ対応の両方のコンポーネントを使用しています",
      "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": "「クリックして」ボタンを押しました"
  }
}

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

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

条件付きロジックを使って、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コマンドが実行されてスキルにゲーム開始のリクエストが送信されます。
スキルの対話モデルにはChooseCategoryIntentインテントがあり、「{category}カテゴリーをプレイしたい」などの発話が指定されています。ユーザーが音声でカテゴリーを選び、ゲームを開始します。

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

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

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

フィードバックを送信

最終更新日: 2022 年 01 月 18 日

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

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

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

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

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

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

関連トピック

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