コンテンツを背景、境界線、ヘッダーと結合する



コンテンツを背景、境界線、ヘッダーと結合する

大半のAlexa Presentation Languageのコンポーネントには境界線や背景色のプロパティがないため、背景と境界線を表示するには、複数のコンポーネントを結合する必要があります。

viewport全体に背景を表示する

背景色、画像、またはビデオを表示するには、Alexa Backgroundレスポンシブ対応コンポーネントを使用します。コンポーネントはviewport全体に表示され、各viewportのサイズに合わせて自動的に調整されます。AlexaBackgroundコンポーネントをContainer内のほかのコンポーネントと結合すると、同じ親Container内のコンポーネントが背景の上に表示されるようになります。

コンテンツの後ろに表示される背景を作成する方法は下記のとおりです。

  1. ドキュメント内のimport配列に、現在のバージョンのalexa-layoutsを追加します。
     {
       "import": [
         {
           "name": "alexa-layouts",
           "version": "1.1.0"
         }
       ]
     }
    
  2. AlexaBackgroundContainer内のほかのコンポーネントと結合します。背景の上に表示するコンポーネントの前にAlexaBackgroundを配置します。

     {
       "type": "Container",
       "items": [
         {
           "type": "AlexaBackground",
         },
         {
           "type": "Text",
           "text": "背景の上に表示されるテキスト。",
         }
       ]
     }
    

    ほかのコンポーネントの後にAlexaBackgroundを配置すると、背景がほかのコンポーネントを覆い隠します。

  3. 背景を表示するには、少なくともbackgroundVideoSourcebackgroundImageSource、またはbackgroundColorを設定してください。
     {
       "type": "AlexaBackground",
       "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/MollyforBT7.png"
     }
    

    これらのプロパティの1つだけが使用されます。たとえば、backgroundImageSourcebackgroundColorの両方を指定すると、Alexaは背景画像を表示します。Alexa Background背景ソースの優先順位を参照してください。

    これらの3つのソースプロパティのいずれも設定しない場合、Alexaはデフォルトの背景を表示します。

この例では、背景に画像を使用します。colorOverlayも設定して画像にレイヤーを適用し、テキストが読みやすくなるようにします。

Textコンポーネントの後ろに背景画像を表示
AlexaBackgroundを使用して、Textコンポーネントの後ろに背景画像を表示

AlexaBackgroundコンポーネントでは、絶対位置を使用してほかのコンポーネントがその上に表示されるようにします。つまり、子項目を配置するための親Containerのプロパティは、背景に影響しません。

たとえば、このContainerでは、justifyContentendに設定されているため、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プロパティ
背景に影響しないjustifyContentプロパティとpaddingBottomプロパティ

画面上部にヘッダーを表示する

ヘッダーは画面上部に表示されるので、タイトルとサブタイトルの情報を表示したり、アイコンを使ってスキルをブランディングするのに役立ちます。

Alexaレイアウトパッケージで指定されたAlexa HeaderAlexaHeader)レスポンシブ対応コンポーネントを使用して、ドキュメントにヘッダーを追加します。

ドキュメントにヘッダーを追加する方法

  1. ドキュメント内のimport配列に、現在のバージョンのalexa-layoutsを追加します。
     {
       "import": [
         {
           "name": "alexa-layouts",
           "version": "1.1.0"
         }
       ]
     }
    
  2. AlexaHeaderContainer内のほかのコンポーネントと結合します。viewportの上部でほかのコンポーネントの前に表示されるように、AlexaHeaderを配置します( AlexaBackgroundも使用している場合を除く)。

     {
       "type": "Container",
       "items": [
         {
           "type": "AlexaHeader",
           "headerTitle": "これはメインヘッダーのタイトルです",
           "headerSubtitle": "これはヘッダーのサブタイトルです",
           "headerDivider": true,
           "headerAttributionImage": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png"
         },
         {
           "type": "Text",
           "text": "ヘッダーの後に表示するテキスト。"
         }
       ]
     }
    
  3. ヘッダーに表示するプロパティ(headerTitleheaderSubtitleなど)を設定します。使用可能なプロパティについては、Alexa Headerを参照してください。

