レスポンシブ対応のAPLドキュメントを作成する

レスポンシブ対応のAPLドキュメントを作成する

ユーザーは、さまざまな画面のサイズ、形状、アスペクト比を持つデバイスでスキルを呼び出せます。こうしたすべてのデバイスでスキルの見栄えを良くするには、レスポンシブ対応のAPLドキュメントを作成します。

レスポンシブ対応のAPLドキュメントとは

レスポンシブ対応のAlexa Presentation Language（APL）ドキュメントは、viewportの特性に合わせて調整できます。たとえば、あるスキルを表すのに、大画面のデバイスではタイトルとサブタイトルのテキストを画面上部に表示できます。しかし、同じスキルでも、Echo Spotのような小型デバイスには、スキルを表すアイコンのみを表示できます。

一方、Fire TV向けに作成された非レスポンシブ対応のAPLドキュメントは、小型のEcho SpotやEcho Show 5での使用には向かない可能性があります。こうした非レスポンシブ対応のドキュメントでは、結果として、ユーザーのエクスペリエンスが低下し、スキルがもう一度使用される可能性が低くなります。

最も効果的な方法は、特定のデバイスではなく、デバイスのviewportプロファイルをレスポンシブ対応にすることです。つまり、画面が特定の形状（横長など）で、かつサイズ範囲（xより大きい、yより小さい）に該当する場合に使用するレイアウトを定義できます。このアプローチは、正確な画面サイズを対象にするよりも柔軟性があります。新たに利用可能になったデバイスが上記と同じサイズ範囲に該当する場合、APLドキュメントは新しいデバイスで適切に機能する準備が整っています。

APLでレスポンシブ対応ドキュメントの作成がサポートされる仕組み

APLは、レスポンシブ対応ドキュメントの作成をサポートするように設計されています。さらに、APLでは柔軟な方法でドキュメントを作成できます。さまざまなデバイスで機能するドキュメントを作成することも、1つのデバイスでのみ機能して別のデバイスでは見栄えが良くないドキュメントを作成することもできます。

APLドキュメントを作成する際は、可能な限りレスポンシブ対応機能を使用するようにしてください。レスポンシブ対応機能は次のとおりです。

  • 条件付きロジックを使用できます。特定のコンポーネントまたはレイアウトをviewportに表示するかどうかを決定する基準を定義できます。この基準では、viewportサイズなどのデバイスの特性を使用できます。

  • スタイルとリソースを使用できます。プロパティをグループ化して名前を付け、ハードコーディングされたプロパティ値の代わりにスタイルまたはリソース名を使用します。また、これらの項目は条件付きロジックを持つことができるので、小さなviewportと大きなviewportで別々のフォントサイズを指定してスタイルを定義できます。

  • Viewportプロパティを使用できます。Viewportプロファイルは条件付きロジックの基準として使用できます。Viewportプロファイルは、viewport特性の範囲を表す名前付きリソースです。プロファイルでは形状、向き、サイズの範囲、密度の範囲を指定するため、複数の物理デバイスを表すことができます。これらのプロファイルにロジックの基盤を置くことで、新しいデバイスが利用可能になった際により堅牢なロジックを確保できます。

  • 相対ディメンションを使用できます。ほとんどのサイズは、「100％」などの相対ディメンションで表すことができます。相対ディメンションを使用すると、さまざまなサイズのviewportに合わせてドキュメントのサイズを変更できます。また、タブレットなど、スキルセッション中にサイズが変わる可能性のあるデバイスで、スムーズにドキュメントのサイズを変更することもできます。

  • Alexaのレスポンシブ対応コンポーネントを使用できます。APL向けAlexaデザインシステムには、すぐに使える一連のレスポンシブ対応コンポーネントが用意されています。レスポンシブ対応コンポーネントは、コンポーネント（プリミティブなUI要素）をドキュメントで使用できる構成要素に統合します。レスポンシブ対応コンポーネントを使用すると、一から作成するという手間を省いて簡単に応答性を実現できます。

  • Alexaのレスポンシブ対応テンプレートを使用できます。APL向けAlexaデザインシステムには、すぐに使える一連のレスポンシブ対応テンプレートが用意されています。テンプレートは、コンポーネント（プリミティブなUI要素）とレスポンシブ対応コンポーネントを、viewport全体に表示される完全なレイアウトに統合します。レスポンシブ対応テンプレートを使用すると、一から作成するという手間を省いて簡単に応答性を実現できます。

  • Alexa Stylesを使用できます。APL向けAlexaデザインシステムには、すぐに使える一連のスタイルとリソースが用意されています。Alexa Stylesとリソースは条件付きロジックを使用しているため、さまざまなviewportに合わせて調整できます。

