Text List

Alexa Text Listテンプレート（AlexaTextList）は、テキストベースのリスト項目のスクロールリストを表示します。このテンプレートは全画面に表示されるため、ヘッダーと背景を含めることができます。リストに表示する、テキストベースの一連の項目を指定します。リストの外観（区切り線を挿入する、項目に番号を付けるかどうかなど）を設定できます。ユーザーがリストから項目を選択したときに実行するコマンドも指定できます。ユーザーが項目をスワイプできるようリストを設定します。

互換性

AlexaTextListは、次のViewportプロファイルで動作するように設計されています。

• alexa-viewport-profilesパッケージの以下のウィジェットviewportプロファイル：
  • ウィジェット、中（@hubWidgetMedium）
• alexa-viewport-profilesパッケージのすべての標準viewportプロファイル：
  • すべての円形デバイスプロファイル
  • すべての横長デバイスプロファイル
  • すべての縦長デバイスプロファイル
  • すべてのモバイルプロファイル
  • すべてのテレビプロファイル

viewportプロファイルの詳細については、Viewportプロファイルを参照してください。

ウィジェットの相違点

このテンプレートをウィジェット内で使用すると、AlexaTextListは、小さいウィジェットサイズに合わせて簡略化されたリストを表示します。この場合のテンプレートには次のような違いがあります。

• 背景には色や画像を表示できますが、ビデオは表示できません。ウィジェットでは、Videoコンポーネントはサポートされません。
• リストヘッダーには、ヘッダータイトルテキストは表示されますが、アトリビューションテキスト、アトリビューション画像、サブタイトルは表示されません。
• リストヘッダーでは、戻るボタンはサポートされません。
• リスト項目には、第1テキスト、第2テキスト、画像のサムネイルが表示されます。第3テキスト、評価、項目番号は表示されません。
• リスト項目の第2テキストの位置は変更できません。
• ウィジェットではSpeakListコマンドがサポートされないため、speechItemsとSpeakListコマンドを使用してリスト項目を読み上げることはできません。

alexa-layoutsパッケージを読み込む

AlexaTextListを使用するには、alexa-layoutsパッケージをインポートします。

alexa-layoutsパッケージの最新バージョンは1.7.0です。AlexaTextListはバージョン1.1.0で導入されました。

AlexaTextListパラメーター

以下の表は、AlexaTextListで設定できるパラメーターを示しています。特に記載のない限り、標準viewportプロファイルはすべてのパラメーターをサポートします。「ウィジェットのサポート」列は、各パラメーターをサポートするウィジェットviewportプロファイルを示しています。viewportプロファイルの詳細については、Viewportプロファイルを参照してください。

type以外のパラメーターはすべてオプションです。