ヘッダーの後にテキストを表示
ヘッダーの後にテキストを表示

AlexaHeaderとほかのコンポーネントを合わせて配置する

Containerのプロパティを使用して、子コンポーネントの位置を指定します。画面上部のAlexaHeaderの配置を妨げるようなレイアウトは作成しないでください。レイアウトによっては、次のように追加のContainersをネストする必要があります。

Container
  AlexaHeader
  Container
    ほかのコンポーネント...

AlexaHeaderを含むContainerのレイアウトを定義するときは、以下の点に留意してください。

  • Alexa BackgroundAlexaBackgroundAlexaHeaderの両方を一緒に使用できます。この場合、まずContainerAlexaBackgroundを配置し、その後でAlexaHeaderを配置します。
  • レイアウト方向Containerdirectionプロパティをデフォルト設定(column)のままにします。この設定により、縦型レイアウトが作成され、子コンポーネントは前のコンポーネントの下に表示されます。この設定をrowに変更すると、子コンポーネントは前のコンポーネントの右側に表示されます。これは、画面上部にヘッダーを配置することを妨げます。横型のレイアウトを作成するときは、別のContainerをネストして、AlexaHeaderの下に配置してください。
  • 絶対位置と相対位置 – 同じContainer内の項目のどれかに絶対位置を使用する場合は、注意が必要です。コンポーネントのpositionabsoluteに設定すると、そのコンポーネントは通常の階層から除外され、親に対して相対的に配置されます。これにより、コンテンツがヘッダーと重なる場合があります。デフォルトのpositionrelative)では、後続のコンポーネントがヘッダーの後に自動的に配置されるため、扱いが簡単です。

    AlexaHeaderと同じContainer内のコンポーネントで絶対位置を使用する場合は、コンポーネントがヘッダーと重複しないように、topのオフセットを十分に大きく設定してください。または、bottomプロパティを使用して、viewportの下からコンポーネントをオフセットしてください。

  • 主軸上の配置Containerの方向がcolumnの場合、justifyContentプロパティによって、子コンポーネントの縦方向のレイアウトが制御されます。デフォルト値(start)を使用して、AlexaHeaderを画面上部に表示します。これを変更すると、AlexaHeaderの縦方向の配置も変更されます。たとえば、justifyContentendに設定すると、Container内のすべてのコンポーネント(AlexaHeaderを含む)がviewportの下部に移動します。

    一部の項目に別のjustifyContent設定を使用する場合は、別のContainerをネストして、そこにjustifyContentを設定します。

  • 交差軸上の配置Containerの方向がcolumnの場合、alignItemsプロパティによって、子コンポーネントの横方向の配置が制御されます。これをデフォルト(auto)のままにしてください。変更すると、AlexaHeaderの横方向の配置も変更されます。必要に応じてほかの子コンポーネントの配置を変えるには、次のような方法があります。
    • ほかのコンポーネントを別のContainer内にネストして、そのContaineralignItemsを設定します。
    • ContaineralignItemsをデフォルトの設定にしたまま、AlexaHeader以外の子に対してalignSelfで上書きします。
    • 必要に応じて親ContaineralignItemsを変更し、AlexaHeaderalignSelfstretchに設定します。
  • パディングContainerレベルでのpaddingプロパティは、AlexaHeaderを含むすべてのContainerの子コンポーネントの配置を変更します。たとえば、paddingTopを設定すると、ヘッダーが押し下げられ、paddingLeftを設定すると、インデントが適用されます。AlexaHeaderコンポーネントで定義されたパディングを使用するには、Containerpaddingプロパティを設定しないままにします。必要に応じてほかの子コンポーネントに別のパディングを設定するには、次のような方法があります。
    • ほかのコンポーネントを別のContainer内にネストして、そこにpaddingプロパティを設定します。
    • それぞれの子コンポーネントにpaddingプロパティを設定します。

    子コンポーネントの左右のマージンをAlexaHeaderの左右のパディングに一致させるには、これらのコンポーネントのpaddingLeftプロパティとpaddingRightプロパティを、Alexa Stylesパッケージで指定されているmarginHorizontalリソースに設定します。

  • データ配列のインフレートdataプロパティを持つComponentにデータ配列をバインドできます。この場合、Alexaは配列の各項目について、whentrueであるitemsの最初のコンポーネントを表示します。これにより、AlexaHeaderコンテンツが複数回表示されますが、ほかのコンポーネントは無視されます。この状況でAlexaHeaderを使用するには、itemsではなく、ContainerfirstItemプロパティにAlexaHeaderを配置します。

