画面上にテキストを表示する



画面上にテキストを表示する

Alexa Presentation Languageを使用する大半のスキルでは、簡単なテキストを表示しています。このドキュメントでは、Viewportにシンプルなテキストコンテンツを配置する方法を説明します。

背景付きの短いヘッドラインを表示する

背景付きの短いテキストを画面に配置する最も簡単な方法は、Alexa HeadlineAlexaHeadline)レスポンシブ対応テンプレートを使用することです。表示するテキスト、使用する背景(色、画像、ビデオなど)、ヘッダーまたはフッターテキストを指定します。背景やヘッダーテキスト、フッターテキストは任意です。テンプレートはこれらすべてをViewportに表示するよう処理し、異なるサイズのViewportに合わせてレイアウトを自動的に調整します。テンプレートは自動的にViewport全体に表示されます。

Alexa Headlineでは、primaryTextsecondaryTextのテキストを指定できます。第1テキストは画面の中央に大きなフォントで表示され、2行を超えると切り詰められます。第2テキストはそれより小さく、1行に制限されます。

このテンプレートは、表示するテキストが非常に少ない場合に使用します。デザインのガイダンスについては、Headlineを参照してください。

Alexa Headlineを使用して背景付きのシンプルなテキストを配置する方法

  1. alexa-layoutsの最新バージョンをドキュメントのimport配列に追加します。
     {
       "import": [
         {
           "name": "alexa-layouts",
           "version": "1.1.0"
         }
       ]
     }
    
  2. AlexaHeadlineコンポーネントをmainTemplateitems配列に追加します。少なくとも、primaryTextを表示するテキストに設定します。

     {
       "type": "AlexaHeadline",
       "primaryText": "表示するヘッドラインのテキストです。",
       "secondaryText": "オプションの第2テキストです。" 
     }
    

    すべてのパラメーターについては、AlexaHeadlineを参照してください。

以下の例では、背景の上にテキストを表示し、ヘッダーのアトリビューション画像を右上に、ヒントを下に表示しています。テキストプロパティにデータバインディング式を使用し、データソースheadlineExampleDataを使用しています。

Alexa Headlineテンプレートでシンプルなテキストを表示
Alexa Headlineテンプレートでシンプルなテキストを表示

「今日のチーズ」の例では、テンプレートのフッターはtextToHintトランスフォーマーを使用し、「今日のチーズについてのジョークを教えて」というテキストをヒントとして適切な書式に設定しています。トランスフォーマーは、ユーザーのデバイスに設定されているウェイクワード(「アレクサ」、「エコー」など)を追加し、テキストを引用符で囲んで、先頭に「試してみよう」を追加します。

詳細については、コンテンツを背景、境界線、ヘッダーと結合するヒントにデバイスのウェイクワードを使用するを参照してください。

Textコンポーネントで独自のデザインを作成する

テキストを表示するには、ドキュメントにTextコンポーネントを配置して、そのtextプロパティを設定します。textプロパティを設定するには、データソースとデータバインディングを使用します。

この例では、画面に「ハローワールド」と表示します。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "1.3",
  "mainTemplate": {
    "parameters": [
      "helloworldData"
    ],
    "items": [
      {
        "type": "Text",
        "text": "${helloworldData.helloText}"
      }
    ]
  }
}

この例では、helloworldDataというデータソースからTextコンポーネントのコンテンツを取得します。

クリップボードにコピーされました。

{
  "helloworldData": {
    "helloText": "ハローワールド"
  }
}
配置用のプロパティがない<code>Text</code>コンポーネント
配置用のプロパティがないTextコンポーネント

