ウィジェットリファレンス
ウィジェットでは、ドキュメント、データバインディング、APL Extensionなど、標準的なAlexa Presentation Language（APL）の機能を使用します。また、ウィジェット固有のAPIとインターフェースも使用します。以降のセクションに、ウィジェットに関連する情報をまとめます。
ウィジェットのAPLドキュメント
APLドキュメントは、表示するテンプレートを定義するJSONオブジェクトです。ウィジェットの場合、ドキュメントはデバイスがウィジェットパネルにウィジェットを表示する際に表示されるテンプレートを定義します。ウィジェットのAPLドキュメントでは、全画面テンプレートのドキュメントと同じ構造を使用します。APLドキュメント構造のリファレンスについては、APLドキュメントを参照してください。
APLコマンド
APLコマンドを使用すると、画面表示の体裁を変更したり、スキルにメッセージを送信したりできます。コマンドは複数の場所から開始できます。
TouchWrapperのonPressハンドラーなど、ドキュメント内のAPLイベントハンドラーからAPLコマンドを実行できます。たとえば、SendEventコマンドを実行するTouchWrapperコンポーネントを定義して、ウィジェットからスキルにリクエストを送信できます。Alexa.Presentation.APL.ExecuteCommandsディレクティブを使用して、スキルからウィジェットにコマンドを送信できます。このディレクティブは、APLドキュメント全体にコマンドを送信するために使用するディレクティブと同じものです。コマンドの対象をウィジェットにするには、APLドキュメント全体の場合に指定するtokenの代わりに、ユーザーのデバイスにインストールされたウィジェットに対応するpresentationUriを指定する必要があります。
ウィジェットに対応したAPLコマンドの一覧については、APL標準コマンドを参照してください。
データバインディングとデータストア
APLドキュメントでは、データバインディングを使用して、分離したデータソースからデータを取得します。ウィジェットのAPLドキュメントでは、データバインディング式と同じ構文を使用します。ただし、以下の相違点に注意してください。
- ウィジェットのドキュメントは、ユーザーのデバイスのデータストアからデータを取得できます。データストアを使用することで、ウィジェットはスキルにリクエストを再送信して応答を待つことなくデータにアクセスできます。データバインディング式でデータストアにアクセスするには、APLドキュメントでデータストアExtensionを使用する必要があります。
- ウィジェットのドキュメントは、全画面テンプレートのドキュメントと同じように、データソースからデータを取得することもできます。ただし、データソースはAlexaがユーザーのデバイスにインストールするAPLパッケージに含まれています。Alexaがウィジェットをインストールした後は、スキルによるデータソースの更新はできません。以下に、データソースとデータストアの使い分けの基準を示します。
- 最初のウィジェットデータと静的なコンテンツにはデータソースを使用します。
- ユーザーがウィジェットのインストールを選択した後に更新する必要があるデータにはデータストアを使用します。
データストアExtensionの詳細については、APLデータストアExtensionを参照してください。
データバインディングとデータバインディング式の詳細については、APLデータバインディングの評価とAPLデータバインディングの構文を参照してください。
APLパッケージ
APLパッケージは、特定のviewportでAPLエクスペリエンスをレンダリングするために使用するAPLドキュメントと関連アセットの自己完結型リソースです。APLパッケージを使用すると、ウィジェットのviewportでレンダリングされるAPLエクスペリエンスを定義できます。ユーザーがデバイスにウィジェットをインストールすると、Alexaがデバイスにパッケージをインストールします。その後、デバイスがパッケージのコンテンツを使用してウィジェットパネルでウィジェットをレンダリングします。
パッケージには、APLドキュメント、最初のデータソース、マニフェストが含まれます。
APLパッケージ構造の詳細については、APLパッケージリファレンスを参照してください。
ウィジェットのリクエストと応答のインターフェース
以下のスキルのリクエストと応答のインターフェースでは、デバイスでAPLパッケージとデータストアを管理するためのリクエストを利用できます。
- Alexa.DataStoreインターフェース – デバイスのデータストアを更新すると発生する可能性のあるエラーについてスキルに通知するリクエストを利用できます。このインターフェースの詳細については、Alexa.DataStoreインターフェースのリファレンスを参照してください。
- Alexa.DataStore.PackageManagerインターフェース – Alexaがデバイスでウィジェットをインストール、削除、更新したときにスキルに通知するリクエストを利用できます。このインターフェースの詳細については、Alexa.DataStore.PackageManagerインターフェースのリファレンスを参照してください。
- Alexa.Presentation.APLインターフェース – APLを操作するための標準的なディレクティブとイベントを利用できます。このインターフェースはウィジェットで使用できます。使い方は、APLドキュメント全体の場合と同様です。APLドキュメントはスキルに
UserEventリクエストを送信できます。スキルは、ExecuteCommandsディレクティブで実行するコマンドをウィジェットに送信できます。
ウィジェットが表示されているときにAlexaがスキルにリクエストを送信する場合、そのリクエストにはウィジェットに関する情報が含まれます。詳細については、スキルのリクエスト内のウィジェットに関する情報を参照してください。
データストアREST API
データストアREST APIには、デバイスのデータストアを更新するためのオペレーションが用意されています。このAPIを使用すると、スキルに送信されたリクエストから、そしてスキルセッション外からデータストアに更新をプッシュできます。このAPIを使用してデータストアコマンドをデバイスに送信し、データストアを更新します。
データストアREST APIの詳細については、データストアREST APIリファレンスを参照してください。
データストアコマンド
データストアコマンドを使用して、デバイスのデータストアを更新および管理します。データストアコマンドの送信には、Alexa.DataStoreインターフェースとデータストアREST APIの両方を使用できます。データストアコマンドは、APLドキュメント内で使用するAPLコマンドとは異なります。
コマンドの詳細については、データストアコマンドリファレンスを参照してください。
ウィジェットで対応していないAPL機能
ウィジェットはデバイスのウィジェットパネルに表示されます。このインターフェースが原因で、ウィジェットが対応していないAPL機能もあります。
データバインディングコンテキストのenvironmentオブジェクトには、一部の非対応機能にtrueを返すフラグが含まれています。
| 機能 | 非対応フラグ |
|---|---|
|
編集可能なテキストフィールド用の |
|
|
ビデオ再生用の |
|
|
|
|
|
ユーザーはウィジェットパネルで長押しジェスチャーを使用して、ウィジェットを削除したり並べ替えたりします。 |
なし |
|
動的なデータソース。 データストアREST APIまたはAlexa.DataStoreインターフェースでデータストアの項目の一覧を更新するには、一覧全体を送信する必要があります。 |
なし |
|
このジェスチャーには対応していますが、推奨しません。ウィジェット内でスワイプジェスチャーを使用すると、ウィジェットパネルを拡大したり閉じたりする操作の妨げとなり、ユーザーが混乱する可能性があります。 |
なし |
関連トピック
最終更新日: 2023 年 09 月 11 日