Image List

---

Alexa Image Listテンプレート（AlexaImageList）は、画像とテキストのスクロールリストを表示します。AlexaImageListは全画面テンプレートで、必要に応じてヘッダー、フッター、背景を表示できます。リストに表示する画像ベースの項目セットを提供し、リストの外観を設定できます。たとえば、区切り線を挿入したり、項目に番号を付けるかどうかを指定したりできます。ユーザーがリストから項目を選択したときに実行するコマンドを指定することもできます。

互換性

AlexaImageListは、alexa-viewport-profilesパッケージのすべての標準Viewportプロファイルで動作するように設計されています。次のプロファイルに対応しています。

• すべての円形デバイスプロファイル
• すべての横長デバイスプロファイル
• すべての縦長デバイスプロファイル
• すべてのモバイルプロファイル
• すべてのテレビプロファイル

サポートされていないViewportでAlexaImageListを使用すると、予期しない結果になることがあります。Viewportプロファイルの詳細については、Viewportプロファイルを参照してください。

alexa-layoutsパッケージをインポートする

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

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

AlexaImageListのパラメーター

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

名前	型	デフォルト	説明	ウィジェットのサポート	追加されたバージョン
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
backgroundVideoSource	ビデオソース	—	背景ビデオのソースです。Videoコンポーネントのsourceプロパティと同じ形式でソースを指定します。	サポートされません	1.1.0
defaultImageSource	文字列		imageSourceが定義されていないリスト項目に使用するデフォルト画像のURLです。画像コンテナーが空にならないようにするには、defaultImageSourceを指定します。imageSourceがないすべてのリスト項目に対して、同じdefaultImageSourceが使用されます。	サポートされません	1.1.0
entities	配列	—	このテンプレートにバインドするentityデータの配列です。	サポートされません	1.2.0
headerAttributionImage	文字列	—	アトリビューションの画像ソースのURLです。	サポートされません	1.1.0
headerAttributionOpacity	数値	0.8	ヘッダーのアトリビューションテキストとアトリビューション画像のopacityです。0～1の間の数値を設定します。	サポートされません	1.3.0
headerAttributionText	文字列	—	ヘッダーに表示するアトリビューションのテキストです。headerAttributionImageが指定されていない場合にのみ表示されます。	サポートされません	1.1.0
headerBackButton	ブール値	false	trueの場合、戻るボタンをヘッダーに表示します。ユーザーがこのボタンをクリックしたときに実行するコマンドを指定するには、headerBackButtonCommandプロパティを設定します。	サポートされません	1.1.0
headerBackButtonAccessibilityLabel	文字列	Back	スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。	サポートされません	1.1.0
headerBackButtonCommand	コマンド	{"type":"SendEvent","arguments":["goBack"]}	ユーザーが戻るボタンを選択したときに実行するコマンドです。	サポートされません	1.1.0
headerBackgroundColor	文字列	transparent	（任意）ヘッダーの背景色として使用する色の値です。	サポートされません	1.1.0
headerDivider	ブール値	false	trueの場合、ヘッダーの下に区切り線を表示してコンテンツと区別できるようにします。	サポートされません	1.1.0
headerTitle	文字列	—	ヘッダーに表示する第1テキストです。	サポートされません	1.1.0
hideDivider	ブール値	true	各「水平方向の項目」の下／右に表示される、次のコンテンツと区別するための区切り線の非表示を切り替えます。	サポートされません	1.6.0
hideOrdinal	ブール値	false	trueの場合、各リスト項目の横に番号を表示しません。	サポートされません	1.1.0
hintText	文字列	—	フッターに表示するヒントテキストです。正しいウェイクワードをヒントに追加するには、textToHintを使用します。imageMetadataPrimacyがfalseでない限り、小型デバイスでは表示されません。	サポートされません	1.1.0
hintTextAccessibilityLabel	文字列		ヒントテキストの説明文字列です。ユーザーがこのコンポーネントを選択すると、ボイスオーバーでこの文字列が読み上げられます。	サポートされません	1.7.0
imageAlignment	文字列	center	listItems内の項目に適用されるimageAlignmentオプションのデフォルトを設定します。AlexaImageListItemのimageAlignmentプロパティを参照してください。	サポートされません	1.1.0
imageAspectRatio	文字列	square	リスト内のすべての項目で画像のバウンディングボックスに使用するアスペクト比です。指定できる値は、square、round、standard_landscape、standard_portrait、poster_landscape、poster_portrait、widescreenです。このプロパティは、AlexaImageレスポンシブ対応コンポーネントのimageAspectRatioプロパティと同じように機能します。ただし、バウンディングボックスの高さと幅はアスペクト比に基づいて事前に定義され、変更することはできません。すべてのリスト項目は常に同じアスペクト比を使用します。	サポートされません	1.1.0
imageBlurredBackground	ブール値	false	listItems内の項目に適用されるimageBlurredBackgroundオプションのデフォルトを設定します。AlexaImageListItemのimageBlurredBackgroundプロパティを参照してください。	サポートされません	1.1.0
imageHeight	ディメンション	—	listItems内の項目に適用されるimageHeightオプションのデフォルトを設定します。リスト内の各画像は、この高さに収まるようにimageScale設定を使用して拡大縮小されます。	サポートされません	1.4.0
imageHideScrim	ブール値	false	listItems内の項目に適用されるimageHideScrimオプションのデフォルトを設定します。AlexaImageListItemのimageHideScrimプロパティを参照してください。	サポートされません	1.1.0
imageMetadataPrimacy	ブール値	true	trueの場合、小型デバイスでhintTextを非表示にし、secondaryTextとtertiaryTextを表示します。このプロパティをfalseに設定すると、secondaryTextとtertiaryTextが非表示になり、代わりにhintTextが表示されます。大型デバイスではテキスト項目とhintTextの両方を表示するスペースがあるため、このプロパティは無視されます。	サポートされません	1.1.0
imageRoundedCorner	ブール値	true	listItems内の項目に適用されるimageRoundedCornerオプションのデフォルトを設定します。AlexaImageListItemのimageRoundedCornerプロパティを参照してください。	サポートされません	1.1.0
imageScale	文字列	best-fit	listItems内の項目に適用されるimageScaleオプションのデフォルトを設定します。AlexaImageListItemのimageScaleプロパティを参照してください。	サポートされません	1.1.0
imageShadow	ブール値	true	listItems内の項目に適用されるimageShadowオプションのデフォルトを設定します。trueの場合、各リスト項目の画像の背後にドロップシャドウを表示します。	サポートされません	1.3.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	AlexaImageListItemの配列		リストに表示する項目の配列です。各項目は、AlexaImageListItemで定義されているものと同じプロパティを持つオブジェクトです。リスト項目を指定するを参照してください。	サポートされません	1.1.0
primaryAction	コマンド	—	listItems内の項目に適用されるprimaryActionオプションのデフォルトを設定します。このプロパティには、ユーザーがリストから項目を選択したときにトリガーするコマンドを設定します。AlexaImageListItemのprimaryActionプロパティを参照してください。	サポートされません	1.1.0
speechItems	任意	—	読み上げ項目の配列です。AlexaImageListテンプレートは、この配列の各項目を、対応するリスト項目のspeechプロパティに割り当てます。このプロパティは、SpeakListコマンドを使用してリスト項目を読み上げる場合に使用します。詳細については、AlexaImageListにSpeakListコマンドを使用するを参照してください。	サポートされません	1.2.0
theme	文字列	dark	色のテーマをダークまたはライトに設定します。選択されたテーマによってテンプレートの色が制御されます。	サポートされません	1.1.0
type	文字列	—	常にAlexaImageListに設定します。	サポートされません	1.1.0
videoAudioTrack	文字列	foreground	ビデオの再生時に再生するオーディオトラックです。指定できる値は、foreground、background、noneのいずれかです。	サポートされません	1.1.0
videoAutoPlay	ブール値	false	trueの場合、ドキュメントがデバイスに表示されるとビデオが自動的に再生されます。backgroundVideoSourceに値が指定されている場合に適用されます。	サポートされません	1.1.0

