APLコマンドの概要



APLコマンドの概要

コマンドは、画面上のコンテンツの視覚および音声の表現を変更するメッセージです。コマンドはAlexaから受け取ることも(通常は音声の発話に対する応答)、APLドキュメントでイベントハンドラーが生成することもあります(たとえば、ボタンが押されたことへの応答など)。コマンドはコンテンツの操作、ドキュメントのシーンの切り替え、音声と視覚表示の同期に使われます。

具体的なコマンドについては、APL標準コマンドAPLメディアコマンドを参照してください。

コマンドと画面アクション

コマンドがサポートするシーンでのアクションには、次のタイプがあります。

  • シーン内をナビゲートする
    • ScrollViewまたはSequenceをスクロールする
    • スクロールしてコンポーネントを表示する
    • Pagerで表示されるページを変更する
  • 音声
    • 単一コンポーネントのオーディオコンテンツを読む
    • 2つ以上のコンポーネントのオーディオコンテンツを読む

コマンドの評価

コマンドの個々のプロパティはデータバインディングをサポートします。コマンドは、そのコマンドの発行要因に関する情報を含むeventプロパティとコマンド受信者のターゲットプロパティが追加された、ソースデータのバインディングコンテキストの組み合わせで評価されます。

イベントの内容

コマンドはソースデータのバインディングコンテキストで評価を行います。Alexaから受け取られたコマンドは、最上位レベルのデータバインディングコンテキストで評価を行います。つまりこれは、viewportと環境が定義された、名前付きリソースにアクセスできるデータバインディングコンテキストです。画面タッチなどのAPLのイベントに応答して発行されたコマンドは、コマンドが定義されているローカルデータのバインディングコンテキストで評価を行います。次にTouchWrapperのサンプルを示します。

{
  "type": "TouchWrapper",
  "bind": [
    "name": "myRandomData",
    "value": 24.3
  ],
  "onPress": {
    "type": "SendEvent",
    "arguments": [ "値は${myRandomData}です" ]
  }
}

TouchWrapperを押すと、最初の引数は「値は24.3です」と設定されます。

イベントの定義

ソースデータのバインディングコンテキストは、コマンドが評価されるときにイベントデータによって拡張されます。すべてのイベントデータは、eventプロパティで利用可能です。eventプロパティにはsourceサブプロパティが含まれています。これは、イベントを発生させたコンポーネントに関してシステムから提供される情報です。

"event": {
  "source": {
    "type": COMPONENT_TYPE,
    "handler": EVENT_HANDLER,
    "id": SOURCE_COMPONENT_ID,  // If assigned
    "value": SOURCE_COMPONENT_VALUE
  },
  "target": {
    PROP1: VALUE1,
    PROP2: VALUE2,
    ...
  }
}

Source

ペイロードのsourceセクションは、イベント発生要因に関するメタ情報です。このsourceセクションは、スキル開発者ではなくAPLランタイムによって生成されます。この情報はスキル開発者が使うこともできますが、分析目的で使用することも意図しています。sourceオブジェクトには、次の値が含まれます。

プロパティ 必須 説明
type 文字列 このメッセージを開始したコンポーネントの型です。
handler 文字列 このメッセージを開始したイベントハンドラーの名前です。たとえば、「Press」や「Checked」です。通常イベントハンドラーは頭にonを付けて「onXXXXX」と命名されます。このハンドラーは慣例的に「XXXX」としてレポートされます。
id 文字列 このメッセージを開始したコンポーネントのIDです。
value 任意 このメッセージを開始したコンポーネントの値です。

次の表では、標準的なsourceの値を示します。

コンポーネントのタイプ
TouchWrapper チェック済みの状態
Pager 現在のページインデックス
ScrollViewSequence 最上部からのスクロールビューの高さの割合

明示されるsource値については、個々のコンポーネントの定義を参照してください。

関連トピック: APL標準コマンドおよびAPLメディアコマンド

Target

targetプロパティは、イベントを受け取るコンポーネントについての状態情報を提供します。targetプロパティの値は、コンポーネントごとに定義されます。標準的なtarget値をいくつか以下に示しますが、この値はコンポーネントによって異なります。

プロパティ 説明 レポート元
color 現在の色 Text
height 数値 高さ(dp) コンポーネント
id 文字列 コンポーネントID コンポーネント
opacity 数値 コンポーネントの不透明度 コンポーネント
source 文字列 画像のソースURL Image
text 文字列 表示されるテキスト Text
width 数値 幅(dp) コンポーネント

式の評価

  • コマンドの中には、componentId値をtargetとするものがあります。ただし、コンポーネントがコマンドを発行し、そのコマンドが同じコンポーネントをターゲットにする場合、componentIdは省略できます。ExecuteCommandsディレクティブを使用する場合は、componentIdを指定する必要があります。

  • コマンドのデータバインディング式は、コマンドを定義するときではなく、コマンドを実行するときに評価されます。たとえば、ExecuteCommandsディレクティブが、グローバルデータバインディングコンテキストを参照するデータバインディング式を含んでいる場合があります。これらの式は、デバイスでコマンドが実行されたときに評価されます。コマンドがクラウドで作成されたときではありません。

  • イベントハンドラーとExecuteCommandsディレクティブの両方が、実行するコマンドの配列を取り出します。配列はrepeatCountが0であるSequential commandと同様に扱われます。