上の例では、Viewportの左上隅にデフォルトのフォントスタイルとサイズで「ハローワールド」と表示されました。しかし、通常はコンテンツの配置と外観を指定することが多いので、APLではViewportにTextコンポーネントを配置して書式設定する方法をいろいろと用意しています。

  • Container内にコンポーネントを配置します。Containerは、1つのコンポーネントを表示するmainTemplateとは異なり、複数の子コンポーネントを表示することができます。その子コンポーネントのレイアウト方法を指定するさまざまなオプションも提供しています。
  • テキストを格納する非表示のバウンディングボックス</em>のサイズを指定してテキストを制約し、Textコンポーネントの配置プロパティ(textAlignおよびtextAlignVertical)を使用してボックス内にテキストを配置します。
  • paddingプロパティ(paddingToppaddingLeftなど)を使用して、コンポーネントの周囲にマージンとスペースを追加します。すべてのAPLコンポーネントにこれらのプロパティがあるため、レイアウトのニーズに応じて、Textコンポーネント自体、またはその親コンポーネントでプロパティを設定できます。
  • テキストのスタイル、文字表現のプロパティ、マークアップを使用して、書式を設定します。

テキストの書式を設定する

Textコンポーネントには、テキストの見た目をコントロールするfontSizefontStylefontFamilyletterSpacingなどのさまざまなプロパティがあります。これらのプロパティの詳細については、Textコンポーネントのプロパティを参照してください。Alexa Stylesパッケージには、これらの値を設定するときに使用できるリソースとテキストスタイルが含まれているため、一貫性のある見た目に整えることができます。

また、テキスト内でいくつかの基本的なマークアップタグを使用してインラインで書式設定をすることもできます。

Textコンポーネントのバウンディングボックスを理解する

Textコンポーネントには、テキストが内側から出ないように制約する非表示のバウンディングボックスがあります。このボックスのheightwidthは、対応するTextコンポーネント自体のプロパティで設定できます。

Textコンポーネントのheightプロパティとwidthプロパティが指定されていない場合、デフォルトのautoになります。つまり、バウンディングボックスは、コンポーネントの親の制約内で、コンテンツに合わせたサイズになります。

たとえば、height/widthを100vh/100vwに設定したContainerがあり、そのContainerがViewport全体に表示されるとします。次の表は、このContainer内にTextコンポーネントのバウンディングボックスを配置してTextコンポーネントのheightプロパティとwidthプロパティをさまざまな方法で設定したときに、バウンディングボックスがどのように機能するかをまとめたものです。

Textコンポーネントのheightとwidthの設定 バウンディングボックスの動作

heightwidthを設定していない(auto)

バウンディングボックスは、Container内のスペースをコンテンツに必要なだけ占有します。したがって、バウンディングボックスは、Containerの制約内で、テキストの幅と高さになります。具体例は、 自動サイズに設定したTextコンポーネントを参照してください。

heightwidthのいずれか、または両方が相対ディメンションに設定されている

バウンディングボックスは、親Containerのサイズに相対的なサイズになります。たとえば、Textコンポーネントのwidthが50%に設定されている場合、バウンディングボックスはContainerのサイズの50%になります。具体例は、 相対的な高さと幅のTextコンポーネントを参照してください。

heightwidthのいずれか、または両方が絶対ディメンションに設定されている

バウンディングボックスは指定された絶対サイズを持ちますが、親Containerのサイズによって制約されるため、親Containerよりも大きい場合は切り詰められます。たとえば、Containerwidthが“50vw”(Viewportの幅の50%)で、Textのwidthが“100vw”の場合、Textのバウンディングボックスは親に対して大きすぎるため、切り詰められます。

そのため、Container内のコンポーネントのサイズを絶対サイズにすることは避けてください。

heightwidthが設定されておらず(auto)、growが1に設定されている

バウンディングボックスはコンテンツに必要なだけのスペースを占有し、さらに拡張されてContainer内の使用可能なスペース全体に表示されます。これは、Container内に複数のコンポーネントを配置する場合に便利です。具体例は、 Container全体に広がるTextコンポーネントを参照してください。

TextコンポーネントがContainer内にある場合のみ、growプロパティとshrinkプロパティを使用できます。その場合は、子Containerでもほかのプロパティを使用できます。

バウンディングボックスは常に長方形