リスト項目を指定する

AlexaImageListテンプレートは、listItemsプロパティに項目の配列が設定されることを想定しています。各項目は、AlexaImageListItemレスポンシブ対応コンポーネントで定義されているものと同じプロパティを持つオブジェクトです。

次の例は、imageListDataというデータソース内の項目の配列を示しています。

次に、${imageListData.listItemsToShow}式を使用して、この配列をlistItemsプロパティにバインドします。

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

リスト項目のデフォルトを設定する

AlexaImageListテンプレートには、AlexaImageListItemのプロパティに対応するプロパティが含まれています。これらは、リスト項目のプロパティのデフォルト値を設定するために使用されます。

デフォルトには次の2種類があります。

• 個々の項目で設定またはオーバーライドできるデフォルト - AlexaImageListは、個々の項目に値が指定されている場合はその値を使用し、それ以外の場合はAlexaImageListに指定された値を使用します。

  たとえば、リスト全体に対してimageScaleをbest-fitに設定し、リストの1つの項目でbest-fillにオーバーライドできます。

• 常にリスト内のすべての項目に適用されるデフォルト - AlexaImageListは、常にこれらのプロパティに対してAlexaImageListで指定された値を使用します。個々の項目で対応するプロパティに値を設定しても無視されます。

  たとえば、imageAspectRatioはリスト全体に対して設定する必要があります。一部の項目を正方形として表示し、一部の項目を円として表示するリストは作成できません。リスト項目のimageAspectRatioの値は無視されます。

