APLレイアウト



APLレイアウト

APLレイアウトは名前付きの複合コンポーネントであり、APLドキュメントまたはパッケージで定義されています。APLのレイアウトは、別の名前付きレイアウトやプリミティブコンポーネントのコレクションに展開(インフレート)される関数のようなものです。APLレイアウトでは、parameters配列内で引数を渡すことができます。各種コンポーネントを現在のデータバインディングコンテキストに応じてインフレートできるため、APLレイアウトのインフレートは条件付きで行われます。

レイアウトのサンプル

次の例では、Headerレイアウトでtitlelogoの2つのパラメーターを受け取ります。titleパラメーターはTextコンポーネントに、logoパラメーターはImageに渡されます。円形のviewportの場合、Headerコンポーネントは列方向のContainerにインフレートされ、タイトルの上にロゴが配置されます。長方形のviewportの場合、ロゴはタイトルの右側に配置されます。

{
  "Header": {
    "description": "タイトルとロゴ付きの基本的なヘッダー",
    "parameters": [
      {
        "name": "title",
        "type": "string"
      },
      {
        "name": "logo",
        "type": "string",
        "default": "http://images.amazon.com/default_logo.png"
      }
    ],
    "items": [
      {
        "when": "${viewport.shape == 'round'}",
        "type": "Container",
        "direction": "column",
        "items": [
          {
            "type": "Image",
            "source": "${logo}",
            "height": 36,
            "width": 36
          },
          {
            "type": "Text",
            "text": "${title}",
            "style": "textStylePrimary2"
          }
        ]
      },
      {
        "type": "Container",
        "direction": "row",
        "paddingLeft": 20,
        "items": [
          {
            "type": "Text",
            "text": "${title}",
            "style": "textStyleSecondary2"
          },
          {
            "type": "Image",
            "source": "${logo}",
            "height": 40,
            "width": 40
          }
        ]
      }
    ]
  }
}

プロパティ

プロパティ 必須 説明
description 文字列 このレイアウトの説明です。
item コンポーネント: プロパティ インフレートするコンポーネントです。配列を渡した場合、一致するwhen句のある最初の項目がインフレートされます。
parameters パラメーターの配列 このレイアウトに渡すことができるパラメーターのリストです。

item/items

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

parameters

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

プロパティ 必須 説明
default 任意 パラメーターを指定しない場合に適用するデフォルト値です。デフォルトは空白です。
description 文字列 このパラメーターの用途について、ユーザーが指定する説明です。
name 文字列 パラメーターの名前です。
type パラメーターの型です。デフォルトは「any」です。

パラメーターのtypeは文字列であり、そのパラメーターに入力できる値の型を定義します。次のいずれかになります。

  • any
  • array
  • boolean
  • color
  • component
  • dimension
  • integer
  • map
  • number
  • object
  • string

パラメーターの名前には、大文字または小文字の英字から始まる一意の名前を指定する必要があります。空白を含めることはできません。

手間を省くため、パラメーターオブジェクトの代わりに単一のパラメーター名を使用できます({ "name": "title", ... }の代わりに"title"など)。この形式は非推奨ですが、強制型変換やデフォルト値が不要な場合に用いることで、レイアウトの定義を手短に行うことができます。

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

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

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

次のようなレイアウト定義を例に説明します。

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

このレイアウトを、以下を使用して呼び出すとします。

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

インフレートロジックは以下のとおりです。

まず、「title」パラメーターと「subtitle」パラメーターがデータバインディングコンテキストに追加されます。

次に、itemプロパティが評価されます。このコードが横向きの画面で実行される場合、item配列の最初のコンポーネントが選択されます。

最後に、元の呼び出しに含まれるその他のプロパティがコンポーネントに渡されます。この場合は、colorプロパティが渡されます。最終結果として、(データバインディングの後に)次のようなTextコンポーネントが作成されます。

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