名前	型	デフォルト	説明	ウィジェットのサポート	追加されたバージョン
accessibilityLabel	文字列	—	リストに表示されるフッターアクションボタンを説明する文字列です。ユーザーがボタンを選択すると、ボイスオーバーでこの文字列が読み上げられます。AlexaTextListをウィジェットで使用する場合に適用されます。	中	1.5.0
backgroundAlign	文字列	center	背景画像または背景ビデオの配置を指定します。	中	1.1.0
backgroundBlur	ブール値	false	trueの場合、指定された背景画像にぼかしを入れて表示します。backgroundImageSourceに値が指定された場合にのみ適用されます。	中	1.1.0
backgroundColor	色	—	背景色として使用する色です。backgroundImageSourceとbackgroundVideoSourceのいずれにも値が含まれない場合に使用します。	中	1.1.0
backgroundColorOverlay	ブール値	false	trueの場合、背景にレイヤーを適用して、画像やビデオ上のテキストを読みやすくします。	中	1.1.0
backgroundImageSource	文字列	—	背景画像ソースのURLです。backgroundVideoSourceを指定していない場合に使用します。	中	1.1.0
backgroundOverlayGradient	ブール値	false	trueの場合、背景にグラデーションを適用します。	中	1.1.0
backgroundScale	文字列	best-fill	背景画像または背景ビデオのサイズを調整する方法を指定します。	中	1.1.0
backgroundVideoAudioTrack	文字列	foreground	ビデオを再生する際に流すオーディオトラックです。指定できる値は、foreground、background、noneのいずれかです。	サポートされません	1.1.0
backgroundVideoAutoPlay	ブール値	false	trueの場合、ドキュメントがデバイスに表示されるとビデオが自動的に再生されます。backgroundVideoSourceに値が指定された場合に適用します。	サポートされません	1.1.0
backgroundVideoSource	ビデオソース	—	背景ビデオのソースです。Videoコンポーネントのsourceプロパティと同じ形式でソースを指定します。	サポートされません	1.1.0
buttonStyle	文字列	—	フッターアクションボタンのスタイルです。containedまたはingressに設定します。どのスタイルを使用すればよいかの詳細については、ボタンの外観を参照してください。ボタンの色はテーマによって決まります。ウィジェット以外のViewportでドキュメントを表示する場合は適用されません。	中	1.5.0
buttonText	文字列	—	フッターアクションボタンに表示するテキストです。ボタンの目的を示します。ウィジェット以外のViewportでドキュメントを表示する場合は適用されません。	中	1.5.0
enableReorder	ブール値	false	trueの場合、ユーザーは上向きと下向きのボタンを使用してリスト項目の順序を変更できます。	サポートされません	1.7.0
entities	配列	—	このテンプレートにバインドするentityデータの配列です。	中	1.2.0
headerAttributionImage	文字列	—	アトリビューションの画像ソースのURLです。headerAttributionPrimacyがtrueの場合、またはタイトル／サブタイトルとアトリビューションの両方を表示するデバイスの場合に表示されます。	サポートされません	1.1.0
headerAttributionOpacity	数値	0.8	ヘッダーのアトリビューションテキストとアトリビューション画像にopacityを設定します。0と1の間の数値を設定します。	サポートされません	1.3.0
headerAttributionPrimacy	ブール値	true	trueの場合、画面サイズの制約のために1つの要素しか表示されないデバイスでは、headerAttributionImageを表示します。falseの場合、headerTitleとheaderSubtitleを表示します。	サポートされません	1.1.0
headerAttributionText	文字列	—	ヘッダーで表示するアトリビューションのテキストです。headerAttributionImageに値が含まれず、かつheaderAttributionPrimacyがtrueの場合、またはデバイスがタイトル／サブタイトルとアトリビューションの両方を表示する場合に表示されます。	サポートされません	1.1.0
headerBackButton	ブール値	false	trueの場合、戻るボタンをヘッダーに表示します。	サポートされません	1.1.0
headerBackButtonAccessibilityLabel	文字列	Back	スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。	サポートされません	1.1.0
headerBackButtonCommand	コマンド	{"type":"SendEvent","arguments":["goBack"]}	ユーザーが戻るボタンを選択したときに実行するコマンドです。	サポートされません	1.1.0
headerBackgroundColor	文字列	transparent	ヘッダーの背景色として使用するオプションの色の値です。	中	1.1.0
headerSubtitle	文字列	—	ヘッダーに表示する第2テキストです。	サポートされません	1.1.0
headerTitle	文字列	—	ヘッダーに表示する第1テキストです。	中	1.1.0
headerTitleCanUseTwoLines	ブール値	false	trueの場合、ウィジェット内の長いheaderTitleテキストを必要に応じて2行に折り返します。ウィジェットViewportプロファイルにのみ適用されます。標準のAPL Viewportに表示されている場合は無視されます。	中	1.5.0
hideDivider	ブール値	false	trueの場合、リストの各項目の下に表示される横方向の区切り線を非表示にします。	中	1.1.0
hideOrdinal	ブール値	false	trueの場合、各リスト項目の横に番号を表示しません。	サポートされません	1.1.0
lang	文字列	${environment.lang}	テンプレートに表示されるテキストの言語です。この言語によって、テキストに使用されるデフォルトのフォントが決まります。たとえば、ar-SAに設定すると、コンポーネントはデバイスでアラビア語フォントが利用可能であれば使用します。BCP-47文字列に設定します。 レスポンシブ対応コンポーネントの言語固有のフォントの詳細については、コンポーネントとテンプレートでの言語固有のフォントを参照してください。	中	1.4.0
layoutDirection	文字列	${environment.layoutDirection}	コンテンツのレイアウト方向を指定します。このプロパティは、LTR（左から右）またはRTL（右から左）に設定します。このプロパティには、コンポーネントの親コンテナーのlayoutDirectionは継承されません。このため、必要に応じて明示的にこのプロパティを設定してください。 レスポンシブ対応コンポーネントでの右から左に記述する言語のサポートの詳細については、右から左に記述する言語のサポートを参照してください。	中	1.4.0
listId	文字列	—	リストとして使用されるSequenceコンポーネントに割り当てるIDです。ビルトインインテントを使用して音声でスクロールできるようにするには、listIdに値を設定します。SpeakListコマンドを使用する場合など、リストをコマンドのターゲットとして指定する必要がある場合も、このパラメーターにIDを設定します。	中	1.2.0
listItems	listItemsの配列	—	リストに表示するテキストリスト項目の配列です。	中	1.1.0
onReorder	配列	—	ユーザーがリストを並べ替えたときに実行するコマンドの配列です。reorderListItemsDataBindingNameを設定した場合に使用されます。	サポートされません	1.7.0
onSwipeDone	任意	—	ユーザーがスワイプアクションを完了した場合に実行するコマンドです。		1.2.0
onSwipeMove	任意	—	ユーザーが項目をスワイプしているときに実行するコマンドです。	サポートされません	1.2.0
optionsButton1Command	任意	—	オプションリストの最初のボタンにバインドするコマンドです。テレビデバイスにのみ使用します。	サポートされません	1.2.0
optionsButton1Text	文字列	—	オプションリストの最初のボタンのテキストです。テレビデバイスにのみ使用します。	サポートされません	1.2.0
optionsButton2Command	任意	—	オプションリストの2番目のボタンにバインドするコマンドです。テレビデバイスにのみ使用します。	サポートされません	1.2.0
optionsButton2Text	文字列	—	オプションリストの2番目のボタンのテキストです。テレビデバイスにのみ使用します。	サポートされません	1.2.0
primaryAction	コマンドの配列	—	標準Viewportで使用した場合、独自のprimaryActionコマンドが定義されていないリスト項目で実行するデフォルトアクションを定義します。 ウィジェットで使用した場合、ユーザーがフッターアクションボタンを選択したときに実行するコマンドを定義します。このコマンドは、独自のprimaryActionコマンドが定義されていないリスト項目のデフォルトアクションとしても使用されます。	中	1.1.0
reorderListItemsDataBindingName	文字列		listItemsのデータバインディングパラメーター名です。並べ替え機能にユーザー定義のデータバインディングを使用する場合は必須です。	サポートされません	1.7.0
speechItems	任意	—	読み上げ項目の配列です。テンプレートは、この配列の各項目を、対応するリスト項目のspeechプロパティに割り当てます。このプロパティは、SpeakListコマンドを使用してリスト項目を読み上げる場合に使用します。	サポートされません	1.2.0
stickyButton	ブール値	false	trueの場合、フッターアクションボタンをウィジェットの下部に固定します。ボタンはテキストリストに重ねて常に表示されます。falseの場合、フッターアクションボタンをリスト項目の後に表示します。ウィジェット以外のViewportでドキュメントを表示する場合は適用されません。	中	1.5.0
swipeActionIcon	文字列	—	スワイプ中に表示するカスタムアイコンのソースです。swipeActionIconTypeがAVGの場合、このプロパティには、graphicsプロパティまたはインポートされたパッケージで定義されているグラフィックの名前を設定します。swipeActionIconTypeがimageの場合、表示する画像のURLを指定します。	中	1.2.0
swipeActionIconBackground	色	—	ユーザーが項目をスワイプしたときにアクションアイコンの背後に表示する背景色です。	中	1.2.0
swipeActionIconForeground	文字列	—	ユーザーが項目をスワイプしたときに表示するアクションアイコンの色です。	中	1.2.0
swipeActionIconType	文字列	—	カスタムのswipeActionIconに使用するグラフィックの種類です。AVGまたはimageに設定します。imageに設定した場合は、swipeActionIconに画像のURLを指定します。AVGに設定した場合は、ドキュメントのgraphicsプロパティでAVGを定義するか、インポートされたパッケージで定義されているグラフィックを使用し、swipeActionIconにグラフィックの名前を設定します。	中	1.2.0
swipeDirection	文字列	—	リスト内の項目に使用するスワイプジェスチャーの方向です。backwardまたはforwardに設定すると、ユーザーがリスト内で項目をスワイプできるようになります。下位互換性のために、このプロパティはleftまたはrightに設定することもできます。設定しない場合、リスト項目はスワイプジェスチャーをサポートしません。	中	1.2.0
theme	文字列	dark	色のテーマをダークまたはライトに設定します。テーマを選択することでテンプレートの色を制御します。		1.1.0
touchForward	ブール値	false	trueの場合、ユーザーが画面をタッチできるほど近くにいる（視聴距離が1m以内）と想定し、リスト項目のフォントサイズを小さくします。falseの場合、ユーザーが画面をタッチできるほど近くにはいない（音声で操作する）と想定し、大きいフォントサイズを使用します。	中	1.1.0
type	文字列	—	常にAlexaTextListに設定されます。	中	1.1.0