次の表は、デフォルトとして使用されるプロパティの一覧です。

プロパティ	項目でオーバーライド可能
defaultImageSource	×
imageAlignment	◯
imageAspectRatio	×
imageBlurredBackground	◯
imageHeight	×
imageHideScrim	◯
ImageMetadataPrimacy	×
imageRoundedCorner	◯
imageScale	◯
imageShadow	◯
primaryAction	◯

各プロパティの詳細については、AlexaImageListItemを参照してください。

各リスト項目のアクションを指定する

AlexaImageListは対話型です。ユーザーはリストの項目を選択できます。primaryActionプロパティに、ユーザーが項目を選択したときに実行するコマンドを設定します。

AlexaImageListコンポーネントでprimaryActionを設定すると、AlexaImageListはリストの各項目にこのコマンドを渡します。

個々のリスト項目でコマンドをオーバーライドするには、リスト項目自体にprimaryActionプロパティを設定します。

次の例は、SendEventコマンドを使用してスキルにUserEventリクエストを送信する方法を示しています。SendEvent.arguments配列の一部として、選択された項目を表す番号を渡します。

AlexaImageListにSpeakListコマンドを使用する

SpeakListコマンドを使用して項目のリストを読み上げるには、AlexaImageListでspeechItemsパラメーターを使用します。speechItemsプロパティに項目の配列を設定します。

SpeakListコマンドでは、読み上げる各項目にspeechプロパティが必要です。speechプロパティには、ssmlToSpeechかtextToSpeechのいずれかのトランスフォーマーの出力を設定する必要があります。このため、AlexaImageListでSpeakListを使用するには、次の手順を実行する必要があります。

• オブジェクト型のデータソースを使用して、読み上げる項目の配列を設定する。このデータソース内で、読み上げ項目の配列を処理するようにssmlToSpeechまたはtextToSpeechトランスフォーマーを設定します。
• AlexaImageListのspeechItemsプロパティを読み上げ項目リストにバインドする。
• リストでSpeakListコマンドを呼び出す。

読み上げ項目リストのデータソースを設定する

1. ドキュメントで使用するオブジェクト型のデータソースを作成します。

2. データソースで、読み上げる項目の配列をデータソースのpropertiesオブジェクト内にプロパティとして追加します。

   次の例は、listItemsToShowという配列を含むobjectデータソースを示しています。項目の配列はpropertiesオブジェクトに含まれています。

    {
      "imageListData": {
        "type": "object",
        "objectId": "imageListDataId",
        "properties": {
          "listItemsToShow": [
            {
              "primaryText": "1番目のリスト項目",
              "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png"
            },
            {
              "primaryText": "2番目のリスト項目",
              "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png"
            }
          ]
        }
      }
    }
   