テキストバウンディングボックスは常に長方形です。円形の画面を搭載しているデバイスでは、バウンディングボックスの端に近いテキスト(上下など)が切れることがあります。次に例を示します。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "1.3",
  "mainTemplate": {
    "parameters": [
      "textNoMarginsData"
    ],
    "items": [
      {
        "type": "Container",
        "height": "100vh",
        "width": "100vw",
        "items": [
          {
            "type": "Text",
            "text": "${textNoMarginsData.textAboutMargins}"
          }
        ]
      }
    ]
  }
}

クリップボードにコピーされました。

{
  "textNoMarginsData": {
    "textAboutMargins": "この<code>Text</code>コンポーネントにはマージンがないため、バウンディングボックスの端まで表示されます。小型の円形デバイスではテキストが切れます。”
  }
}

長方形のViewportでは、これは判読可能ですが、テキストが画面の端まで広がっているため見栄えがよくありません。円形デバイスでは、画面のそれぞれの端でテキストが切れているため読めなくなっています。

円形のViewportでは<code>Text</code>バウンディングボックスの端まで表示されない例
円形のViewportではTextバウンディングボックスの端まで表示されない例

これを修正するには、paddingプロパティを使用してテキストの周囲にスペースを作り、バウンディングボックスの端から離します。paddingTopプロパティとpaddingBottomプロパティのパディングを大きくすると、円形のViewportには特に有効です。

次の例では、Alexa Stylesパッケージで提供されているSpacingリソースを使用して、テキストの周囲にパディングを追加しています。また、同じパッケージのtextStyleBodyスタイルを使用して、本文テキストに合わせてテキストを書式設定し、textAlignプロパティを使用してテキストを中央に配置しています。

上パディング、テキストの中央配置、適切なフォントサイズの設定により小型の円形デバイスでテキストを適切に表示している例
上パディング、テキストの中央配置、適切なフォントサイズの設定により小型の円形デバイスでテキストを適切に表示している例

テキストの見栄えを良くするために使えるテクニックについては、さまざまなサイズの画面でテキストの見栄えを良くするを参照してください。

以降のセクションでは、Textコンポーネントのバウンディングボックスと、コンポーネント内のテキストを配置するためのプロパティを組み合わせた例をいくつか紹介します。

例: 自動サイズに設定したTextコンポーネント

これは、Viewport全体に表示されるContainer内で、サイズがautoに設定されているTextの例です。テキストは必要なだけの領域を占有します。テキストバウンディングボックスの高さはテキスト自体とまったく同じであるため、textAlignVerticalプロパティの効果はありません。

サイズがデフォルトのautoに設定されているTextコンポーネント
サイズがデフォルトのautoに設定されているTextコンポーネント

例: 相対的な高さと幅のTextコンポーネント

これは、Textコンポーネントのheightwidth相対ディメンション(100%)に設定した例です。Textコンポーネントのバウンディングボックスは、コンテンツに必要なサイズに関係なく、Container全体のサイズになります。そのため、textAlignVerticalなどの配置プロパティを使用してテキストを配置できます。

heightとwidthが定義されている<code>Text</code>コンポーネント
heightとwidthが定義されているTextコンポーネント

例: Container全体に広がるTextコンポーネント

また、growプロパティを1に設定することで、Textコンポーネントのサイズが親Containerの使用可能なスペース量に基づいて動的に調整されるようにすることもできます。TextコンポーネントがContainer内にある場合のみ、このプロパティを適用できます。その場合は、子Containerでもほかのプロパティを使用できます。

これは、Container内に複数のコンポーネントを配置する場合に特に便利です。2つのTextコンポーネントのうち、1つをViewportの上部に、もう1つを下部に表示する例を示します。growプロパティを使用すると、2番目のコンポーネントのバウンディングボックスが1番目のコンポーネントの後に残っているすべての垂直方向のスペースを埋めるため、textAlignVerticalでテキストをViewportの下部に配置できます。

<code>Text</code>コンポーネントでサイズがautoに設定されているが、<code>grow</code>が1に設定されている場合
Textコンポーネントでサイズがautoに設定されているが、growが1に設定されている場合

growshrinkプロパティは0~1の値を受け付け、縦横比を維持して機能します。たとえば、grow0.5に設定すると、Container内の空きスペースの半分を埋めるようにコンポーネントが広がります。