リスト項目を指定する

AlexaTextListレイアウトは、listItemsプロパティに項目の配列が設定されることを想定しています。各項目は、AlexaTextListItemまたはAlexaSwipeToActionレスポンシブ対応コンポーネントで定義されたプロパティを持つオブジェクトです。ウィジェット内で使用すると、AlexaTextListItemコンポーネントでサポートされるプロパティは少なくなります。たとえば、ウィジェット内のリスト項目には評価や第3テキストを表示できません。

リスト項目の配列の例

次の例は、AlexaTextListで使用できるリスト項目の配列を示しています。

リスト項目に指定できるパラメーターは、AlexaTextListItemのバージョンによって異なります。たとえば、評価を表示するプロパティには、alexa-layoutsパッケージのバージョン1.2.0以降が必要です。すべてのプロパティについては、以下を参照してください。

• AlexaTextListItem
• AlexaSwipeToAction

listItemsプロパティにリスト項目の配列をバインドする

listItemsプロパティに項目の配列をバインドするには、次の2つの方法があります。

• データバインディング式を使用して、別のデータソースにある配列をlistItemsに設定する。

  • この方法は標準Viewportで使用します。スキルコードで、RenderDocumentディレクティブの一部としてdatasourcesオブジェクトにリスト項目の配列を含めます。
  • ウィジェットの場合は、RenderDocumentを使用するのではなく、ユーザーのデバイスにウィジェットをインストールするときにデータソースを指定します。したがって、このオプションはウィジェットの存続期間中に変更されないデータに使用してください。

