Image List

Image List

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

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

AlexaImageListを使用するには、alexa-layoutsパッケージを読み込みます。

alexa-layoutsパッケージの最新バージョンは1.4.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です。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

文字列

なし

スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。

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

hideOrdinal

ブール値

false

trueの場合、各リスト項目の横に番号を表示しません。

1.1.0

hintText

文字列

なし

フッターに表示するヒントテキストです。正しいウェイクワードをヒントに追加するには、textToHintを使用します。imageMetadataPrimacyが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

ディメンション

none

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

文字列

""

テンプレートに表示されるテキストの言語です。この言語によって、テキストに使用されるデフォルトのフォントが決まります。たとえば、ar-SAを設定すると、コンポーネントはデバイスで利用できる場合にアラビア語のフォントを使用します。BCP-47文字列に設定します。

レスポンシブ対応コンポーネントの言語固有フォントについて詳しくは、Language-specific fonts in the components and templatesを参照してください。

1.4.0

layoutDirection

文字列

LTR

コンテンツのレイアウト方向を指定します。このプロパティをLTR（左から右）、RTL（右から左）のいずれかに設定します。このプロパティは、コンポーネントの親コンテナからlayoutDirectionを継承しません。このため、必要に応じて明示的にこのプロパティを設定してください。

レスポンシブ対応コンポーネントでの右から左に記述する言語のサポートについて詳しくは、Support for Right-to-left Languagesを参照してください。

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": [
      {
        "primaryText": "1番目のリスト項目です。",
        "secondaryText": "第2テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gruyere.png",
        "imageProgressBarPercentage": 90,
        "imageShowProgressBar": false,
        "ratingSlotMode": "multiple",
        "ratingNumber": 2.87,
        "ratingText": "（206件の評価）"
      },
      {
        "primaryText": "2番目のリスト項目です。",
        "secondaryText": "第2テキストです。",
        "tertiaryText": "第3テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/md_gorgonzola.png",
        "providerText": "プロバイダーテキストです。",
        "imageProgressBarPercentage": 50,
        "ratingSlotMode": "multiple",
        "ratingNumber": 4.5,
        "ratingText": "（500件の評価）"
      },
      {
        "primaryText": "画像なし、デフォルトを使用します。",
        "secondaryText": "第2テキストです。",
        "ratingSlotMode": "multiple",
        "ratingNumber": 2,
        "ratingText": "（50件の評価）"
      },
      {
        "primaryText": "4番目のリスト項目です。",
        "secondaryText": "進捗バーは表示しません。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/tl_brie.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 5,
        "ratingText": "（452件の評価）"
      },
      {
        "primaryText": "5番目のリスト項目です。",
        "secondaryText": "背景をぼかします。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 0,
        "ratingText": "（206件の評価）"
      },
      {
        "primaryText": "6番目のリスト項目です（折り返しのある長いテキストです）。",
        "secondaryText": "切り詰めのある長い第2テキストです。",
        "imageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/sm_blue.png",
        "ratingSlotMode": "multiple",
        "ratingNumber": 0,
        "ratingText": "（206件の評価）"
      }
    ]
  }
}

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

{
  "type": "AlexaImageList",
  "listItems": "${imageListData.listItemsToShow}",
  "defaultImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT7_Background.png",
  "imageBlurredBackground": true,
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}

リスト項目の指定可能なパラメーターは、AlexaImageListItemのバージョンによって異なります。たとえば、レーティングを表示するプロパティには1.2.0以上のバージョンのalexa-layoutsパッケージが必要です。すべてのプロパティについては、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配列の一部として渡します。

{
  "primaryAction": {
    "type": "SendEvent",
    "arguments": [
      "ListItemSelected",
      "${ordinal}"
    ]
  }
}

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

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

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

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

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

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

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

    以下は、listItemsToShowという配列を含むオブジェクト型データソースの例です。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のいずれかを指定します。

    以下の例では、textToSpeechトランスフォーマーを設定してlistItemsToShow配列の各項目のprimaryTextフィールドを処理しています。

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

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

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

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

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

リストで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およびdynamicIndexListデータソース

AlexaImageListテンプレートはSequenceを使用します。つまり、dynamicIndexListデータソースを使用できます。dynamicIndexListデータソースを使用すると、次のことを実行できます。

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

AlexaImageListとdynamicIndexListデータソースを組み合わせて使用する方法

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

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

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

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

AlexaImageListの例

この例では、リスト項目を選択すると、"ListItemSelected"とリスト項目の番号を持つUserEventがスキルに送信されます。

単純なAlexaImageList
単純なAlexaImageList