APLレイアウト

APLレイアウト

Alexa Presentation Language（APL）レイアウトは、コンポーネントとほかのレイアウトを組み合わせて、再利用可能な「カスタムコンポーネント」を作成します。プログラミング言語の関数が引数を受け取って特定のタスクを実行する自己完結型のコードモジュールであるのと同様に、レイアウトは引数を受け取って特定のビジュアル要素をレンダリングできる自己完結型のAPLコードのモジュールです。

各種コンポーネントを現在のデータバインディングコンテキストに応じてインフレートできるため、APLレイアウトのインフレートは条件付きで行われます。

レイアウトについて

レイアウトは、APLドキュメントまたはパッケージのlayoutsプロパティで定義します。このプロパティの引数は文字列とオブジェクトのマッピングです。レイアウト定義には、parametersの配列を含めることができます。レイアウトを使用する場合、これらのパラメーターに引数を渡すことができます。たとえば、境界線のあるボックス内にテキストを表示するレイアウトでは、パラメーターを使用して、表示するテキストと境界線の色を指定できます。

たとえば、titleとlogoという2つのパラメーターを受け取るHeaderLayoutExampleレイアウトがあるとします。レイアウト内で、Textコンポーネントはtitleパラメーターに指定された値を使用し、Imageコンポーネントはlogoパラメーターに指定された値を使用します。

円形のViewportの場合、HeaderLayoutExampleレイアウトは列方向のContainerにインフレートされ、タイトルの前にロゴが配置されます。長方形のViewportの場合、このレイアウトは行方向のContainerにインフレートされ、同じ行のタイトルの後にロゴが配置されます。

以下は、HeaderLayoutExampleのAPLコードの例です。

{
  "HeaderLayoutExample": {
    "description": "タイトルとロゴ付きの基本的なヘッダー",
    "parameters": [
      {
        "name": "title",
        "type": "string",
        "default": "表示するタイトルを入力してください"
      },
      {
        "name": "logo",
        "type": "string"
      }
    ],
    "items": [
      {
        "when": "${viewport.shape == 'round'}",
        "type": "Container",
        "direction": "column",
        "alignItems": "center",
        "padding": [64,48],
        "items": [
          {
            "type": "Image",
            "source": "${logo}",
            "height": 50,
            "width": 50
          },
          {
            "type": "Text",
            "text": "${title}",
            "style": "textStylePrimary"
          }
        ]
      },
      {
        "type": "Container",
        "direction": "row",
        "padding": [64,32],
        "width": "100%",
        "justifyContent": "spaceBetween",
        "items": [
          {
            "type": "Text",
            "text": "${title}",
            "width": "90%",
            "style": "textStylePrimary"
          },
          {
            "type": "Image",
            "source": "${logo}",
            "height": 50,
            "width": 50
          }
        ]
      }
    ]
  }
}

ドキュメントでレイアウトを呼び出すには、コンポーネントのtypeにレイアウト名を使用して、パラメーターを渡します。以下は、HeaderLayoutExampleレイアウトを呼び出す方法の例です。

{
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "HeaderLayoutExample",
        "title": "これはタイトルに使用するテキストです",
        "logo": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png"
      }
    ]
  }
}

次のAPLドキュメントでは、HeaderLayoutExampleレイアウトを定義してViewportに表示しています。

レイアウトのプロパティ

レイアウトオブジェクトには次の表のプロパティがあります。

プロパティ 型 必須 説明

bind

バインドの配列

×

データバインディングコンテキストに追加する式です。

description

文字列

×

このレイアウトの説明を指定します。

item、items

コンポーネントの配列

◯

インフレートするコンポーネントです。itemsに配列が含まれる場合、レイアウトはwhen条件がtrueになった最初のコンポーネントをインフレートします。

parameters

パラメーターの配列

×

このレイアウトに渡すことができるパラメーターの配列です。

bind

コンポーネントのbindプロパティは、ローカルのバインド変数を使用して、コンポーネントとその子のデータバインディングコンテキストを拡張します。バインド変数の詳細については、APLバインド変数を参照してください。

item、items