• データバインディング式を使用して、デバイス上のデータストアに保存されている配列をlistItemsに設定する。その後、スキルでデータストアのコンテンツを更新して、ウィジェットに最新の情報を表示できます。

  • データストアはウィジェットで使用できます。標準Viewportに表示されるAlexa Presentation Language（APL）ドキュメントでは、データストアを使用することはできません。
  • データストアExtensionを使用し、リージョン、名前空間、キーを設定して、dataTypeがARRAYに設定された項目にマップする必要があります。
  • 例については、AlexaTextListをウィジェットのデータストアにバインドする例を参照してください。

listItemsプロパティには、APLドキュメント内の静的配列を設定することもできます。この方法はテストに役立ちますが、ベストプラクティスではありません。可能な場合は、データバインディングを使用して配列をリストに渡してください。

AlexaTextListをウィジェットのデータストアにバインドする例

次の例では、データストアExtensionを有効にしてDataStoreという名前を割り当てます。次に、DataStore.dataBindingsプロパティでDS_ListItemsという名前のデータバインディングを定義して、指定されたリージョン、名前空間、キーにマップします。このデータバインディングのdataTypeをARRAYに設定します。

これで、${DS_ListItems}というデータバインディング式により、スキルがデータストアに保存する配列を参照できます。したがって、次のAlexaTextListテンプレートのインスタンスはリストを表示します。

