Grid List

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

互換性

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

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

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

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

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

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

AlexaGridListのパラメーター

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

名前	型	デフォルト	説明	ウィジェットのサポート	追加されたバージョン
backgroundAlign	文字列	center	背景画像または背景ビデオの配置を指定します。	サポートされません	1.2.0
backgroundBlur	ブール値	false	trueの場合、指定された背景画像にぼかしを入れて表示します。backgroundImageSourceに値が指定された場合にのみ適用されます。デフォルトはfalseです。	サポートされません	1.2.0
backgroundColor	色	—	背景色として使用する色です。backgroundImageSourceとbackgroundVideoSourceのいずれにも値が含まれない場合に使用します。	サポートされません	1.2.0
backgroundColorOverlay	ブール値	false	trueの場合、背景にレイヤーを適用して、画像やビデオ上のテキストを読みやすくします。	サポートされません	1.2.0
backgroundImageSource	文字列	—	背景画像ソースのURLです。backgroundVideoSourceを指定していない場合に使用します。	サポートされません	1.2.0
backgroundOverlayGradient	ブール値	false	trueの場合、背景にグラデーションを適用します。	サポートされません	1.2.0
backgroundScale	文字列	best-fill	背景画像または背景ビデオのサイズを調整する方法を指定します。	サポートされません	1.2.0
backgroundVideoSource	ビデオソース	—	背景ビデオのソースです。Videoコンポーネントのsourceプロパティと同じ形式でソースを指定します。	サポートされません	1.2.0
customLayoutName	任意	—	各リスト項目に使用するカスタムレイアウトの名前です。未設定のままにすると、リスト項目にAlexaImageListItemレイアウトが使用されます。リスト項目を指定するを参照してください。	サポートされません	1.2.0
defaultImageSource	文字列	—	imageSourceが定義されていないリスト項目に使用するデフォルト画像のURLです。画像コンテナーが空にならないようにするには、defaultImageSourceを指定します。imageSourceがないすべてのリスト項目に対して、同じdefaultImageSourceが使用されます。	サポートされません	1.2.0
entities	配列	—	このテンプレートにバインドするentityデータの配列です。	サポートされません	1.2.0
headerAttributionImage	文字列	—	アトリビューションの画像ソースのURLです。headerAttributionPrimacyがtrueの場合、またはタイトル／サブタイトルとアトリビューションの両方を表示するデバイスの場合に表示されます。	サポートされません	1.2.0
headerAttributionOpacity	数値	小型の円形デバイスでは1、それ以外では@opacitySecondary	アトリビューションテキストとアトリビューション画像の不透明度です。	サポートされません	1.3.0
headerAttributionPrimacy	ブール値	true	trueの場合、画面サイズの制約のために1つの要素しか表示されないデバイスでは、headerAttributionImageを表示します。falseの場合、headerTitleとheaderSubtitleを表示します。	サポートされません	1.2.0
headerAttributionText	文字列	—	ヘッダーで表示するアトリビューションのテキストです。headerAttributionImageに値が含まれず、かつheaderAttributionPrimacyがtrueの場合、またはデバイスがタイトル／サブタイトルとアトリビューションの両方を表示する場合に表示されます。	サポートされません	1.2.0
headerBackButton	ブール値	false	trueの場合、戻るボタンをヘッダーに表示します。ユーザーがこのボタンをクリックしたときに実行するコマンドを指定するには、headerBackButtonCommandプロパティを設定します。	サポートされません	1.2.0
headerBackButtonAccessibilityLabel	文字列	Back	スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。	サポートされません	1.2.0
headerBackButtonCommand	コマンド	{"type":"SendEvent","arguments":["goBack"]}	ユーザーが戻るボタンを選択したときに実行するコマンドです。	サポートされません	1.2.0
headerBackgroundColor	文字列	transparent	ヘッダーの背景色として使用するオプションの色の値です。	サポートされません	1.2.0
headerDivider	ブール値	false	trueの場合、ヘッダーの下に区切り線を表示してコンテンツと区別できるようにします。	サポートされません	1.2.0
headerSubtitle	文字列	—	ヘッダーに表示する第2テキストです。	サポートされません	1.2.0
headerTitle	文字列	—	ヘッダーに表示する第1テキストです。	サポートされません	1.2.0
hideOrdinal	ブール値	false	trueの場合、各リスト項目の横に番号を表示しません。	サポートされません	1.2.0
imageAlignment	文字列	center	listItems内の項目に適用されるimageAlignmentオプションのデフォルトを設定します。AlexaImageListItemのimageAlignmentプロパティを参照してください。	サポートされません	1.2.0
imageAspectRatio	文字列	square	リスト内のすべての項目の画像バウンディングボックスに使用するアスペクト比です。オプションは、square、round、standard_landscape、standard_portrait、poster_landscape、poster_portrait、widescreenです。このプロパティは、AlexaImageレスポンシブ対応コンポーネントのimageAspectRatioプロパティと同じように機能します。ただし、バウンディングボックスの高さと幅はアスペクト比に基づいて事前に定義され、変更することはできません。すべてのリスト項目は、常に同じアスペクト比を使用します。	サポートされません	1.2.0
imageBlurredBackground	ブール値	false	listItems内の項目に適用されるimageBlurredBackgroundオプションのデフォルトを設定します。AlexaImageListItemのimageBlurredBackgroundプロパティを参照してください。	サポートされません	1.2.0
imageHideScrim	ブール値	false	listItems内の項目に適用されるimageHideScrimオプションのデフォルトを設定します。AlexaImageListItemのimageHideScrimプロパティを参照してください。	サポートされません	1.2.0
imageMetadataPrimacy	ブール値	true	trueの場合、小型デバイスでsecondaryTextとtertiaryTextを優先します。このプロパティをfalseに設定すると、secondaryTextとtertiaryTextが非表示になります。このプロパティは、大型デバイスでは無視されます。	サポートされません	1.2.0
imageRoundedCorner	ブール値	true	listItems内の項目に適用されるimageRoundedCornerオプションのデフォルトを設定します。AlexaImageListItemのimageRoundedCornerプロパティを参照してください。	サポートされません	1.2.0
imageScale	文字列	best-fit	listItems内の項目に適用されるimageScaleオプションのデフォルトを設定します。AlexaImageListItemのimageScaleプロパティを参照してください。	サポートされません	1.2.0
imageShadow	ブール値	true	listItems内の項目に適用されるimageShadowオプションのデフォルトを設定します。trueの場合、各リスト項目の画像の背後にドロップシャドウを表示します。	サポートされません	1.3.0
imageShowProgressBar	ブール値	true	trueの場合、画像のオーバーレイに進行状況バーを表示します。個々のリスト項目で進捗状況バーの割合を設定するには、imageProgressBarPercentageプロパティを使用します。	サポートされません	1.2.0
layoutDirection	文字列	${environment.layoutDirection}	コンテンツのレイアウト方向を指定します。このプロパティは、LTR（左から右）またはRTL（右から左）に設定します。このプロパティには、コンポーネントの親コンテナーのlayoutDirectionは継承されません。このため、必要に応じて明示的にこのプロパティを設定してください。 レスポンシブ対応コンポーネントでの右から左に記述する言語のサポートの詳細については、右から左に記述する言語のサポートを参照してください。	サポートされません	1.4.0
listEntities	任意	—	GridSequenceにバインドするエンティティデータの配列です。	サポートされません	1.5.0
listId	文字列	—	リストとして使用されるSequenceコンポーネントに割り当てるIDです。ビルトインインテントを使用して音声でスクロールできるようにするには、listIdに値を設定します。SpeakListコマンドを使用する場合など、リストをコマンドのターゲットとして指定する場合も、このパラメーターにIDを設定します。listIdは、コンポーネント全体のidとは異なる値にする必要があります。listIdとidを同じ値に設定すると、リストをコマンドのターゲットにすることはできません。	サポートされません	1.2.0
listItemHeight	ディメンション	表示するデータのサイズに基づいて計算されます。	リスト項目の高さです。	サポートされません	1.2.0
listItemHorizontalCount	数値	0	1行に表示するリスト項目の数です。このプロパティを大きい値に設定すると、画像が切り詰められることがあります。imageAspectRatioとViewportサイズで最適化されたデフォルト値を使用するには、未設定のままにします。水平リストの密度を参照してください。	サポートされません	1.2.0
listItems	AlexaImageListItemの配列	—	リストに表示する項目の配列です。各項目は、AlexaImageListItemで定義されているものと同じプロパティ、またはカスタムのリスト項目に定義されているプロパティのセットを持つオブジェクトです。リスト項目を指定するを参照してください。	サポートされません	1.2.0
primaryAction	コマンド	—	listItems内の項目に適用されるprimaryActionオプションのデフォルトを設定します。このプロパティは、ユーザーがリストから項目を選択したときにトリガーされるコマンドに設定します。AlexaImageListItemのprimaryActionプロパティを参照してください。	サポートされません	1.2.0
speechItems	任意	—	読み上げ項目の配列です。AlexaGridListテンプレートは、この配列の各項目を、対応するリスト項目のspeechプロパティに割り当てます。このプロパティは、SpeakListコマンドを使用してリスト項目を読み上げる場合に使用します。	サポートされません	1.2.0
theme	文字列	dark	色のテーマをダークまたはライトに設定します。テーマを選択することでテンプレートの色を制御します。	サポートされません	1.2.0
type	文字列	—	常にAlexaGridListに設定されます。	サポートされません	1.2.0
videoAudioTrack	文字列	foreground	ビデオを再生する際に流すオーディオトラックです。指定できる値は、foreground、background、noneのいずれかです。	サポートされません	1.2.0
videoAutoPlay	ブール値	false	trueの場合、ドキュメントがデバイスに表示されるとビデオが自動的に再生されます。backgroundVideoSourceに値が指定された場合に適用します。	サポートされません	1.2.0