itemプロパティには単一のコンポーネントを、itemsプロパティにはコンポーネントの配列を指定します。ほかのレイアウトも、layoutsオブジェクトに既にインポート済みまたは定義済みであれば、itemsに含めることができます。APLデータバインディングの評価を参照してください。

itemsに配列が含まれる場合、レイアウトはwhen条件がtrueになった最初のコンポーネントをインフレートします。

parameters

parametersは、呼び出し時にレイアウトに渡すことができる名前付きの値のことです。各パラメーターは、以下の表のプロパティを持つオブジェクトです。

プロパティ 型 必須 説明

default

任意

×

パラメーターを指定しない場合に適用するデフォルト値です。デフォルトは空白です。

description

文字列

×

このパラメーターの用途について説明する任意の詳細です。

name

文字列／その他

◯

一意のパラメーター名です。名前には、大文字または小文字の英字で始まり、スペースを含まない名前を設定します。

type

型

×

パラメーターの型です。デフォルトはanyです。有効な値は、any、array、boolean、color、component、dimension、integer、map、number、object、stringです。

手間を省くため、パラメーターオブジェクトの代わりに単一のパラメーター名を使用できます。たとえば、{ "name": "title", ... }の代わりに、titleだけを定義します。これにより、パラメーターに渡す値にデフォルト値や型の強制が不要になるため、コードを簡素化できます。明確に定義するには、完全なパラメーターオブジェクトを使用することをお勧めします。

レイアウトのインフレート

APLは、次のアルゴリズムに従ってレイアウトをインフレートします。

  1. 各parameterを評価し、データバインディングコンテキストに追加します。
  2. 1つの子のみのインフレートアルゴリズムを使ってitemまたはitemsプロパティを評価します。
  3. レイアウトには割り当てられているが、名前付きパラメーター、項目、型に一致しないプロパティを、評価のために項目に渡します。

たとえば、次のコードは、横長のViewportとそれ以外のViewportでテキストの表示が異なるレイアウトを定義しています。

"myLayout": {
  "parameters": [
    "title",
    "subtitle"
  ],
  "item": [
    {
      "when": "${viewport.width > viewport.height}",
      "type": "Text",
      "text": "<b>${title}:</b> ${subtitle}",
      "style": "textStyleDisplay1"
    },
    {
      "type": "Text",
      "text": "<b>${title}</b><br>${subtitle}",
      "style": "textStyleDisplay2"
    }
  ]
}

次の例では、このレイアウトを呼び出して、title、subtitle、colorの3つのパラメーターを渡します。colorパラメーターは、myLayoutのプロパティとして指定されていません。

{
	"type": "myLayout",
	"title": "フランケンシュタイン",
	"subtitle": "あるいは現代のプロメテウス",
	"color": "green"
}

ユーザーのデバイス画面が横長である場合を考えてみます。インフレーションロジックは以下を行います。

  1. titleとsubtitleのパラメーターをデータバインディングコンテキストに追加します。
  2. itemプロパティを評価し、when条件がtrueに評価された最初のコンポーネントを探します。ユーザーのデバイス画面は横長のため、APLはitems配列のfirstのコンポーネントを選択します。
  3. 追加のプロパティがあれば、すべて選択したitemに渡します。この例では、colorプロパティをレイアウトに渡します。このプロパティは、myLayoutに定義されたプロパティのいずれとも一致していません。このため、このプロパティを選択された項目に渡します。

最終的には、次のようなTextコンポーネントになります。

{
	"type": "Text",
	"text": "<b>フランケンシュタイン</b>：あるいは現代のプロメテウス",
	"style": "textStyleDisplay1",
	"color": "green"
}

次のAPLドキュメントでは、myLayoutのサンプルを定義して表示しています。colorはTextコンポーネントの有効なプロパティであるため、Textコンポーネントはスタイルで定義されたcolorプロパティをオーバーライドし、緑色のテキストを表示します。"color": "green"行を削除すると、テキストの色がtextStyleDisplayスタイルで定義されている色に戻ることを確認できます。

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

最終更新日: 2025 年 11 月 11 日