Lists

Note: Sign in to the developer console to build or publish your skill.

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以外のパラメーターはすべてオプションです。

名前	型	デフォルト	説明	ウィジェットのサポート	追加されたバージョン
`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
`defaultImageSource`	文字列	—	`imageSource`が定義されていないリスト項目に使用するデフォルト画像のURLです。これは、画像コンテナが空にならないようにするために使用します。`imageSource`がないすべてのリスト項目に対して、同じ`defaultImageSource`が使用されます。	サポートされません	1.1.0
`emptyPrimaryText`	文字列	—	リストに項目がない場合に、最大2行で表示する第1テキストです。テキストは2行に収まるように切り詰められます。	サポートされません	1.1.0
`emptySecondaryText`	文字列	—	リストに項目がない場合に、1行で表示する第2テキストです。第1テキストの下に表示されます。テキストは1行に収まるように切り詰められます。	サポートされません	1.1.0
`entities`	配列	—	このテンプレートにバインドするentityデータの配列です。	サポートされません	1.2.0
`footerHintText`	文字列	—	フッターに表示するヒントテキストです。正しいウェイクワードをヒントに追加するには、`textToHint`を使用します。`imageMetadataPrimacy`が`false`でない限り、小型デバイスでは表示されません。	サポートされません	1.1.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`の場合、戻るボタンをヘッダーに表示します。ユーザーがこのボタンをクリックしたときに実行するコマンドを指定するには、`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
`headerSubtitle`	文字列	—	ヘッダーに表示する第2テキストです。	サポートされません	1.1.0
`headerTitle`	文字列	—	ヘッダーに表示する第1テキストです。	サポートされません	1.1.0
`hideDivider`	ブール値	`false`	`true`の場合、リストの各項目の下に表示される横方向の区切り線を非表示にします。`listImagePrimacy`が`false`の場合に使用されます。	サポートされません	1.1.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
`listImagePrimacy`	ブール値	`false`	`true`の場合、リストのレイアウトは、指定された画像ソースをメインのナビゲーション要素として表示するように調整され、通常は水平方向のナビゲーションになります。`false`の場合、第1テキストが表示され、通常は垂直方向のナビゲーションになります。デフォルトは`false`です。	サポートされません	1.1.0
`listItems`	listItemsの配列	—	表示するリスト項目の配列です。	サポートされません	1.1.0
`primaryAction`	コマンド	—	`listItems`内の項目に適用される`primaryAction`オプションのデフォルトを設定します。これは、ユーザーがリストから項目を選択したときにトリガーされるコマンドに設定します。`AlexaImageListItem`の`primaryAction`プロパティを参照してください。	サポートされません	1.1.0
`speechItems`	任意	—	読み上げ項目の配列です。`AlexaLists`テンプレートは、この配列の各項目を、対応するリスト項目の`speech`プロパティに割り当てます。このプロパティは、`SpeakList`コマンドを使用してリスト項目を読み上げる場合に使用します。	サポートされません	1.2.0
`theme`	文字列	`dark`	色のテーマをダークまたはライトに設定します。テーマを選択することでテンプレートの色を制御します。	サポートされません	1.1.0
`touchForward`	ブール値	`false`	`true`の場合、ユーザーが画面をタッチできるほど近くにいる（視聴距離が1m以内）と想定し、リスト項目のフォントサイズを小さくします。`false`の場合、ユーザーが画面をタッチできるほど近くにはいない（音声で操作する）と想定し、大きいフォントサイズを使用します。`listImagePrimacy`が`false`の場合に適用されます。	サポートされません	1.1.0
`type`	文字列	—	常に`AlexaLists`に設定されます。	サポートされません	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 日

Lists

互換性

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

AlexaListsのパラメーター

表示するリストのレイアウトを選択する（listImagePrimacy）

リスト項目を指定する

空のリストのデフォルトテキスト

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

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

AlexaListsの例

関連トピック