ウィジェットリファレンス
ウィジェットでは、ドキュメント、データバインディング、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リファレンスを参照してください。
ウィジェットでサポートされないAPL機能
ウィジェットは、デバイスのウィジェットパネルに表示されます。このようなインターフェースが原因で、ウィジェットではサポートされないAPL機能もあります。
データバインディングコンテキストのenvironmentオブジェクトには、一部の非対応機能に対してtrueを返すフラグが含まれています。
| 機能 | 非対応フラグ |
|---|---|
|
編集可能なテキストフィールド用の |
|
|
ビデオ再生用の |
|
|
|
|
|
ウィジェットパネルでの長押しジェスチャーは、ウィジェットを削除したり並べ替えたりするために使用されます。 |
なし |
|
動的なデータソース。 データストアREST APIまたはAlexa.DataStoreインターフェースを使用してデータストアの項目のリストを更新するには、リスト全体を送信する必要があります。 |
なし |
|
このジェスチャーはサポートされていますが、推奨されません。ウィジェット内でスワイプジェスチャーを使用すると、ウィジェットパネルを拡大したり閉じたりする操作の妨げとなり、ユーザーが混乱する可能性があります。 |
なし |
関連トピック
最終更新日: 2025 年 11 月 26 日