APLスタイルの定義と評価(1.0)
(これはAPLの最新バージョンではありません。APLの最新バージョンの資料を参照するには、その他のバージョンオプションをクリックしてください)
スタイルとは、一連の視覚プロパティを定義する名前付きエンティティのことです。スタイルを使用すると、コンポーネントのプロパティを一貫して設定できます。スタイルでは、条件付きロジックを含めたり、コンポーネントの状態を使用したりできます。たとえば、コンポーネントの状態がchecked
に設定されているかどうかに応じて、スタイルでテキストの色を変更できます。
スタイルの定義
スタイルの定義では、スタイルの名前、継承元となる1つまたは複数の親スタイルのリスト、条件付きで適用されるプロパティ定義の順序付きリストを指定します。Textコンポーネントでの使用に適した「title」というスタイル定義を以下に示します。ここでは、フォントのサイズと色が設定されています。色は、Textコンポーネントの状態と現在のテーマに応じて変更されます。
"styles": {
"baseText": {
"values": [
{
"fontFamily": "Amazon Ember",
"color": "${viewport.theme == 'dark' ? 'white' : 'black' }"
},
{
"when": "${state.karaoke}",
"color": "blue"
}
]
},
"title": {
"extends": "baseText",
"values": [
{
"fontWeight": 700,
"fontSize": "${viewport.height > 400 ? 30 : 25}"
}
]
}
}
たとえば、viewportが大型、ダークテーマ、状態がfocusedに設定されているデバイスの場合、スタイルtitle
の評価結果は次のようになります。
{
"fontFamily": "Amazon Ember Display",
"color": "blue",
"fontWeight": 700,
"fontSize": 30
}
スタイルでは、すべてのコンポーネントプロパティを設定できるわけではありません。すべてのコンポーネントのスタイル設定可能プロパティについては、スタイル設定可能プロパティを参照してください。個々のコンポーネントについては、利用可能なコンポーネントプロパティの表を参照してください。該当するコンポーネントのプロパティのうち、スタイルで設定可能なものについては、表の「スタイル設定」列に「〇」が記載されています。たとえばTextプロパティの表では、
text
以外のすべてのプロパティがスタイル設定可能です。定義のプロパティ
スタイルの定義ごとに、次のプロパティがあります。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
description | 文字列 | ✕ | このスタイルの説明です。 |
extend | スタイル名の配列 | ✕ | このスタイルの継承元となるスタイルを一覧にしたものです。順序が後の項目が、順序が先の項目を上書きするため、順序が重要です。 |
values | valueオブジェクトの配列 | ✕ | オブジェクトの配列です。 |
extend
配列には、このスタイルの継承元となるスタイルが順番に並んだ一覧が含まれます。access
プロパティは、定義パッケージ以外でこのスタイルを使用できるかどうかを制御します。
values
配列には、適用するvalueオブジェクトが順番に並んだ一覧が含まれます。各value
オブジェクトは、次の形式になります。
{
"when": EXPRESSION,
NAME: VALUE,
NAME: VALUE,
:
}
when
プロパティはオプションであり、定義されていない場合のデフォルト値はtrue
です。定義されたプロパティは、有効なスタイル設定可能プロパティの名前である必要があります(無効な名前は無視されます)。when
句のデータバインディングコンテキストには、ドキュメントまたは読み込まれたパッケージの中に以前に表示されたviewport、環境、リソース定義、スタイルが含まれます。
スタイルの評価
コンポーネントの評価
個々のコンポーネントには状態があります。次の状態プロパティが定義されています。
プロパティ | 定義 |
---|---|
checked |
コンポーネントがチェックされているか、オンになっています。 |
disabled |
コンポーネントが無効になっています(多くのコンポーネントに「disabled」プロパティがあります)。 |
focused |
コンポーネントがキーボード入力でフォーカスされた状態になっています。 |
karaoke |
音声発話時に使用します。 |
pressed |
マウスまたはタッチパネルによる入力がアクティブになっています。 |
コンポーネントの状態はコンポーネントの作成時に設定され、ユーザーが画面に触れたり、キーボードやコマンドを使用したりするなどの操作に応じて変化します。たとえば、TouchWrapperコンポーネントは、押された状態を設定すると、タッチやキーボードによるイベントに反応します。コンポーネントの状態とスタイルの組み合わせにより、コンポーネントの外観を変更します。
コンポーネントの状態を変更しても、inheritParentState
プロパティを設定しない限り、子コンポーネントの状態は変更されません。Textコンポーネントの例は以下のとおりで、押されると色が変わります。
スタイルの定義:
"textStylePressable": {
"values": [
{
"color": "white"
},
{
"when": "${state.pressed}",
"color": "green"
}
]
}
レイアウトでのスタイルの使用:
{
"type": "TouchWrapper",
"item": {
"type": "Text",
"inheritParentState": true,
"style": "textStylePressable",
"text": "Push Me!"
}
}
スタイルの評価
各コンポーネントは、名前付きのスタイルを明示的または非明示的に参照します(デバイスのランタイムには、コンポーネントごとにデフォルトのスタイルがあります)。スタイルの評価は、限定されたデータバインディングのコンテキストで発生し、viewport
、state
、およびresource
の定義のみを使用します。
スタイルの計算結果は、viewport
、resource
、state
の相関関係で表されます。計算アルゴリズムは、おおよそ次の擬似コードに相当します。
function _calcInternal(style, context):
result = {};
// extend配列のチェック
foreach style.extend as name:
result += _calcInternal( getStyleByName(name), context)
// values配列のチェック
foreach values as value:
if evaluate(value.when):
result += evaluateEach(value)
return result
function calculateStyle(style, context, state):
workingContext = extendContext(context, { state: state })
return _calcInternal(style, workingContext)
最初にextend
配列、次にvalues
のブロックを(順番に)計算します。