<code>Text</code>コンポーネントでサイズがautoに設定されているが、<code>grow</code>が0.5に設定されている場合
Textコンポーネントでサイズがautoに設定されているが、growが0.5に設定されている場合

長いスクロールテキストを表示する

Textコンポーネントはスクロールしないため、小型デバイスでは長いコンテンツが切り詰められることがあります。長いコンテンツがある場合は、ScrollViewコンポーネントを使用して、テキストやその他のコンポーネント用に画面上にスクロール可能な領域を作成します。ユーザーは画面にタッチすることで、コンテンツをスクロールできます。また、ScrollViewを設定すると、ユーザーが「アレクサ、下にスクロールして」などの発話によって、音声でコンテンツをスクロールできるようになります。

ScrollViewでTextコンポーネントを表示する

ScrollViewには、1つの子コンポーネントがあります。テキストブロックを表示するには、TextコンポーネントをScrollViewの子として使用します。複数のコンポーネントを表示するには、Container内にコンポーネントを配置し、そのContainerScrollViewの子として使用します。

これは、Viewportの大部分を使用する領域にある大きなテキストブロックで、すべての辺にパディングがある場合の例です。この例ではScrollViewが唯一のトップレベルコンポーネントであるため、ScrollViewをmainTemplateに直接配置します。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "1.3",
  "import": [
    {
      "name": "alexa-styles",
      "version": "1.1.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "scrollTextData"
    ],
    "items": [
      {
        "type": "ScrollView",
        "id": "simpleScrollViewExample",
        "height": "100vh",
        "paddingLeft": "@marginHorizontal",
        "paddingRight": "@marginHorizontal",
        "paddingBottom": "@spacingSmall",
        "paddingTop": "@spacingSmall",
        "items": [
          {
            "type": "Text",
            "text": "${scrollTextData.simpleScrollingText}",
            "style": "textStyleBody"
          }
        ]
      }
    ]
  }
}

子が<code>Text</code>コンポーネントである<code>ScrollView</code>コンポーネント
子がTextコンポーネントであるScrollViewコンポーネント

円形Viewportにパディングを使用する

円形デバイスでテキストが切れるのを防ぐには、ScrollViewの上部に十分なパディングを使用します。前の例では、spacingSmallリソースにpaddingTopを設定しました。これは長方形のViewportでは機能しますが、円形のViewportでは適切に表示されません。

長いテキストが円形Viewportで適切に表示されない例
長いテキストが円形Viewportで適切に表示されない例

円形Viewportの場合はpaddingTopの値を増やします。textAlignを使用してテキストを水平方向にセンタリングして、テキストコンテンツをViewportの最大の部分に入れ込み、カーブしている端から離すようにしてください。

円形Viewportに収まるようにパディングとセンタリングを設定した例
円形Viewportに収まるようにパディングとセンタリングを設定した例

カスタムスタイルとリソースを使用して、Viewportなどの条件に基づいてこれらのプロパティを異なる値に設定できます。詳細については、この後のさまざまなサイズの画面でテキストの見栄えを良くするで説明します。

スクロールコンテンツの上や下に固定領域を作成する

前の例では、テキストがViewportの一番下までずっと続いているため、paddingBottomプロパティが使用されていないように見えるかもしれません。ScrollViewの「top」と「bottom」は、スクロール可能なコンテンツを含むコンポーネントの全体の垂直サイズに基づいています。パディングプロパティは、スクロール可能なコンテンツの最初と最後にパディングを追加します。コンテンツの最後までスクロールすると、パディングが表示されます。

コンテンツが最後までスクロールされたときに表示される、<code>ScrollView</code>の下にあるパディング
コンテンツが最後までスクロールされたときに表示される、ScrollViewの下にあるパディング

スクロールコンテンツの上または下にスクロールしない領域が必要な場合は、Containerの中にScrollViewを配置して、ScrollViewではなくContainerにパディングプロパティを設定します。

固定スクロール領域
固定スクロール領域