水平リストの密度（listItemHorizontalCount）

AlexaGridListは水平方向にスクロールしません。テンプレートは、固定数の項目を複数の行に表示します。1行に表示するリスト項目の数は、listItemHorizontalCountプロパティを使用して設定できます。AlexaGridListはデフォルトで、listItemHorizontalCountをimageAspectRatioとViewportサイズに基づいた数値に設定します。このデフォルト値では、すべてのリスト項目が切り詰められずに表示されます。

次の表は、標準Viewportプロファイルと画像のアスペクト比ごとのデフォルト値をまとめたものです。

画像のアスペクト比	デバイス、円形	デバイス、横長、小	デバイス、横長、中	デバイス、横長	テレビ、全画面
正方形	1	3	3	3	4
円形	1	3	3	3	4
標準、横長	1	3	3	3	4
標準、縦長	2	4	4	4	5
ポスター、横長	1	3	3	3	4
ポスター、縦長	2	4	4	4	5
ワイド画面	1	2	2	3	4

これらのレスポンシブ対応のデフォルトを使用するには、listItemHorizontalCountを未設定のままにします。listItemHorizontalCountを変更すると、AlexaGridListは、指定された項目数が1行に収まるように必要に応じてリスト項目を切り詰めます。

リスト項目を指定する