Alexa.DataStore.ExecuteCommandsディレクティブまたはデータストアREST APIで次のデータストアコマンドを使用すると、データストアの指定した領域に、AlexaTextList用にフォーマットされた項目の配列を入力できます。

テキストリストのタップアクションを指定する

AlexaTextListは対話型です。標準Viewportでは、ユーザーはヘッダーの戻るボタンをタップしたり、リストの各項目を選択したりできます。ウィジェットでは、ユーザーはオプションのフッターアクションボタンや個々のリスト項目をタップできます。次の表に示すように、これらのアクションに応答して実行するコマンドを指定できます。

タップターゲット	標準Viewportでの設定	ウィジェットでの設定
ヘッダー	ヘッダーの戻るボタンを設定できます。 headerBackButtonをtrueに設定します。 headerBackButtonAccessibilityLabelに、スクリーンリーダーを使用するユーザー向けに戻るボタンを説明する文字列を設定します。 headerBackButtonCommandに、ユーザーが戻るボタンをタップしたときに実行するコマンドの配列を設定します。	該当なし
フッターアクションボタン	該当なし	buttonTextプロパティに、ボタンに表示するテキストを設定します。 primaryActionに、ユーザーがボタンをタップしたときに実行するコマンドの配列を設定します。 primaryActionプロパティは、個々のリスト項目で実行するデフォルトコマンドも定義します。フッターアクションボタンでこのプロパティを使用した場合、個々のリスト項目でデフォルトをオーバーライドできます。または、イベントソースに応じて異なるアクションを実行するコマンドを記述することもできます。例については、AlexaTextListの例にあるウィジェットの例を参照してください。
個々のリスト項目	すべてのリスト項目で実行するデフォルトコマンドを設定するには、primaryActionにコマンドの配列を設定します。 個々のリスト項目でデフォルトコマンドをオーバーライドするには、そのリスト項目のTextListItemオブジェクトでprimaryActionを設定します。	すべてのリスト項目で実行するデフォルトコマンドを設定するには、primaryActionにコマンドの配列を設定します。primaryActionコマンドはフッターアクションボタンでも使用されます。フッターアクションボタンも使用する場合は、イベントソースに応じて異なるアクションを実行するコマンドを記述してください。例については、AlexaTextListの例にあるウィジェットの例を参照してください。 個々のリスト項目でデフォルトコマンドをオーバーライドするには、そのリスト項目のTextListItemオブジェクトでprimaryActionを設定します。

ユーザーがリスト項目をスワイプできるようにする

ユーザーがリスト項目をスワイプしてアクションを実行できるようにするには、swipeDirectionプロパティを次のいずれかの値に設定します。

• backward
• forward
• left（下位互換性のために提供）
• right（下位互換性のために提供）

次に、その他のスワイプ関連のプロパティを必要に応じて設定します。これらのプロパティは、AlexaSwipeToActionのプロパティと対応しています。

• swipeActionIcon
• swipeActionIconType
• swipeActionIconForeground
• swipeActionIconBackground
• onSwipeMove
• onSwipeDone
• optionsButton1Text
• optionsButton1Command
• optionsButton2Text
• optionsButton2Command

スワイプアクションの詳細とテキストリスト内でAlexaSwipeToActionを使用する例については、AlexaTextList内のAlexaSwipeToActionを参照してください。

ユーザーがリスト項目の順序を変更できるようにする

