Lists
Alexa Listsテンプレート(AlexaLists)は、項目のリストを表示します。AlexaListsは全画面テンプレートで、必要に応じてヘッダー、フッター、背景を表示できます。テンプレートでテキストベースのリスト項目を表示するか、画像ベースの項目を表示するかを指定します。テキスト項目の場合、テンプレートはAlexaTextListを使用します。画像ベースの項目の場合、テンプレートはほとんどのViewportでAlexaImageListを使用し、小型の円形デバイスではAlexaPaginatedListを使用します。
互換性
AlexaListsは、alexa-viewport-profilesパッケージのすべての標準Viewportプロファイルで動作するように設計されています。次のプロファイルに対応しています。
- すべての円形デバイスプロファイル
- すべての横長デバイスプロファイル
- すべての縦長デバイスプロファイル
- すべてのモバイルプロファイル
- すべてのテレビプロファイル
サポートされていないViewportでAlexaListsを使用すると、予期しない結果になることがあります。Viewportプロファイルの詳細については、Viewportプロファイルを参照してください。
alexa-layoutsパッケージをインポートする
AlexaListsを使用するには、alexa-layoutsパッケージをインポートします。
alexa-layoutsパッケージの最新バージョンは1.7.0です。AlexaListsはバージョン1.1.0で導入されました。
AlexaListsのパラメーター
type以外のパラメーターはすべてオプションです。
| 名前 | 型 | デフォルト | 説明 | ウィジェットのサポート | 追加されたバージョン | 
|---|---|---|---|---|---|
| 
 | 文字列 | 
 | 背景画像または背景ビデオの配置を指定します。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | — | 背景色として使用する色です。 | サポートされません | 1.1.0 | |
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | 背景画像ソースのURLです。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | 背景画像または背景ビデオのサイズを調整する方法を指定します。 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | ビデオを再生する際に流すオーディオトラックです。指定できる値は、 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | — | 背景ビデオのソースです。Videoコンポーネントの | サポートされません | 1.1.0 | |
| 
 | 文字列 | — | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | リストに項目がない場合に、最大2行で表示する第1テキストです。テキストは2行に収まるように切り詰められます。 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | リストに項目がない場合に、1行で表示する第2テキストです。第1テキストの下に表示されます。テキストは1行に収まるように切り詰められます。 | サポートされません | 1.1.0 | 
| 
 | 配列 | — | このテンプレートにバインドするentityデータの配列です。 | サポートされません | 1.2.0 | 
| 
 | 文字列 | — | フッターに表示するヒントテキストです。正しいウェイクワードをヒントに追加するには、 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | アトリビューションの画像ソースのURLです。 | サポートされません | 1.1.0 | 
| 
 | 数値 | 
 | ヘッダーのアトリビューションテキストとアトリビューション画像にopacityを設定します。0と1の間の数値を設定します。 | サポートされません | 1.3.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | ヘッダーで表示するアトリビューションのテキストです。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。 | サポートされません | 1.1.0 | 
| 
 | 
 | ユーザーが戻るボタンを選択したときに実行するコマンドです。 | サポートされません | 1.1.0 | |
| 
 | 文字列 | 
 | ヘッダーの背景色として使用するオプションの色の値です。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | ヘッダーに表示する第2テキストです。 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | ヘッダーに表示する第1テキストです。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | リスト内のすべての項目の画像バウンディングボックスに使用するアスペクト比です。オプションは、square、round、standard_landscape、standard_portrait、poster_landscape、poster_portrait、widescreenです。このプロパティは、 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | — | 
 | サポートされません | 1.4.0 | |
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.3.0 | 
| 
 | 文字列 | 
 | テンプレートに表示されるテキストの言語です。この言語によって、テキストに使用されるデフォルトのフォントが決まります。たとえば、 | サポートされません | 1.4.0 | 
| 
 | 文字列 | 
 | コンテンツのレイアウト方向を指定します。このプロパティは、 | サポートされません | 1.4.0 | 
| 
 | 文字列 | — | リストとして使用される | サポートされません | 1.2.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | listItemsの配列 | — | 表示するリスト項目の配列です。 | サポートされません | 1.1.0 | 
| 
 | — | 
 | サポートされません | 1.1.0 | |
| 
 | 任意 | — | 読み上げ項目の配列です。 | サポートされません | 1.2.0 | 
| 
 | 文字列 | 
 | 色のテーマをダークまたはライトに設定します。テーマを選択することでテンプレートの色を制御します。 | サポートされません | 1.1.0 | 
| 
 | ブール値 | 
 | 
 | サポートされません | 1.1.0 | 
| 
 | 文字列 | — | 常に | サポートされません | 1.1.0 | 
