コンテンツを背景、境界線、ヘッダーと結合する
大半のAlexa Presentation Languageのコンポーネントには境界線や背景色のプロパティがないため、背景と境界線を表示するには、複数のコンポーネントを結合する必要があります。
viewport全体に背景を表示する
背景色、画像、またはビデオを表示するには、Alexa Backgroundレスポンシブ対応コンポーネントを使用します。コンポーネントはviewport全体に表示され、各viewportのサイズに合わせて自動的に調整されます。AlexaBackgroundコンポーネントをContainer内のほかのコンポーネントと結合すると、同じ親Container内のコンポーネントが背景の上に表示されるようになります。
コンテンツの後ろに表示される背景を作成する方法は下記のとおりです。
- ドキュメント内の
import配列に、現在のバージョンのalexa-layoutsを追加します。{ "import": [ { "name": "alexa-layouts", "version": "1.1.0" } ] } -
AlexaBackgroundをContainer内のほかのコンポーネントと結合します。背景の上に表示するコンポーネントの前にAlexaBackgroundを配置します。{ "type": "Container", "items": [ { "type": "AlexaBackground", }, { "type": "Text", "text": "背景の上に表示されるテキスト。", } ] }ほかのコンポーネントの後に
AlexaBackgroundを配置すると、背景がほかのコンポーネントを覆い隠します。 - 背景を表示するには、少なくとも
backgroundVideoSource、backgroundImageSource、またはbackgroundColorを設定してください。{ "type": "AlexaBackground", "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png" }これらのプロパティの1つだけが使用されます。たとえば、
backgroundImageSourceとbackgroundColorの両方を指定すると、Alexaは背景画像を表示します。Alexa Backgroundの背景ソースの優先順位を参照してください。これらの3つのソースプロパティのいずれも設定しない場合、Alexaはデフォルトの背景を表示します。
この例では、背景に画像を使用します。colorOverlayも設定して画像にレイヤーを適用し、テキストが読みやすくなるようにします。
AlexaBackgroundを使用して、Textコンポーネントの後ろに背景画像を表示AlexaBackgroundコンポーネントでは、絶対位置を使用してほかのコンポーネントがその上に表示されるようにします。つまり、子項目を配置するための親Containerのプロパティは、背景に影響しません。
たとえば、このContainerでは、justifyContentがendに設定されているため、Alexaは子コンポーネントを画面下部に配置します。paddingBottomプロパティは、最後のコンポーネントと画面下部の間にスペースを追加します。AlexaBackgroundも同じContainerの子ですが、これらのプロパティは背景の配置には影響せず、Textコンポーネントにのみ影響します。
{
"type": "Container",
"justifyContent": "end",
"paddingBottom": "@spacingLarge",
"items": [
{
"type": "AlexaBackground",
"backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png",
"colorOverlay": true
},
{
"type": "Text",
"text": "この例の<code>justifyContent</code>プロパティと<code>paddingBottom</code>プロパティは、ほかの子プロパティに影響しますが、AlexaBackgroundには影響しません。",
"style": "textStyleBody",
"paddingLeft": "@marginHorizontal",
"paddingRight": "@marginHorizontal",
"textAlign": "center"
}
]
}
justifyContentプロパティとpaddingBottomプロパティ画面上部にヘッダーを表示する
ヘッダーは画面上部に表示されるので、タイトルとサブタイトルの情報を表示したり、アイコンを使ってスキルをブランディングするのに役立ちます。
Alexaレイアウトパッケージで指定されたAlexa Header（AlexaHeader）レスポンシブ対応コンポーネントを使用して、ドキュメントにヘッダーを追加します。
ドキュメントにヘッダーを追加する方法
- ドキュメント内の
import配列に、現在のバージョンのalexa-layoutsを追加します。{ "import": [ { "name": "alexa-layouts", "version": "1.1.0" } ] } -
AlexaHeaderをContainer内のほかのコンポーネントと結合します。viewportの上部でほかのコンポーネントの前に表示されるように、AlexaHeaderを配置します（AlexaBackgroundも使用している場合を除く）。{ "type": "Container", "items": [ { "type": "AlexaHeader", "headerTitle": "これはメインヘッダーのタイトルです", "headerSubtitle": "これはヘッダーのサブタイトルです", "headerDivider": true, "headerAttributionImage": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png" }, { "type": "Text", "text": "ヘッダーの後に表示するテキスト。" } ] } - ヘッダーに表示するプロパティ（
headerTitle、headerSubtitleなど）を設定します。使用可能なプロパティについては、Alexa Headerを参照してください。
AlexaHeaderとほかのコンポーネントを合わせて配置する
Containerのプロパティを使用して、子コンポーネントの位置を指定します。画面上部のAlexaHeaderの配置を妨げるようなレイアウトは作成しないでください。レイアウトによっては、次のように追加のContainersをネストする必要があります。
Container
AlexaHeader
Container
ほかのコンポーネント...
AlexaHeaderを含むContainerのレイアウトを定義するときは、以下の点に留意してください。
- Alexa Background –
AlexaBackgroundとAlexaHeaderの両方を一緒に使用できます。この場合、まずContainerにAlexaBackgroundを配置し、その後でAlexaHeaderを配置します。 - レイアウト方向 –
Containerのdirectionプロパティをデフォルト設定（column）のままにします。この設定により、縦型レイアウトが作成され、子コンポーネントは前のコンポーネントの下に表示されます。この設定をrowに変更すると、子コンポーネントは前のコンポーネントの右側に表示されます。これは、画面上部にヘッダーを配置することを妨げます。横型のレイアウトを作成するときは、別のContainerをネストして、AlexaHeaderの下に配置してください。 -
絶対位置と相対位置 – 同じ
Container内の項目のどれかに絶対位置を使用する場合は、注意が必要です。コンポーネントのpositionをabsoluteに設定すると、そのコンポーネントは通常の階層から除外され、親に対して相対的に配置されます。これにより、コンテンツがヘッダーと重なる場合があります。デフォルトのposition（relative）では、後続のコンポーネントがヘッダーの後に自動的に配置されるため、扱いが簡単です。AlexaHeaderと同じContainer内のコンポーネントで絶対位置を使用する場合は、コンポーネントがヘッダーと重複しないように、topのオフセットを十分に大きく設定してください。または、bottomプロパティを使用して、viewportの下からコンポーネントをオフセットしてください。 -
主軸上の配置 –
Containerの方向がcolumnの場合、justifyContentプロパティによって、子コンポーネントの縦方向のレイアウトが制御されます。デフォルト値（start）を使用して、AlexaHeaderを画面上部に表示します。これを変更すると、AlexaHeaderの縦方向の配置も変更されます。たとえば、justifyContentをendに設定すると、Container内のすべてのコンポーネント（AlexaHeaderを含む）がviewportの下部に移動します。一部の項目に別の
justifyContent設定を使用する場合は、別のContainerをネストして、そこにjustifyContentを設定します。 - 交差軸上の配置 –
Containerの方向がcolumnの場合、alignItemsプロパティによって、子コンポーネントの横方向の配置が制御されます。これをデフォルト（auto）のままにしてください。変更すると、AlexaHeaderの横方向の配置も変更されます。必要に応じてほかの子コンポーネントの配置を変えるには、次のような方法があります。- ほかのコンポーネントを別の
Container内にネストして、そのContainerでalignItemsを設定します。 - 親
ContainerでalignItemsをデフォルトの設定にしたまま、AlexaHeader以外の子に対してalignSelfで上書きします。 - 必要に応じて親
ContainerのalignItemsを変更し、AlexaHeaderでalignSelfをstretchに設定します。
- ほかのコンポーネントを別の
- パディング –
Containerレベルでのpaddingプロパティは、AlexaHeaderを含むすべてのContainerの子コンポーネントの配置を変更します。たとえば、paddingTopを設定すると、ヘッダーが押し下げられ、paddingLeftを設定すると、インデントが適用されます。AlexaHeaderコンポーネントで定義されたパディングを使用するには、Containerのpaddingプロパティを設定しないままにします。必要に応じてほかの子コンポーネントに別のパディングを設定するには、次のような方法があります。- ほかのコンポーネントを別の
Container内にネストして、そこにpaddingプロパティを設定します。 - それぞれの子コンポーネントに
paddingプロパティを設定します。
子コンポーネントの左右のマージンを
AlexaHeaderの左右のパディングに一致させるには、これらのコンポーネントのpaddingLeftプロパティとpaddingRightプロパティを、Alexa Stylesパッケージで指定されているmarginHorizontalリソースに設定します。 - ほかのコンポーネントを別の
- データ配列のインフレート –
dataプロパティを持つComponentにデータ配列をバインドできます。この場合、Alexaは配列の各項目について、whenがtrueであるitemsの最初のコンポーネントを表示します。これにより、AlexaHeaderコンテンツが複数回表示されますが、ほかのコンポーネントは無視されます。この状況でAlexaHeaderを使用するには、itemsではなく、ContainerのfirstItemプロパティにAlexaHeaderを配置します。
firstItemプロパティを使用して、データ配列のインフレートでヘッダーを使用画面下部にフッターを表示する
画面下部のフッターでは、ヒントを表示して、ユーザーが使うほかのフレーズを提案できます。
Alexaレイアウトパッケージで指定されたAlexa Footer（AlexaFooter）レスポンシブ対応コンポーネントを使用して、ドキュメントにフッターを追加します。
ドキュメントにフッターを追加する方法
- ドキュメント内の
import配列に、現在のバージョンのalexa-layoutsを追加します。{ "import": [ { "name": "alexa-layouts", "version": "1.1.0" } ] } -
AlexaFooterをContainer内のほかのコンポーネントと結合します。AlexaFooterを最後に配置して、ほかのコンポーネントの後にviewportの下部に表示されるようにします。{ "type": "Container", "items": [ { "type": "Text", "text": "本文テキスト。" }, { "type": "AlexaFooter" } ] } -
hintTextプロパティに表示するテキストを設定します。データソースとデータトランスフォーマーを使用して、デバイスのウェイクワードを使ってヒントを自動的にフォーマットします。
- ほかの
Containerプロパティを設定して、フッターがviewportの下部に表示されるようにします。後述のフッターの位置を設定するを参照してください。
この例では、ヘッダーとフッターの両方を含むTextコンポーネントを表示します。
フッターの位置を設定する
AlexaFooterがContainerのitems配列の最後にある場合、ほかのすべてのコンポーネントの後に表示されます。ただし、ほかのコンポーネントのサイズによっては、意図したとおりにviewportの下部に表示されない場合があります。AlexaFooterを常にviewportの下部に表示するには、次のような方法があります。
-
AlexaFooterのpositionをabsoluteに設定して、bottomを0に設定します。これにより、ほかのコンポーネントの位置やサイズに関係なく、AlexaFooterはviewportの下部から0ピクセル分オフセットされます。AlexaFooterレスポンシブ対応コンポーネントにはボトムパディングが含まれているため、追加のパディングを含める必要はありません。前述の基本的なフッターの例では、このオプションを使用しています。本文のコンテンツとフッターの両方に十分な縦方向のスペースがない場合、フッターは本文のコンテンツと重なります。本文のコンテンツが長くなりすぎないようにしてください。
-
Containerのheightをviewport全体の高さに設定して、Container内のほかのコンポーネントでgrowを「1」に設定します。growを持つコンポーネントはviewport内の空白スペース全体に拡張されて表示されます。本文のコンテンツとフッターの両方に十分な縦方向のスペースがない場合、フッターは画面下部に表示されなくなります。本文のコンテンツが長くなりすぎないようにしてください。
この例では、viewport内の本文に2つのTextコンポーネントがあります。2番目のコンポーネントではgrowを「1」に設定して、Textのバウンディングボックスが残りのスペース全体に広がるようにしています。
growを使用して、viewportの下まで押し下げられたフッター長いコンテンツを表示する場合は、小型の円形のデバイスではフッターを非表示にします。次のようにwhenプロパティを使用してください："when": "${@viewportProfile != @hubRoundSmall}
ヒントにデバイスのウェイクワードを使用する
ユーザーは、デバイスで使用するウェイクワードを設定できます。ウェイクワードが常に「アレクサ」であるとは限らないため、フッターのテキストを「『アレクサ、何かほかのことをして...』と言ってみてください」のようにハードコーディングせず、data sourceとtextToHintトランスフォーマーを使用して、デバイス固有のウェイクワードをヒントに自動的に含めることができます。このトランスフォーマーには、テキストのフォーマットを適用して一貫性を保ちます。
textToHintトランスフォーマーを使用する
objectデータソースのpropertiesオブジェクト内のプロパティにヒントテキストを配置します。この例では、ヒントはpropertiesオブジェクト内のhintTextToTransformプロパティに格納されています。ここにはヒントの語句だけを含めるようにしてください。ウェイクワードや「言ってみてください」という語句は除外します。{ "footerExampleData": { "type": "object", "objectId": "footerExampleData", "description": "このデータソースには、フッターのヒント例が含まれています。", "properties": { "hintTextToTransform": "このスキルを使って何かほかのことをして" } } }- データソースの
transformers配列にtextToHintトランスフォーマーを追加して、そのトランスフォーマーのinputPathをヒントテキストを持つプロパティに設定します。変換された値のoutputNameプロパティを指定します。{ "transformers": [ { "inputPath": "hintTextToTransform", "transformer": "textToHint", "outputName": "transformedHintText" } ] }outputNameは省略できます。この場合、変換された値は、inputPathで指定したプロパティで使用できます。 - ドキュメントでは、データバインディングを使用して、
AlexaFooterのhintTextプロパティをトランスフォーマー出力に設定します。{ "type": "AlexaFooter", "hintText": "${payload.footerExampleData.properties.transformedHintText}" }
このfooterExampleデータソースでは、ヒントテキスト（「このスキルを使って何かほかのことをして」）はfooterExampleData.properties.hintTextToTransformに格納されています。テキストはfooterExampleData.properties内にあると想定されているため、inputPathはhintTextToTransformという名前のプロパティを参照するだけです。変換の結果は、transformedHintTextプロパティで使用できます。
この例は、ドキュメント内でトランスフォーマーの出力を使用する方法を示しています。AlexaFooterのhintTextプロパティは、データバインディングを使用してfooterExampleDataデータソースからtransformedHintText値を取得します。
デフォルトの「アレクサ」というウェイクワードを使用するデバイスには、次のヒントが表示されます。
「アレクサ、このスキルを使って何かほかのことをして」と言ってみてください。
ウェイクワードが「エコー」に設定されたデバイスには、次のヒントが表示されます。
「エコー、このスキルを使って何かほかのことをして」と言ってみてください。
textToHintの結果を確認してください。スクロールテキストをヘッダーおよびフッターと結合する
スクロールの必要があるコンテンツでは、ScrollViewまたはSequenceの前後にヘッダーとフッターを配置する際に、viewportのサイズを考慮する必要があります。
-
画面が小さい（特に小型の円形のデバイス）の場合は、スクロールエリア内に
AlexaHeaderを配置して、ヘッダーが邪魔にならないように画面外にスクロールするようにします。これにより、コンテンツが表示される画面スペースを最大化できます。たとえば、次のような構造を使用できます。Container AlexaBackground ScrollView Container AlexaHeader スクロールする必要があるコンテンツを持つコンポーネント -
中型および大型の画面の場合は、
AlexaHeaderをスクロールエリアの外に配置して、常に表示されるようにします。たとえば、次のような構造を使用できます。Container AlexaBackground AlexaHeader ScrollView スクロールする必要があるコンテンツを持つコンポーネント （または、表示するコンポーネントが複数ある場合はContainer）
viewportに表示するコンポーネントを指定する条件を設定するには、whenプロパティを使用します。
{
"mainTemplate": {
"items": [
{
"when": "${@viewportProfile == @hubRoundSmall}",
"type": "Container",
"items": []
},
{
"type": "Container",
"items": []
}
]
}
}
コンテンツの複製を避ける
上位のContainerでwhen句を使用してドキュメントを別のレイアウトにインフレートすると、Containerコンポーネントでコンテンツが複製されることがあります。この複製により、デザインを反復処理するときに、ドキュメントの更新が難しくなります。たとえば、前述の構造では、背景、ヘッダー、スクロールコンテンツはすべて、APLドキュメントで2回指定されています。backgroundImageSourceなどのプロパティ値をドキュメント内で直接設定する場合は2回設定し、変更を行ったときは2か所とも更新する必要があります。
この問題を回避するために、APLでは、コンテンツのシングルソーシングを行うためのツールをいくつか提供しています。
- 複数のレイアウトにおいて、リソースとして使用する定数を定義します。たとえば、すべてのレイアウトでリソースとして使用するカスタムの色を定義できます。
- コンテンツを別のデータソースに配置して、データバインディングを使用してプロパティを設定します。データソースは、スキルの実行時に生成して変更するコンテンツに適しています。コードでは、適切なデータソースを構築して、
Alexa.Presentation.APL.RenderDocumentディレクティブに含めることができます。 - 変更の可能性があるプロパティのパラメーターを持つ、再利用可能なレイアウトを作成します。
mainTemplate内にレイアウトを配置して、データをそのレイアウトに一度に渡します。
この例では、小型の円形デバイスではヘッダーが画面をスクロールしますが、大きなviewportでは固定されたままです。ここでは、データソース内の両方のバージョンのレイアウトに必要なデータを定義しています。表示するメインのコンテンツは、配列内の一連の段落です。
ScrollViewこの例では、パラメーターを持つ同じデザインを再利用可能なレイアウトとして実装します。mainTemplateは1つのカスタムのレイアウトコンポーネントを含み、データをパラメーターに一度に渡します。レイアウトパラメーターによって複製は排除されますが、コンテンツには引き続きデータソースを使用します。
スクロールテキストについて詳しくは、以下を参照してください。
項目の周囲に境界線を描く
画面の項目の周囲に境界線を描くには、Frameコンポーネントを使用します。このコンポーネントには、境界線、背景色、またはその両方を含めることができます。Frameは、境界線内に表示する1つの子コンポーネントを指定します。複数のコンポーネントの周囲に境界線を描く場合は、コンポーネントをContainerに格納して、そのContainerをFrame内で子コンポーネントとして使用します。
境界線の例
この例では、Textコンポーネントの周囲に青緑色の境界線を作成します。paddingプロパティは、Frame内のTextコンポーネントと境界線の間にスペースを作成します。
{
"type": "Frame",
"borderColor": "@colorTeal800",
"borderWidth": "5",
"paddingLeft": "@spacingXSmall",
"paddingRight": "@spacingXSmall",
"paddingTop": "@spacingXSmall",
"paddingBottom": "@spacingXSmall",
"items": [
{
"type": "Text",
"text": "この<code>Frame</code>には、青緑色の境界線と透明な背景が含まれています。<code>Frame</code>には、1つの<code>Text</code>コンポーネントが含まれ、<code>Frame</code>の内側に表示されます。",
"style": "textStyleBody",
"maxLines": 3
}
]
}
この例では、Frameはほかのコンポーネントも持つContainerに格納されています。Alexaは、Frameの子コンポーネントの周囲に境界線を描きます。
Textコンポーネントの周囲に表示される境界線角丸と円形の境界線
borderRadiusプロパティを使用して、角丸を作成します。デフォルトでは、これらのプロパティは0に設定されているため、直角になります。境界線の丸みの値を大きくすると、角が丸くなります。大きな値に設定すると、Frameは円（Frameが正方形の場合）、または細長い円か楕円（Frameが正方形でない場合）として描画されます。
Alexa Stylesパッケージでは、境界線の丸みを設定するために使用できる事前定義されたリソースを提供しています。このリソースは、shapeRoundedRectとshapeCircleです。
この例では、2つのFrameコンポーネントを表示しています。1つのコンポーネントはborderRadiusを0に、もう1つのコンポーネントはshapeRoundedRectに設定されています。
境界線を円にする場合は、必ずFrameのheightとwidthを正確に同じサイズに設定してください。次の例では、borderRadiusがshapeCircleに設定された、2つのFrameコンポーネントを示しています。最初のFrameは、heightとwidthの寸法が異なるため、細長い円として表示されます。2番目は、heightとwidthが同じ値に設定されているため、円として表示されます。
背景色でフレームを塗りつぶす
Frameには、backgroundColorプロパティも含まれています。各項目の後ろに色付きの背景を表示する場合に使用します。viewport全体の背景を指定する場合は、AlexaBackgroundレスポンシブ対応コンポーネントを使用してください。
たとえば、このFrameは、背景色で塗りつぶした円を作成します。指定されたテキストが円の内側に表示されます。
{
"type": "Frame",
"width": "25vw",
"height": "25vw",
"backgroundColor": "${backgroundColor}",
"spacing": "@spacingMedium",
"borderRadius": "@shapeCircle",
"items": [
{
"type": "Text",
"text": "${text}",
"textAlign": "center",
"width": "100%",
"height": "100%",
"textAlignVertical": "center"
}
]
}
次の点に注意してください。
AlexaBackgroundは、viewport全体に表示される背景画像を指定します。TextCircleWithBackgroundというカスタムレイアウトは、Frameを定義します。このレイアウトには、表示する色とテキストのパラメーターを指定できます。Containerは、mainTemplateにTextCircleWithBackgroundを配置します。Containerのdataプロパティにはオブジェクトの配列が含まれ、それぞれが色とテキストを設定します。
デバイスがこのドキュメントを表示すると、data配列の各項目に対してTextCircleWithBackgroundが表示されます。