テキストリストは、ユーザーがリスト内で項目を上下に移動できるように設定することが可能です。並べ替え機能は、Hub Round Smallを除くすべての標準Viewportプロファイルでサポートされます。

リストの並べ替えを有効にするには、enableReorderプロパティをtrueに設定します。各リスト項目に上向きと下向きの矢印が表示され、ユーザーはそれをタップして項目を上下に移動できます。ユーザーが項目の上向きボタンまたは下向きボタンをタップすると、AlexaTextListテンプレートは表示されているリストを更新して変更を反映します。デフォルトでは、テンプレートはさらにSendEventを使用して、更新されたリスト項目を含むリクエストをスキルに送信します。また、onReorderプロパティに指定されている追加コマンドも実行します。

デフォルトのSendEventコマンドを使用する

次の例は、enableReorderがtrueに設定されたAlexaTextListを示しています。ユーザーが「Peonies & Petals Nursery」項目の下向き矢印をタップすると、テンプレートはSendEventコマンドを実行して、更新されたリスト項目をスキルに送信します。さらに、onReorderプロパティに指定されているSetValueコマンドも実行して、ヘッダーのサブタイトルを変更します。

---

次の例は、ユーザーがリスト内で「Peonies & Petals Nursery」を下に移動したときにスキルに送信されるUserEventリクエストを示しています。

この例のUserEventリクエストをテストするには、コードをスキルにコピーします。

並べ替えコマンドをカスタマイズする

スキルに送信されるリクエストをより細かく制御する必要がある場合は、enableReorderに加えてreorderListItemsDataBindingNameプロパティとonReorderプロパティを使用します。ユーザーが順序の変更ボタンをタップすると、AlexaTextListテンプレートは、表示されているリストを更新して変更を反映し、onReorderプロパティに指定されたコマンドを実行します。このシナリオでは、テンプレートはSendEventを自動的に実行しません。スキルにリクエストを送信する場合は、このコマンドをonReorderの一部として指定する必要があります。

ユーザーがリストを並べ替えたときに実行するコマンドをカスタマイズするには

1. 表示するリスト項目の配列を使用してbind変数を定義します。
2. bind変数の名前をreorderListItemsDataBindingNameプロパティに渡します。

3. onReorderプロパティに、ユーザーがリストを並べ替えたときに実行するコマンドの配列を設定します。

   ユーザーがボタンをタップしてリストの順序を変更すると、AlexaTextListはreorderListItemsDataBindingNameで指定されたbind変数の値を更新します。更新されたリストをスキルに送信するには、SendEventコマンドを使用してbind変数を渡します。

次の例は、reorderListItemsDataBindingNameプロパティがdynamicListItemsというbind変数に設定されたAlexaTextListを示しています。dynamicListItemsの初期値は、データソースから提供されるリスト項目の配列です。onReorderプロパティは、dynamicListItems変数をSendEventコマンドに渡して、更新されたリストを含むカスタム配列オブジェクトをスキルに送信します。

---

次の例は、ユーザーがリスト内で「Peonies & Petals Nursery」を下に移動したときにスキルに送信されるUserEventリクエストを示しています。

AlexaTextListの例

以下は、AlexaTextListの例を示しています。この例では、リスト項目を選択すると、arguments配列に"ListItemSelected"とリスト項目の番号を含むUserEventリクエストが送信されます。このイベントをテストするには、例をスキルにコピーします。

---

次の例は、データソースから静的な項目セットを表示するウィジェットを示しています。primaryActionプロパティでは、Selectコマンドをwhen文と組み合わせて、ユーザーがフッターアクションボタンをタップしたか、リスト項目をタップしたかに応じて異なるコマンドを実行します。どちらの場合も、イベントはSendEventコマンドを実行して、ユーザーがタップしたボタンまたは項目に関する情報を含むUserEventをスキルに送信します。

---

関連トピック

• APL向けAlexa Design System
• レスポンシブ対応コンポーネントとテンプレート
• Alexaデザインガイド： レスポンシブ対応テンプレート

---

---

最終更新日: 2025 年 10 月 09 日