表示するリストのレイアウトを選択する(listImagePrimacy)
リストのレイアウトは、listImagePrimacyパラメーターによって決まります。
listImagePrimacyがtrueの場合、テンプレートはAlexaImageListまたはAlexaPaginatedListを表示します。これらのレイアウトは、各項目の画像とテキストを表示します。小型の円形デバイスではAlexaPaginatedListが使用され、各ページにリスト項目が1つずつ表示されます。
listImagePrimacyがfalseの場合、テンプレートはAlexaTextListを表示します。このレイアウトは、テキスト項目のスクロールリストを表示します。
リスト項目を指定する
AlexaListsテンプレートは、listItemsプロパティに項目の配列が設定されることを想定しています。各項目は以下のいずれかです。
- AlexaImageListItemレスポンシブ対応コンポーネントで定義されているものと同じプロパティを持つオブジェクト
- AlexaTextListItemレスポンシブ対応コンポーネントで定義されているものと同じプロパティを持つオブジェクト
このリストは、listImagePrimacyがtrueの場合は画像のプロパティを使用し、listImagePrimacyがfalseの場合は画像のプロパティを無視します。
次の例は、listDataというデータソース内の項目の配列を示しています。
{
  "listData": {
    "listItemsToShow": [
      {
        "primaryText": "1番目のリスト項目です。",
        "secondaryText": "第2テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
        "imageProgressBarPercentage": 90,
        "imageShowProgressBar": false
      },
      {
        "primaryText": "2番目のリスト項目です。",
        "secondaryText": "第2テキストです。",
        "tertiaryText": "第3テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
        "providerText": "プロバイダーテキストです。",
        "imageProgressBarPercentage": 50
      },
      {
        "primaryText": "画像なし、デフォルトを使用します。",
        "secondaryText": "第2テキストです。"
      },
      {
        "primaryText": "4番目のリスト項目です。",
        "secondaryText": "進捗バーは表示しません。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png"
      },
      {
        "primaryText": "5番目のリスト項目です。",
        "secondaryText": "背景をぼかします。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png"
      },
      {
        "primaryText": "6番目のリスト項目です(折り返しのある長いテキストです)。",
        "secondaryText": "切り詰めのある長い第2テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png"
      }
    ]
  }
}
この配列を、${listData.listItemsToShow}という式によってlistItemsプロパティにバインドします。次の例では、AlexaImageListまたはAlexaPaginatedListを表示し、指定された画像を表示します。
{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "listImagePrimacy": true,
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true
}
listImagePrimacyをfalseに変更すると、同じデータを持つAlexaTextListが表示されます。このバージョンでは、AlexaTextListに適用されないプロパティは無視されます。
{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "listImagePrimacy": false,
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true
}
空のリストのデフォルトテキスト
リスト項目がない場合に表示するテキストを定義するには、emptyPrimaryTextパラメーターとemptySecondaryTextパラメーターを使用します。これによって画面の中央に短いテキストのヘッドラインが表示されます。
次の例は、emptyPrimaryTextとemptySecondaryTextのコンテンツのあるAlexaListsを示しています。
{
  "type": "AlexaLists",
  "listItems": "${listData.listItemsToShow}",
  "emptyPrimaryText": "${listData.emptyPrimaryText}",
  "emptySecondaryText": "${listData.emptySecondaryText}",
  "imageBlurredBackground": true
}
以下は、画面に「リストが空」であることを示すメッセージを生成するデータソースの例です。
{
  "listData": {
    "emptyPrimaryText": "リスト項目がありません。",
    "emptySecondaryText": "開始するには、リストに追加する項目を教えてください。",
    "listItemsToShow": []
  }
}
リスト項目のデフォルトを設定する
AlexaListsテンプレートには、AlexaImageListItemのプロパティに対応するプロパティが含まれています。対応するプロパティを使用して、これらのプロパティのデフォルト値を設定します。デフォルト値はlistImagePrimacyがtrueの場合に適用されます。
デフォルトには次の2種類があります。
- 
    個々の項目で設定またはオーバーライドできるデフォルト - AlexaListsは、個々の項目に値が指定されている場合はその値を使用し、それ以外の場合はAlexaListsに指定された値を使用します。たとえば、リスト全体に対して imageScaleをbest-fitに設定し、リストの1つの項目でbest-fillにオーバーライドできます。
- 
    常にリスト内のすべての項目に適用されるデフォルト - AlexaListsは、常にこれらのプロパティに対してAlexaListsで指定された値を使用します。個々の項目に設定された対応するプロパティの値は無視されます。たとえば、 imageAspectRatioはリスト全体に対して設定する必要があります。一部の項目を正方形として表示し、一部の項目を円として表示するリストは作成できません。リスト項目のimageAspectRatioの値は無視されます。
デフォルトとして使用するプロパティの一覧を次の表に示します。
| プロパティ | 項目の上書きが可能 | 
|---|---|
| defaultImageSource | × | 
| imageAlignment | ◯ | 
| imageAspectRatio | × | 
| imageBlurredBackground | ◯ | 
| imageHeight | × | 
| imageHideScrim | ◯ | 
| ImageMetadataPrimacy | × | 
| imageRoundedCorner | ◯ | 
| imageScale | ◯ | 
| imageShadow | ◯ | 
| primaryAction | ◯ | 
各プロパティの詳細については、AlexaImageListItemを参照してください。
各リスト項目のアクションを指定する
AlexaListsは対話型です。ユーザーはリストの項目を選択できます。primaryActionプロパティに、ユーザーが項目を選択したときに実行するコマンドを設定します。
AlexaListsコンポーネントでprimaryActionを設定すると、AlexaListsはリストの各項目にこのコマンドを渡します。
個々のリスト項目でコマンドをオーバーライドするには、リスト項目自体にprimaryActionプロパティを設定します。
次の例は、SendEventコマンドを使用してスキルにUserEventリクエストを送信する方法を示しています。SendEvent.arguments配列の一部として、選択された項目を表す番号を渡します。
{
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}
AlexaListsの例
以下は、AlexaListsテンプレートの例を示しています。大型のデバイスでは、リストはAlexaImageListとして表示されます。ViewportをHub Round Smallに切り替えると、同じリストがAlexaPaginatedListとして表示されます。
関連トピック
最終更新日: 2025 年 09 月 30 日