Image List
Alexa Image Listテンプレート(AlexaImageList
)は、画像とテキストのスクロールリストを表示します。AlexaImageList
は全画面に表示されるテンプレートであり、オプションでヘッダー、フッター、背景を表示します。リストに表示する画像ベースの項目を指定して、リストの外観(区切り線を挿入する、項目に番号を付けるなど)を設定できます。ユーザーがリストから項目を選択したときに実行するコマンドも指定できます。
alexa-layoutsパッケージを読み込む
AlexaImageList
を使用するには、alexa-layoutsパッケージを読み込みます。
alexa-layouts
パッケージの最新バージョンは1.4.0
です。AlexaImageList
はバージョン1.1.0
で導入されました。
AlexaImageListのパラメーター
type
以外のパラメーターはすべてオプションです。
名前 | 型 | デフォルト | 説明 | 追加または更新されたバージョン |
---|---|---|---|---|
|
文字列 |
|
背景画像または背景ビデオの配置を指定します。 |
1.1.0 |
|
ブール値 |
|
trueの場合、指定された背景画像にぼかしを入れて表示します。 |
1.1.0 |
|
なし |
背景色として使用する色です。 |
1.1.0 |
|
|
ブール値 |
|
trueの場合、背景にレイヤーを適用して、画像やビデオ上のテキストを読みやすくします。 |
1.1.0 |
|
文字列 |
なし |
背景画像ソースのURLです。 |
1.1.0 |
|
ブール値 |
|
trueの場合、背景にグラデーションを適用します。 |
1.1.0 |
|
文字列 |
|
背景画像または背景ビデオのサイズを調整する方法を指定します。 |
1.1.0 |
|
なし |
背景ビデオのソースです。Videoコンポーネントの |
1.1.0 |
|
|
文字列 |
|
1.1.0 |
|
|
配列 |
[] |
このテンプレートにバインドするentityデータの配列です。 |
1.2.0 |
|
文字列 |
なし |
アトリビューションの画像ソースのURLです。 |
1.1.0 |
|
数値 |
0.8 |
ヘッダーのアトリビューションテキストとアトリビューション画像にopacityを設定します。0と1の間の数値を設定します。 |
1.3.0 |
|
ブール値 |
true |
trueの場合、画面サイズの制約のため1つの要素だけを表示するデバイスに |
1.1.0 |
|
文字列 |
なし |
ヘッダーで表示するアトリビューションのテキストです。 |
1.1.0 |
|
ブール値 |
|
trueの場合、戻るボタンをヘッダーに表示します。ユーザーがこのボタンをクリックしたときに実行するコマンドを指定するには、 |
1.1.0 |
|
文字列 |
なし |
スクリーンリーダーを使用するユーザーに、戻るボタンについて説明するアクセシビリティラベルです。 |
1.1.0 |
|
|
ユーザーが戻るボタンを選択したときに実行するコマンドです。 |
1.1.0 |
|
|
文字列 |
|
ヘッダーの背景色として使用するオプションの色の値です。 |
1.1.0 |
|
ブール値 |
|
trueの場合、ヘッダーの下に区切り線を表示してコンテンツと区別できるようにします。 |
1.1.0 |
|
文字列 |
なし |
ヘッダーで表示する第1テキストです。 |
1.1.0 |
|
ブール値 |
|
|
1.1.0 |
|
文字列 |
なし |
フッターに表示するヒントテキストです。正しいウェイクワードをヒントに追加するには、 |
1.1.0 |
|
文字列 |
center |
|
1.1.0 |
|
文字列 |
square |
リスト内のすべての項目の画像バウンディングボックスに使用するアスペクト比です。オプションは、square、round、standard_landscape、standard_portrait、poster_landscape、poster_portrait、widescreenです。このプロパティは、 |
1.1.0 |
|
ブール値 |
false |
|
1.1.0 |
|
none |
|
1.4.0 |
|
|
ブール値 |
false |
|
1.1.0 |
|
ブール値 |
true |
trueの場合、小型デバイスで |
1.1.0 |
|
ブール値 |
true |
|
1.1.0 |
|
文字列 |
best-fit |
|
1.1.0 |
|
ブール値 |
true |
|
1.3.0 |
|
文字列 |
"" |
テンプレートに表示されるテキストの言語です。この言語によって、テキストに使用されるデフォルトのフォントが決まります。たとえば、 |
1.4.0 |
|
文字列 |
|
コンテンツのレイアウト方向を指定します。このプロパティを |
1.4.0 |
|
文字列 |
リストに使用する |
1.2.0 |
|
|
リストに表示する項目の配列です。各項目は、 |
1.1.0 |
||
|
なし |
|
1.1.0 |
|
|
任意 |
[] |
音声項目の配列です。 |
1.2.0 |
|
文字列 |
dark |
色のテーマをダークまたはライトに設定します。テーマを選択することでテンプレートの色を制御します。 |
1.1.0 |
|
文字列 |
なし |
常に |
1.1.0 |
|
文字列 |
|
ビデオを再生する際に流すオーディオトラックです。 |
1.1.0 |
|
ブール値 |
|
trueの場合、ドキュメントがデバイスに表示されるとビデオが自動的に再生されます。 |
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
コマンドを呼び出します。
読み上げる項目リストのデータソースを設定する
- ドキュメントで使用するオブジェクト型のデータソースを作成します。
-
データソースで、読み上げる項目の配列をデータソースの
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" } ] } } }
-
以下のように、
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
ハンドラーからコマンドを実行して、デバイスがドキュメントを表示した後に項目を読み上げさせることができます。
-
AlexaImageList
のlistId
パラメーターにドキュメント固有のIDを割り当てます。SpeakList
を実行するにはこのIDを指定する必要があります。{ "type": "AlexaImageList", "listId": "myImageListWithItemsToSpeak", "listItems": "${imageListData.properties.listItemsToShow}", "speechItems": "${imageListData.properties.listItemsToShow}" }
-
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データソースを組み合わせて使用する方法
- dynamicIndexListデータソースに記載されている
dynamicIndexList
の構造に従います。この構造で定義されていない他のプロパティは含めないでください。 - リスト項目オブジェクトをデータソースの
items
配列に配置します。 - データソースを
AlexaImageList
のlistItems
プロパティにバインドします。このバインドは、カスタムレイアウトのSequence
のdata
プロパティにデータソースをバインドすることと同じです。
以下は、dynamicIndexList
データソースを使用するAlexaImageList
を含むドキュメントの例です。
dynamicIndexList
データソースの定義の詳細については、dynamicIndexListデータソースを参照してください。
データソースの管理に使用するディレクティブとリクエストの詳細については、Alexa.Presentation.APLインターフェースのリファレンスを参照してください。
AlexaImageListの例
この例では、リスト項目を選択すると、"ListItemSelected"とリスト項目の番号を持つUserEvent
がスキルに送信されます。