このドキュメントの残りのセクションでは、これらの機能と概念を使用してドキュメントをレスポンシブ対応にする方法について詳しく説明します。

APL向けAlexaデザインシステムを使用する

Alexaデザインシステムでは、スキルで使用できるプレビルドのレスポンシブ対応コンポーネント、テンプレート、スタイルが含まれたパッケージを提供しています。これらはすべて、さまざまなviewportに対応するレスポンシブ仕様になっています。詳細については、以下のセクションを参照してください。

レスポンシブ対応テンプレート

APL向けAlexaデザインシステムで提供されているレスポンシブ対応テンプレートを使用すると、レスポンシブ対応ドキュメントを簡単に作成することができます。各テンプレートにはviewport全体に表示されるレイアウトが用意され、そこにはヘッダーや背景などの必要な要素がすべて含まれています。表示するコンテンツをカスタマイズするには、テンプレートのプロパティを設定します。このオプションを使用する場合、視覚階層にコンポーネントを自分で配置する必要はありません。1つの項目をドキュメントに配置するだけで、全体に適用されます。

たとえば、次のAPLドキュメントでスクロールリストを作成します。mainTemplateプロパティには、AlexaTextListタイプの項目が1つ含まれています。

一方、同様のレイアウトを一から作成するには、7つのコンポーネントをmainTemplate内で手動で調整する必要があります。

  • 上部にタイトルを表示するTextコンポーネント
  • 小さなviewportの上部にアイコンを表示するImageコンポーネント
  • 背景を作成するImageまたはFrame
  • スクロールリストを作成するSequence
  • 各項目の番号を表示するText
  • Textで各項目のテキストを表示
  • TouchWrapperでリスト項目を選択可能にする

レスポンシブ対応テンプレートの詳細については、レスポンシブ対応コンポーネントとテンプレートを参照してください。

次のレスポンシブ対応テンプレートを使用できます。

レスポンシブ対応コンポーネント

APL向けAlexaデザインシステムに用意されているレスポンシブ対応コンポーネントは、コンポーネント（プリミティブなUI要素）をドキュメントで使用できる構成要素に統合しています。各レスポンシブ対応コンポーネントは、レスポンシブ仕様となっています。これらのコンポーネントを組み合わせて、カスタムレイアウトを作成できます。

たとえば、次のコンポーネントを組み合わせてカスタム詳細ページを作成できます。

この場合、ヘッダー、フッター、背景はすべて、さまざまなviewportに合わせて調整されます。レイアウトの本文部分をデザインして、各種viewportに対応できます。次の例ではこのデザイン作業を行うために、TextコンポーネントにmaxLinesプロパティを設定して2行のみを表示し、小さな円形のデバイスではテキストを切り詰めるように指定しています。さらに複雑な本文のレイアウトでは、広範な条件付きロジックとテクニックが必要になります。このコードサンプルでは、正しいヒントテキストを作成するためにデータソースを使用しています。詳細とサンプルについては、textToHintトランスフォーマーを使用するを参照してください。

レスポンシブ対応コンポーネントを使用してカスタムレイアウトを作成する場合は、後半で説明するベストプラクティスに従って、デザインの残りの部分をレスポンシブ対応にしてください。

次のレスポンシブ対応コンポーネントを使用できます。

Alexa Styles

スタイルは、ドキュメントのコンポーネントに適用できる一連の視覚的特性を表します。APL向けAlexaデザインシステムで提供されているAlexaスタイルパッケージ（alexa-styles）には、ドキュメントで使用できる一連のスタイルが含まれています。これらのスタイルは、さまざまなviewportや状況に対応できるように条件付きロジックを使用して作られています。

たとえば、fontSizeLargeスタイルは大きなフォントサイズを定義します。実際のサイズはデバイスのviewportによって変わるため、横長のデバイスではフォントが大きくなり、円形のデバイスではフォントが小さくなります。

スタイルを使用することで、スキルの外観と操作感の一貫性を保つことができます。

スタイルの詳細については、Alexa Stylesを参照してください。

スタイルを設定することができるコンポーネントプロパティについて詳しくは、スタイル設定可能プロパティを参照してください。