小型デバイスではスクロールコンテンツの周りに固定領域を使用することはお勧めしません。ただでさえ小さなデバイスのコンテンツ領域が狭まるためです。デバイスごとに異なるレイアウトを作成するには、whenプロパティを使用します。

  • 小型の円形デバイスの場合は、ScrollView自体のパディングプロパティを設定します。これにより、スペースが画面外にスクロールし、コンテンツを表示できる領域が広がります。ScrollView内にほかのコンポーネント(ヘッダーやフッターなど)を配置すると、画面上のすべてのコンテンツがスクロールできるようになります。
  • ほかのすべてのタイプのViewportでは、ScrollViewContainerの中に配置します。Containerのパディングを設定し、画面上に残すほかのコンポーネントは、ScrollViewではなくContainerの子コンポーネントとして含めます。

ヘッダーやフッターなどの固定領域にコンテンツを表示する場合も、同様の方法で行うことができます。コンテンツを背景、境界線、ヘッダーと結合するスクロールテキストをヘッダーおよびフッターと結合するを参照してください。

ユーザーが音声でコンテンツをスクロールできるようにする

ユーザーは画面をタッチしてScrollViewをスクロールできますが、音声でもコンテンツをスクロールさせることができます。

ビルトインインテントを使用して、音声ベースのスクロールを有効にします。

  • AMAZON.ScrollDownIntent
  • AMAZON.ScrollUpIntent
  • AMAZON.PageUpIntent
  • AMAZON.PageDownIntent
  • AMAZON.MoreIntent

ScrollViewは常に垂直方向にスクロールするので、左右にスクロールするビルトインインテントは効果がありません。

ユーザーがこれらのインテントを呼び出すために話す可能性のある発話の例については、画面付きのAlexa搭載デバイスで使用できる標準ビルトインインテントを参照してください。

ユーザーが音声でコンテンツをスクロールできるようにする

  1. 対話モデルに、スクロール用のビルトインインテントを追加します。
    • AMAZON.ScrollDownIntent
    • AMAZON.ScrollUpIntent
    • AMAZON.PageUpIntent
    • AMAZON.PageDownIntent
    • AMAZON.MoreIntent
  2. 対話モデルを再ビルドします。
  3. ドキュメントで、ScrollViewコンポーネントのidプロパティをIDに設定します。そのドキュメント内で一意のIDを使用します。

ScrollViewidを指定しない場合、スクロールインテントは機能しません。

スキルをテストするときは、ScrollViewを表示するインテントを呼び出し、スキルの言語に合った妥当な発話を使用します。次に例を示します。

ScrollViewを表示する対話です。この応答はshouldEndSessionが未定義のままであることに注意してください。そのため、セッションは開いていますが、マイクは閉じています。
ユーザー: アレクサ、下にスクロールして(マイクを開くにはウェイクワードを使用する必要があります)。
コンテンツがスクロールされ、より多くのコンテンツが表示されます。

さまざまなサイズの画面でテキストの見栄えを良くする

テキストを使用する場合、どのような画面付きのAlexaデバイスでもテキストが見栄えよく読みやすく表示されるように、注意すべき点があります。

簡潔な見出しのテキストを表示する場合は、Alexa Headlineレスポンシブ対応テンプレートを使用するのが最も簡単な方法です。このレイアウトは、さまざまなデバイスでうまく動作するように構築されているため、コンテンツを提供するだけで済みます。

独自のレイアウトを作成する場合は、以下のセクションの推奨事項を参考にしてください。

配置プロパティと文字表現プロパティのスタイルを使用する

フォントサイズ、配置、その他の文字表現プロパティなどテキストの表示特性を設定するには、スタイルを使用します。Alexa Stylesパッケージで事前定義されているスタイルを使用することも、独自のスタイルを作成することもできます。スタイルでは、when句を使用して、現在のViewportなどの条件に基づいて表示特性を調整できます。

前述の例では、TextコンポーネントでtextStyleBodyスタイルを使用していました。このスタイルは、長い形式のコンテンツに適しており、さまざまなViewportのフォントサイズを自動的に調整します。