3. ssmlToSpeechまたはtextToSpeechトランスフォーマーを次のように設定します。

   • inputPath - 読み上げ項目の配列です。トランスフォーマーは、指定されたパスがpropertiesオブジェクト内に存在するものと想定しています。したがって、パスにpropertiesを含める必要はありません。配列の項目がオブジェクトの場合は、そのオブジェクト内でテキストまたはSSMLを格納している特定のフィールドを指定します。
   • outputName - 文字列"speech"を設定します。AlexaImageListテンプレートは、項目のリストを処理するときに"speech"という文字列を含めるため、この文字列を正確に指定する必要があります。
   • transformer - 配列の項目の形式に応じて、ssmlToSpeechかtextToSpeechのいずれかを指定します。

   次の例は、listItemsToShow配列の各項目のprimaryTextフィールドを処理するようにtextToSpeechトランスフォーマーを設定します。

    {
      "transformers": [
        {
          "inputPath": "listItemsToShow[*].primaryText",
          "outputName": "speech",
          "transformer": "textToSpeech"
        }
      ]
    }
   

speechItemsプロパティを読み上げ項目リストにバインドする

APLドキュメントで、データバインディング式を使用してAlexaImageListのspeechItemsプロパティを読み上げ項目リストにバインドします。

前の例を引き続き使用すると、式は${imageListData.properties.listItemsToShow}となります。この例では、表示と読み上げの両方に同じprimaryTextを使用します。

リストでSpeakListコマンドを実行する

speechItemsに指定した項目をAlexaで読み上げるには、SpeakListコマンドを実行します。たとえば、onMountハンドラーからコマンドを実行して、デバイスがドキュメントを表示した後に項目を読み上げることができます。

1. AlexaImageListのlistIdパラメーターにドキュメント固有のIDを割り当てます。SpeakListを実行するには、このIDを指定する必要があります。

    {
      "type": "AlexaImageList",
      "listId": "myImageListWithItemsToSpeak",
      "listItems": "${imageListData.properties.listItemsToShow}",
      "speechItems": "${imageListData.properties.listItemsToShow}"
    }
   

2. SpeakListコマンドのcomponentIdプロパティに、listIdに指定したIDを設定します。

   次の例は、onMountハンドラーでコマンドを呼び出します。デバイスがドキュメントを表示した後にAlexaが項目を読み上げます。

    {
      "onMount": [
        {
          "type": "SpeakList",
          "delay": 5000,
          "componentId": "myImageListWithItemsToSpeak",
          "start": 0,
          "count": "${imageListData.properties.listItemsToShow.length}",
          "minimumDwellTime": 1000,
          "align": "center"
        }
      ]
    }
   

ドキュメントとデータソースの例全体を以下に示します。デバイスがドキュメントを表示した後、Alexaはリスト内にある6つの項目の第1テキストをそれぞれ読み上げます。SpeakListコマンドには5秒間の遅延が含まれているため、Alexaはリストの項目を読み上げる前に、スキル応答の通常の音声を読み上げることができます。

サンプルドキュメント： AlexaImageListとSpeakList  

データソース： AlexaImageListとSpeakList  

AlexaImageListとdynamicIndexListデータソース

AlexaImageListテンプレートはSequenceを使用します。つまり、dynamicIndexListデータソースを使用できます。dynamicIndexListデータソースを使用すると、次のような処理が可能になります。

• ユーザーがコンテンツをスクロールするにつれて、大きいリストを段階的に表示する（遅延読み込み）。
• 既に表示されているデータソースの項目を更新する。新しいドキュメントを送信することなく画面上の値を変更できます。

AlexaImageListでdynamicIndexListデータソースを使用するには

1. dynamicIndexListデータソースに記載されているdynamicIndexListの構造に従います。この構造で定義されていないほかのプロパティは含めないでください。
2. リスト項目オブジェクトをデータソースのitems配列に追加します。
3. データソースをAlexaImageListのlistItemsプロパティにバインドします。このバインドは、カスタムレイアウトのSequenceのdataプロパティにデータソースをバインドすることと同じです。

以下は、dynamicIndexListデータソースを使用するAlexaImageListを含むドキュメントの例です。

サンプルドキュメント： dynamicIndexListにバインドされたAlexaImageList  

データソース： dynamicIndexListにバインドされたAlexaImageList  

dynamicIndexListデータソースを定義する方法の詳細については、dynamicIndexListデータソースを参照してください。

データソースの管理に使用するディレクティブとリクエストの詳細については、Alexa.Presentation.APLインターフェースのリファレンスを参照してください。

AlexaImageListの例

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

---

関連トピック

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

---

---

最終更新日: 2025 年 11 月 04 日