レスポンシブ対応ドキュメントに関するベストプラクティス

APLコンポーネントとレスポンシブ対応コンポーネントを組み合わせてAPLドキュメントを作成する場合は、次のベストプラクティスに従って、ドキュメントがすべての異なるviewportで機能するようにしてください。

できるだけ相対ディメンションを使用する

コンポーネントの高さと幅は、絶対ディメンションと相対ディメンションのどちらでも指定できます。

  • 相対ディメンションとは、コンポーネントの親のサイズに対する相対的な割合のことです。ドキュメントの最上位コンポーネントでは、widthを100%に設定すると、viewportの幅全体を表します。
  • 絶対ディメンションでは、20dpのように、ディスプレイ依存のピクセル数を具体的に指定します。

たとえば、次の単純な階層構造を考えてみましょう。

mainTemplate
    Container
        Text
        Text

この例では、最上位のContainerのheightとwidthをどちらも100%に設定して、viewport全体を使用します。次に、TextコンポーネントのサイズをContainerよりも小さい割合にして、Textブロックのサイズを設定します。

レスポンシブ対応ドキュメントには、できるだけ相対ディメンションかautoを使用します。相対ディメンションを使ってコンポーネントのサイズを設定すると、異なるサイズの画面で機能する可能性が高くなります。

さらに、相対ディメンションでは、タブレットなど、スキルセッション中に画面サイズが変わるデバイスをサポートする際の選択肢の幅が広がります。ユーザーは、タブレットを回転させて、縦長と横長を切り替えることができます。デバイスの向きが変わると、コンテンツのサイズが自動で変更されるよう、ドキュメントを設定できます。このようなケースで絶対ディメンションを使うと、コンテンツのサイズがうまく変更されない可能性が高いです。

自動サイズ変更について詳しくは、APLでドキュメントが自動でサイズ変更するよう設定するを参照してください。

vhとvwのディメンションはレスポンシブ対応ですか？

いいえ。単位にvwやvhを使うディメンションは、viewport.widthプロパティやviewport.heightプロパティのショートカットとして機能する絶対ディメンションです。たとえば、Echo Showでは、「100vw」のディメンションが「1024dp」と解決されます。ディメンション「50vw」は「512dp」と解決されます。

viewport.widthプロパティとviewport.heightプロパティは、Reinflateコマンドを実行しない限り、ドキュメントの表示後も変更されない定数です。つまり、スキルセッション中に画面サイズの変わる可能性のあるタブレットなどのデバイスで、vwやvhのディメンションを使うと、ユーザーがデフォルトのサイズ変更オプションを使ってデバイスを回転させたときに、サイズがうまく変更されません。

こうしたエクスペリエンス低下を防ぐため、ディメンションを指定する際にvwやvhを使わないようにしてください。できるだけ、相対ディメンションを使用します。

タブレットをサポートする詳細については、サイズ変更が可能なタブレットなどのデバイスをサポートするを参照してください。

条件付きロジックでviewportプロファイルを使用する

条件付きロジックはレスポンシブ対応のAPLドキュメントにおける主要な概念ですが、最も柔軟に対応できる方法でロジックを定義することが重要です。デバイス特性を評価するデータバインディングの式を作成する際は、viewport特性で細かく設定するのではなく、viewportプロファイルパッケージに含まれているviewportプロファイルを使用します。

たとえば、各APLコンポーネントにはブール型のwhenプロパティがあります。whenプロパティがtrueのとき、Alexaはviewportにコンポーネントを表示します。whenプロパティがfalseのとき、Alexaはコンポーネントをスキップし、viewportに表示しません。

たとえば、コンポーネントを大きなデバイスに表示する場合は、次のようなステートメントを作成します。

"when": "${@viewportProfile == @hubLandscapeLarge}"

次のように幅を指定しないでください。

"when": ${viewport.width == "1280dp"}

2番目のステートメントは対象デバイスが限られており、レスポンシブ対応ではありません。別の同様のデバイスが1030dpのワイドスクリーンで利用できるようになると、このviewport.width条件のコンポーネントは表示されなくなります。対照的に、hubLandscapeLargeには幅1280～1920dpの画面を含むため、この条件は新しい未知のデバイスでも機能します。viewportプロファイル向けのロジックを作成すると、一度で複数の類似デバイスに対応できるようになります。特定のデバイスやviewport特性に応じて細かく設定する必要はありません。