2番目のContainerを使用して、中央揃えの項目の上にヘッダーを表示
2番目のContainerを使用して、中央揃えの項目の上にヘッダーを表示

firstItemプロパティを使用して、データ配列のインフレートでヘッダーを使用
firstItemプロパティを使用して、データ配列のインフレートでヘッダーを使用

画面下部のフッターでは、ヒントを表示して、ユーザーが使うほかのフレーズを提案できます。

Alexaレイアウトパッケージで指定されたAlexa FooterAlexaFooter)レスポンシブ対応コンポーネントを使用して、ドキュメントにフッターを追加します。

ドキュメントにフッターを追加する方法

  1. ドキュメント内のimport配列に、現在のバージョンのalexa-layoutsを追加します。
     {
       "import": [
         {
           "name": "alexa-layouts",
           "version": "1.1.0"
         }
       ]
     }
    
  2. AlexaFooterContainer内のほかのコンポーネントと結合します。AlexaFooterを最後に配置して、ほかのコンポーネントの後にviewportの下部に表示されるようにします。

     {
       "type": "Container",
       "items": [        
         {
           "type": "Text",
           "text": "本文テキスト。"
         },
         {
           "type": "AlexaFooter"
         }
       ]
     }
    
  3. hintTextプロパティに表示するテキストを設定します。

    データソースとデータトランスフォーマーを使用して、デバイスのウェイクワードを使ってヒントを自動的にフォーマットします

  4. ほかのContainerプロパティを設定して、フッターがviewportの下部に表示されるようにします。後述のフッターの位置を設定するを参照してください。

この例では、ヘッダーとフッターの両方を含むTextコンポーネントを表示します。

基本的なフッターの例
基本的なフッターの例

AlexaFooterがContaineritems配列の最後にある場合、ほかのすべてのコンポーネントの後に表示されます。ただし、ほかのコンポーネントのサイズによっては、意図したとおりにviewportの下部に表示されない場合があります。AlexaFooterを常にviewportの下部に表示するには、次のような方法があります。

  • AlexaFooterpositionabsoluteに設定して、bottomを0に設定します。これにより、ほかのコンポーネントの位置やサイズに関係なく、AlexaFooterはviewportの下部から0ピクセル分オフセットされます。AlexaFooterレスポンシブ対応コンポーネントにはボトムパディングが含まれているため、追加のパディングを含める必要はありません。前述の基本的なフッターの例では、このオプションを使用しています。

    本文のコンテンツとフッターの両方に十分な縦方向のスペースがない場合、フッターは本文のコンテンツと重なります。本文のコンテンツが長くなりすぎないようにしてください。

  • Containerheightをviewport全体の高さに設定して、Container内のほかのコンポーネントでgrowを「1」に設定します。growを持つコンポーネントはviewport内の空白スペース全体に拡張されて表示されます。

    本文のコンテンツとフッターの両方に十分な縦方向のスペースがない場合、フッターは画面下部に表示されなくなります。本文のコンテンツが長くなりすぎないようにしてください。

