APLスタイルの定義と評価（1.0）

APLスタイルの定義と評価

（これは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のブロックを（順番に）計算します。