viewport.shapeなど、単一の下位レベルのデバイス特性についても同様の問題が発生する可能性があります。${viewport.shape == 'round'}の式を例に挙げてみましょう。サイズに関係なく円形の画面を搭載するデバイスで、この式はtrueと評価されます。この式を使用して小さな円形のデバイス（Echo Spotなど）のコンテンツを扱う場合、大型の円形画面を備えた新しいデバイスが利用可能になると、スキルが期待どおりに機能しなくなるおそれがあります。${viewport.shape == 'round'}などの式を使用するのは、任意のサイズの円形の画面でのみコンポーネントを表示する場合にとどめてください。

最後に、viewportプロファイル全体ではなくサイズに基づいて条件を作成する必要がある場合は、viewportプロファイルパッケージでも定義されているサイズリソースを使用します。次に例を示します：

"when": "${viewport.width == @viewportSizeMedium}"

高さと幅をグループ化するサイズクラスを使用することもできます。

"when": "${@viewportSizeClass == @viewportClassMediumLarge}"

viewportプロファイルの場合と同様、サイズリソースは範囲と関係なく機能します。さまざまなデバイスが同じviewportSizeMediumサイズに分類される可能性があります。

条件付きロジックをドキュメントに組み込む

実行時にスキルコードに機能を分岐させるのではなく、条件付きロジックをAPLドキュメントに組み込みます。前述のviewportプロファイルと、データバインディングコンテキストのViewportオブジェクトのプロパティを使用して、条件付きロジックを作成します。

viewportに関する情報は、スキルリクエストのViewportオブジェクトのスキルコードでも使用できます。ただし、ドキュメントではなくロジックをコードに配置する場合は、デメリットがあります。

  • リクエストのViewportオブジェクトには、幅や高さなどの下位レベルのviewport特性が含まれます。前述したviewportプロファイルと同じ効果を得るには、下位のデータからプロファイルを計算する関数を記述する必要があります。
  • 一部のデバイスでは、使用中にviewportの特性が変わる可能性があります。このアクションにより、APLドキュメントのonConfigChangeハンドラーが呼び出されますが、新しいリクエストがスキルに送信されることはありません。たとえば、ユーザーはタブレットを横長から縦長に切り替えることができます。ドキュメントに条件を組み込んだスキルは、新しいviewportに合うようにドキュメントを再インフレートしてレイアウトを調整することができます。コードでロジックを使うスキルは、この状況に対応できません。
  • オーサリングツールでのテストと実験が難しくなります。ロジックをドキュメントに組み込むと、ドキュメントをオーサリングツールにアップロードしてそれぞれのviewportをクリックすることで、表示方法を確認したり変更を試したりできます。しかし、ロジックをコードに組み込むと（別々のドキュメントを全体的に管理し、実行時にいずれかを選択するなど）、オーサリングツールでドキュメント全体を切り替えて、さまざまなviewportでの表示方法を確認しなければなりません。

ドキュメントをモジュール化する

APLは、モジュール化ドキュメントをサポートしています。たとえば、alexa-layoutsパッケージのレスポンシブ対応コンポーネントは、APLコンポーネントと条件付きロジックを、ドキュメントに配置可能な1つの構成要素に統合します。これら別々の構成要素をさまざまな方法で組み合わせることで、ドキュメントを完成させることができます。

提供されているコンポーネントがニーズに合わない場合は、独自のレスポンシブ対応コンポーネントを作成することで、同じアプローチを取ることができます。カスタムコンポーネントをAPLドキュメントのlayoutsプロパティに追加します。次に、APLコンポーネントとレスポンシブ対応コンポーネントを使用する場合と同様に、mainTemplateでカスタムコンポーネントを使用します。

カスタムコンポーネントを作成すると、コンポーネントの外観、機能、レスポンシブ対応を1か所にカプセル化して、簡単に把握したり管理したりできるようになります。

たとえば、単純な「豆知識スキル」では、関連する背景画像やキャプションと共に、関連する豆知識を表示するドキュメントをレンダリングします。豆知識のテキストは長いため、小さな円形のデバイスでは非表示にして、画像のキャプションのみを表示することをお勧めします。viewportサイズに応じてキャプションの表示／非表示を行うFactTextAndCaptionBlockレイアウトを作成できます。その後、そのレイアウトとAlexaBackgroundレスポンシブ対応コンポーネントを配置します。

