APLコマンド(1.0)



APLコマンド

(これは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
高さ 数値 高さ(dp) コンポーネント
id 文字列 コンポーネントID コンポーネント
opacity 数値 コンポーネントの不透明度 コンポーネント
source 文字列 画像のソースURL Image
text 文字列 表示されるテキスト Text
数値 幅(dp) コンポーネント

式の評価

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

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

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