この例では、viewport内の本文に2つのTextコンポーネントがあります。2番目のコンポーネントではgrowを「1」に設定して、Textのバウンディングボックスが残りのスペース全体に広がるようにしています。

growを使用して、viewportの下まで押し下げられたフッター
growを使用して、viewportの下まで押し下げられたフッター

長いコンテンツを表示する場合は、小型の円形のデバイスではフッターを非表示にします。次のようにwhenプロパティを使用してください:"when": "${@viewportProfile != @hubRoundSmall}

ヒントにデバイスのウェイクワードを使用する

ユーザーは、デバイスで使用するウェイクワードを設定できます。ウェイクワードが常に「アレクサ」であるとは限らないため、フッターのテキストを「『アレクサ、何かほかのことをして...』と言ってみてください」のようにハードコーディングせず、data sourcetextToHintトランスフォーマーを使用して、デバイス固有のウェイクワードをヒントに自動的に含めることができます。このトランスフォーマーには、テキストのフォーマットを適用して一貫性を保ちます。

textToHintトランスフォーマーを使用する

  1. objectデータソースのpropertiesオブジェクト内のプロパティにヒントテキストを配置します。この例では、ヒントはpropertiesオブジェクト内のhintTextToTransformプロパティに格納されています。ここにはヒントの語句だけを含めるようにしてください。ウェイクワードや「言ってみてください」という語句は除外します。
     {
       "footerExampleData": {
         "type": "object",
         "objectId": "footerExampleData",
         "description": "このデータソースには、フッターのヒント例が含まれています。",
         "properties": {
           "hintTextToTransform": "このスキルを使って何かほかのことをして"
         }
       }
     }
    
  2. データソースのtransformers配列にtextToHintトランスフォーマーを追加して、そのトランスフォーマーのinputPathをヒントテキストを持つプロパティに設定します。変換された値のoutputNameプロパティを指定します。
     {
       "transformers": [
         {
           "inputPath": "hintTextToTransform",
           "transformer": "textToHint",
           "outputName": "transformedHintText"
         }
       ]
     }
    

    outputNameは省略できます。この場合、変換された値は、inputPathで指定したプロパティで使用できます。

  3. ドキュメントでは、データバインディングを使用して、AlexaFooterhintTextプロパティをトランスフォーマー出力に設定します。
     {
       "type": "AlexaFooter",
       "hintText": "${payload.footerExampleData.properties.transformedHintText}"
     }
    

このfooterExampleデータソースでは、ヒントテキスト(「このスキルを使って何かほかのことをして」)はfooterExampleData.properties.hintTextToTransformに格納されています。テキストはfooterExampleData.properties内にあると想定されているため、inputPathhintTextToTransformという名前のプロパティを参照するだけです。変換の結果は、transformedHintTextプロパティで使用できます。

この例は、ドキュメント内でトランスフォーマーの出力を使用する方法を示しています。AlexaFooterhintTextプロパティは、データバインディングを使用してfooterExampleDataデータソースからtransformedHintText値を取得します。

デバイスで設定したウェイクワードをヒントに表示
デバイスで設定したウェイクワードをヒントに表示

デフォルトの「アレクサ」というウェイクワードを使用するデバイスには、次のヒントが表示されます。

「アレクサ、このスキルを使って何かほかのことをして」と言ってみてください。

ウェイクワードが「エコー」に設定されたデバイスには、次のヒントが表示されます。

「エコー、このスキルを使って何かほかのことをして」と言ってみてください。

スクロールテキストをヘッダーおよびフッターと結合する

スクロールの必要があるコンテンツでは、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": []
      }
    ]
  }
}

コンテンツの複製を避ける