以下の例では、カスタムレイアウトの定義が設定されたlayoutsプロパティと、キャプションテキストの書式を設定するカスタムスタイルを示しています。

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

{
  "styles": {
    "mainFactText": {
      "description": "表示するメインテキストの視覚プロパティです。",
      "values": [
        {
          "textAlign": "center",
          "textAlignVertical": "center",
          "fontSize": "@fontSizeLarge"
        }
      ]
    },
    "captionText": {
      "description": "赤字の斜体キャプションのスタイルです。",
      "extends": "mainFactText",
      "values": [
        {
          "color": "red",
          "fontStyle": "italic",
          "fontSize": "@fontSizeMedium"
        }
      ]
    }
  },
  "layouts": {
    "FactTextAndCaptionBlock": {
      "description": "豆知識のテキストを表示し、その後に画像に関連するキャプションを付けます。小さな円形のデバイスにキャプションのみを表示します。",
      "parameters": [
        "factText",
        "imageCaption"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "justifyContent": "center",
          "grow": 1,
          "items": [
            {
              "type": "Text",
              "when": "${@viewportProfile != @hubRoundSmall}",
              "paddingLeft": "@spacingLarge",
              "paddingRight": "@spacingLarge",
              "text": "${factText}",
              "style": "mainFactText"
            },
            {
              "type": "AlexaDivider",
              "when": "${@viewportProfile != @hubRoundSmall}",
              "width": "50%",
              "alignSelf": "center",
              "paddingTop": "@spacingSmall",
              "paddingBottom": "@spacingSmall"
            },
            {
              "type": "Text",
              "paddingLeft": "@spacingSmall",
              "paddingRight": "@spacingSmall",
              "text": "Image: ${imageCaption}",
              "style": "captionText"
            }
          ]
        }
      ]
    }
  }
}

このコードがあれば、mainTemplateには、AlexaBackgroundとFactTextAndCaptionBlockを持つContainerを指定するだけで済みます。

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

{
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100vw",
        "height": "100vh",
        "items": [
          {
            "type": "AlexaBackground",
            "backgroundImageSource": "https://d2o906d8ln7ui1.cloudfront.net/images/BT1_Background.png",
            "colorOverlay": "true"
          },
          {
            "type": "FactTextAndCaptionBlock",
            "factText": "これは豆知識のテキストです。テキストを適切に表示できるだけの十分な大きさの画面があるデバイスに表示されるようにします。スキルでは応答でこのテキストを読み上げるので、小さすぎるデバイスには表示しなくても構いません。",
            "imageCaption": "これは、背景画像に関する簡潔なキャプションです。"
          }
        ]
      }
    ]
  }
}

レスポンシブ対応のAPLドキュメントをテストする

スキルを作成したら、さまざまなviewportで表示をテストします。実際のデバイスでテストすることをお勧めしますが、テストページでオーサリングツールまたはシミュレーターを使用することもできます。

  • オーサリングツールを使用して、作成したドキュメントを確認します。アカウントを登録したデバイスをお持ちの場合は、作成したドキュメントを対象のデバイスに送信できます。
  • テストページで、スキルコード、音声入力、Alexaの応答を使用してドキュメントをテストします。ExecuteCommandsディレクティブを使用して実行したコマンドをテストするには、ランタイムコード（Lambda関数など）をテストする必要もあります。

オーサリングツールとシミュレーターの両方で、さまざまなviewportを使ってテストできます。また、カスタムviewportを作成すると、使用予定のデバイスでのスキルの外観を確認できます。

これらのツールの使い方について詳しくは、以下のトピックを参照してください。

スキルでサポートするviewportプロファイルを選択する

ドキュメントをレスポンシブ対応にして、さまざまなデバイスで正常に表示されることを確認したら、ビルド＞カスタム＞インターフェースページに戻ります。スキルがすべてのviewportプロファイルをサポートするよう選択したことを確認してください。Alexaはドキュメントを表示する前にサポートの有無を確認するため、この選択は重要です。サポートされるプロファイルのいずれにもデバイスが一致しない場合、コンテンツは画面に合わせてサイズ調整されます。

こうしたスケーリングは最後の手段として検討する必要があります。ドキュメントがレスポンシブ対応であれば、スケーリングは必要ありません。

サポートされるプロファイルとサイズ調整のしくみについて詳しくは、スキルでサポートするViewportプロファイルを選択するを参照してください。

このページは役に立ちましたか？

最終更新日: 2023 年 11 月 15 日