独自のカスタムスタイルを作成することも、ひな形として定義済みのスタイルを使用することもできます。たとえば、円形デバイスでテキストを中央に配置すると見栄えがよい場合は、textStyleBodyをベースとしてカスタムスタイルを定義できます。このスタイルは、hubRoundSmallプロファイルを持つViewport上のテキストを中央に配置しますが、ほかのすべてのタイプのViewportではデフォルト(auto)の設定のままです。

{
  "styles": {
    "customTextStyleBody": {
      "extend": "textStyleBody",
      "values": [
        {
          "when": "${@viewportProfile == @hubRoundSmall}",
          "textAlign": "center"
        }
      ]
    }
  }
}

プロパティ値にリソースを使用する

Textコンポーネントのプロパティ値を設定するときに、ハードコーディングした値ではなく、リソースを使用することを検討してください。リソースとは、値を割り当てることができる名前付き定数です。スタイルと同様に、when句を使用してリソースを作成し、Viewportなどの条件に応じて値が変更されるようにできます。リソースはスタイルとは異なり、任意のプロパティを設定するために使用できます。

Alexa Stylesパッケージには、いくつかの事前定義されたリソースも含まれています。Textについては、次の項目を参照してください。

Textコンポーネントを示した前述の例では、パティングプロパティにスペースのリソースを使用していました。marginHorizontalリソースとspacing3XLargeリソースは、Viewportに基づいて自動的に調整されます。

たとえば、小型の円形デバイスには異なるパディングを設定してバウンディングボックスの端からテキストを離すことができます。

{
  "resources": [
    {
      "dimensions": {
        "myTopAndBottomSpacing": "@spacingSmall"
      }
    },
    {
      "when": "${@viewportProfile == @hubRoundSmall}",
      "dimensions": {
        "myTopAndBottomSpacing": "@spacing3XLarge"
      }
    }
  ]
}

指定した値が必要な任意の場所で@構文を使用します。この例では、paddingBottomプロパティとpaddingTopプロパティの両方がmyTopAndBottomSpacingリソースに設定されています。

{
  "type": "ScrollView",
  "id": "simpleScrollViewExample",
  "height": "100vh",
  "paddingLeft": "@marginHorizontal",
  "paddingRight": "@marginHorizontal",
  "paddingBottom": "@myTopAndBottomSpacing",
  "paddingTop": "@myTopAndBottomSpacing",
  "items": [
    {
      "type": "Text",
      "text": "${payload.scrollTextData.properties.simpleScrollingText}",
      "style": "customTextStyleBody"
    }
  ]
}

小型デバイスでテキストを切り詰める

コンテンツによっては、より小型のデバイスでは長いテキストを切り詰めたり非表示にしたりする必要があります。たとえば、前述のgrowの例を考えてみましょう。大型のViewportでは、2つのTextコンポーネントの間にスペースがあります。小型の円形デバイスでは、コンポーネントは間にスペースがない状態で表示され、少しでも長いとテキストが切れてしまいます。

このシナリオでは、2番目のTextコンポーネントのmaxLinesプロパティを設定できます。これにより、指定した行数内に収まらないテキストが切り詰められて省略記号(「…」)が追加され、意図的にテキストが終わっていることがより明確になります。

スタイルを使用して、Viewportに応じて条件付きでmaxLinesを設定します。この例では、customTextStyleBodyは、Alexa StylesパッケージのtextStyleBodyスタイルを拡張し、すべてのViewportに対してtextAlignVerticalを設定します。そして、hubRoundSmalltextAlignmaxLinesを変更します。

{
  "styles": {
    "customTextStyleBody": {
      "extend": "textStyleBody",
      "values": [
        {
          "textAlignVertical": "bottom"
        },
        {
          "when": "${@viewportProfile == @hubRoundSmall}",
          "textAlign": "center",
          "maxLines": 3
        }
      ]
    }
  }
}

小型の円形デバイスで意図的に切り詰められたテキスト
小型の円形デバイスで意図的に切り詰められたテキスト

さまざまなデバイスでのドキュメントの見栄えを確認する方法については、レスポンシブ対応のAPLドキュメントを作成するを参照してください。