上位のContainerwhen句を使用してドキュメントを別のレイアウトにインフレートすると、Containerコンポーネントでコンテンツが複製されることがあります。この複製により、デザインを反復処理するときに、ドキュメントの更新が難しくなります。たとえば、前述の構造では、背景、ヘッダー、スクロールコンテンツはすべて、APLドキュメントで2回指定されています。backgroundImageSourceなどのプロパティ値をドキュメント内で直接設定する場合は2回設定し、変更を行ったときは2か所とも更新する必要があります。

この問題を回避するために、APLでは、コンテンツのシングルソーシングを行うためのツールをいくつか提供しています。

  • 複数のレイアウトにおいて、リソースとして使用する定数を定義します。たとえば、すべてのレイアウトでリソースとして使用するカスタムの色を定義できます。
  • コンテンツを別のデータソースに配置して、データバインディングを使用してプロパティを設定します。データソースは、スキルの実行時に生成して変更するコンテンツに適しています。コードでは、適切なデータソースを構築して、Alexa.Presentation.APL.RenderDocumentディレクティブに含めることができます。
  • 変更の可能性があるプロパティのパラメーターを持つ、再利用可能なレイアウトを作成します。mainTemplate内にレイアウトを配置して、データをそのレイアウトに一度に渡します。

この例では、小型の円形デバイスではヘッダーが画面をスクロールしますが、大きなviewportでは固定されたままです。ここでは、データソース内の両方のバージョンのレイアウトに必要なデータを定義しています。表示するメインのコンテンツは、配列内の一連の段落です。

ヘッダーとフッターを使用したScrollView
ヘッダーとフッターを使用したScrollView

この例では、パラメーターを持つ同じデザインを再利用可能なレイアウトとして実装します。mainTemplateは1つのカスタムのレイアウトコンポーネントを含み、データをパラメーターに一度に渡します。レイアウトパラメーターによって複製は排除されますが、コンテンツには引き続きデータソースを使用します。

スクロールテキストについて詳しくは、以下を参照してください。

項目の周囲に境界線を描く

画面の項目の周囲に境界線を描くには、Frameコンポーネントを使用します。このコンポーネントには、境界線、背景色、またはその両方を含めることができます。Frameは、境界線内に表示する1つの子コンポーネントを指定します。複数のコンポーネントの周囲に境界線を描く場合は、コンポーネントをContainerに格納して、そのContainerFrame内で子コンポーネントとして使用します。

境界線の例

この例では、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コンポーネントの周囲に表示される境界線
Textコンポーネントの周囲に表示される境界線

角丸と円形の境界線

borderRadiusプロパティを使用して、角丸を作成します。デフォルトでは、これらのプロパティは0に設定されているため、直角になります。境界線の丸みの値を大きくすると、角が丸くなります。大きな値に設定すると、Frameは円(Frameが正方形の場合)、または細長い円か楕円(Frameが正方形でない場合)として描画されます。

Alexa Stylesパッケージでは、境界線の丸みを設定するために使用できる事前定義されたリソースを提供しています。このリソースは、shapeRoundedRectshapeCircleです。

この例では、2つのFrameコンポーネントを表示しています。1つのコンポーネントはborderRadiusを0に、もう1つのコンポーネントはshapeRoundedRectに設定されています。

角丸の長方形の境界線
角丸の長方形の境界線

境界線を円にする場合は、必ずFrameheightwidthを正確に同じサイズに設定してください。次の例では、borderRadiusshapeCircleに設定された、2つのFrameコンポーネントを示しています。最初のFrameは、heightwidthの寸法が異なるため、細長い円として表示されます。2番目は、heightwidthが同じ値に設定されているため、円として表示されます。

円形の境界線
円形の境界線

背景色でフレームを塗りつぶす

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は、mainTemplateTextCircleWithBackgroundを配置します。Containerdataプロパティにはオブジェクトの配列が含まれ、それぞれが色とテキストを設定します。

デバイスがこのドキュメントを表示すると、data配列の各項目に対してTextCircleWithBackgroundが表示されます。

背景色を指定した円形のFrame
背景色を指定した円形のFrame