AlexaGridListテンプレートは、listItemsプロパティに項目の配列が設定されることを想定しています。リスト項目を構成するには、次のいずれかの方法を使用します。

• AlexaImageListItemレスポンシブ対応コンポーネントで定義されているものと同じプロパティを持つオブジェクトの配列を提供する。
• リスト項目のカスタムレイアウトを定義し、カスタム項目に対応するオブジェクトの配列を渡す。

リスト項目にAlexaImageListItemを使用する

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

この配列を、${gridListData.listItemsToShow}という式によってlistItemsプロパティにバインドします。

リスト項目にカスタムレイアウトを使用する

カスタムレイアウトを使用して、AlexaGridListに表示されるリスト項目を定義できます。この方法は、AlexaImageListItemの形式がニーズに合わない場合に使用できます。

カスタムレイアウトの作成方法の詳細については、APLレイアウトを参照してください。

リスト項目にカスタムレイアウトを使用するには

1. 表示するリスト項目の配列を作成します。配列の各項目は、一連のプロパティを持つオブジェクトです。次の例は、listItemTextとcolorという2つのプロパティを持つリスト項目オブジェクトを示しています。

    {
      "listItemText": "1番目のリスト項目です。",
      "color": "@colorGreen800"
    }
   

2. APLドキュメントのlayoutsセクションに、リスト項目を1つ表示するカスタムレイアウトを作成します。個々の項目のデータにアクセスするには、dataプロパティを使用します。

   たとえば、配列内の各リスト項目にlistItemTextというプロパティがあり、表示するリスト項目のテキストが含まれている場合、レイアウト内でそのプロパティを参照するには、data.listItemTextを使用します。AlexaGridListは、提供されたlistItemsをリストのdataプロパティに渡します。dataプロパティがどのように機能するかの詳細については、データ配列のインフレートを参照してください。

   次の例は、data配列の項目によって提供される背景色とテキストを使用してボックスを描画するカスタムレイアウトです。

    {
      "type": "Frame",
      "backgroundColor": "${data.color}",
      "padding": "@spacingSmall",
      "items": [
        {
          "type": "Text",
          "width": "100%",
          "height": "100%",
          "text": "${data.listItemText}",
          "textAlign": "center",
          "textAlignVertical": "center"
        }
      ]
    }
   

3. AlexaGridListで、customLayoutNameプロパティにカスタムレイアウトの名前を設定し、リスト項目の配列をlistItemsプロパティにバインドします。

        {
      "type": "AlexaGridList",
      "listItems": "${gridListData.listItemsToShow}",
      "customLayoutName": "MyListItem"
    }
   

次の例は、リスト項目にカスタムレイアウトを使用するAlexaGridListを示しています。このドキュメントでは、MyListItemというカスタムレイアウトを定義して、背景色を指定のcolorに設定したFrame内にlistItemTextを表示します。listItemsに渡される配列の構造は、この例のデータソースに示されています。

---

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

AlexaGridListテンプレートには、AlexaImageListItemのプロパティに対応するプロパティが含まれています。これらは、リスト項目のプロパティのデフォルト値を設定するために使用されます。リスト項目にカスタムレイアウトを使用すると、AlexaGridListはこれらのデフォルト値を無視します。

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

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

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

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

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

デフォルトとして使用するプロパティの一覧を次の表に示します。

プロパティ	項目の上書きが可能
defaultImageSource	×
imageAlignment	◯
imageAspectRatio	×
imageBlurredBackground	◯
imageHideScrim	◯
ImageMetadataPrimacy	×
imageRoundedCorner	◯
imageScale	◯
imageShadow	◯
primaryAction	◯

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

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

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

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

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

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

AlexaGridListの例

以下は、AlexaGridListの例を示しています。

---

関連トピック

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

---

---

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