APL Resources(1.4)



APL Resources

resourcesとは、データバインディングと値の解決によりアクセスできる名前付きエンティティです。resourcesは、APLのドキュメントおよびパッケージ内のリソースブロックで定義します。viewportパラメーターに応じて、条件付きで定義することも可能です。

resourcesの評価は、APLのドキュメントおよびパッケージの読み込み時に行われます。コンポーネントのインフレート時には、resourcesは静的であり、変更されることはありません。

resources定義のサンプル

次の例は、リソース定義を示しています。

{
  "type": "APL",
  "resources": [
    {
      "colors": {
        "accent": "#00CAFF",
        "myBlue": "#66DFFF"
      },
      "dimension": {
        "leftRight": "72dp"
      },
      "string": {
        "logo": "images/logo200x200.png"
      }
    },
    {
      "when": "${viewport.shape == 'round'}",
      "dimension": {
        "leftRight": "${viewport.width * 0.25}"
      }
    },
    {
      "when": "${viewport.theme == 'light'}",
      "colors": {
        "accent": "#0070BA",
        "myBlue": "#005A95"
      }
    },
    {
      "description": "大画面では大きな画像を使用する",
      "when": "${viewport.width > 1200}",
      "string": {
        "logo": "images/logo300x300.png"
      }
    }
  ]
}

この例では、themelightdarkかによって、colorの値をaccentmyBlueから選択しています。また、通常の場合はleftRightディメンションを72に設定しますが、画面形状がroundの場合には、画面の幅の25%(dp単位)に設定します。

resourcesの定義はブロック内で行います。このブロックはオブジェクトであり、オプションでwhen句と複数の型を設定できます。

プロパティ

resourcesの各ブロックのプロパティは以下のとおりです。

プロパティ 必須 説明
boolean, booleans ブール値のマップ ブールの名前をブール値にマッピングします。
color, colors 色のマップ 色の名前を色の値にマッピングします。
description 文字列 リソースブロックの説明です。
dimension, dimensions ディメンションのマップ ディメンション名をディメンション値にマッピングします。
easing, easings イージングのマップ 名前をイージング関数の定義にマッピングします。
gradient, gradients グラデーションのマップ グラデーション名をグラデーション定義にマッピングします。
number, numbers 数値のマップ 名前を数値にマッピングします。
string, strings 文字列の配列 名前を文字列にマッピングします。
when ブール値 trueの場合、このresourceブロックが適用されます。デフォルトはtrueです。

resourceブロックは配列順に処理され、前の定義は後の定義で上書きされます。

resourceの定義では、@name構文を使用することで、前のブロックで定義されているresourceを参照できます。

resourceブロックは、他のresourceブロックの中に入れ子にできます。たとえば、次のようにします。

{
  "resources": [
    {
      "dimensions": {
        "myFontSize": "28dp",
        "myLeftRightPadding": "60dp"
      }
    },
    {
      "when": "${viewport.shape == 'round'}",
      "resources": [
        {
          "dimensions": {
            "myFontSize": "30dp",
            "myLeftRightPadding": "80dp"
          }
        },
        {
          "when": "${viewport.width < 400}",
          "dimensions": {
            "myFontSize": "20dp",
            "myLeftRightPadding": "45dp"
          }
        }
      ]
    }
  ]
}

boolean, booleans

ブール型リソースは、trueまたはfalseの値です。ブール型以外をブール型リソースに割り当てると、「truthy」ルールにより変換されます。詳細については、Truthyと強制を参照してください。

"boolean": {
  "bool1": true,       // true
  "bool2": 23.4,       // true
  "bool3": "hello!",   // true
  "bool4": false,      // false
  "bool5": 0,          // false
  "bool6": ""          // false
}

color, colors

色値は、32ビットのRGBA値の色として格納されています。色に変換される文字列式の記述方法については、を参照してください。一般的な強制ルールについては、色の強制を参照してください。

"colors": {
  "myRed1": "#ff0000ff",    // 通常の赤
  "myRed2": "#ff0000",      // 短縮バージョン(透明度を省略)
  "myRed3": "#f00",         // 超短縮バージョン(R、G、Bの2桁分を1桁で表現)
  "myRed4": "red",          // ビルトインの色名を使用
  "myRed5": "rgb(255,0,0)", // RGB関数
  “myRed6”: 4278190335      // 非推奨:0xff0000ffの16進数
}

dimension, dimensions

ディメンションリソースには、絶対ディメンション、相対ディメンション、または特殊ディメンションが格納されます。ディメンションの種類の詳細についてはディメンションを参照してください。他の型がディメンションに変換される方法の詳細については、絶対ディメンションの強制を参照してください。

"dimensions": {
  "myDim1": "150dp",  // 150 dp
  "myDim2": "300px",  // 320 dpiの画面では150 dp。
  "myDim3": “100vw”、// 160dpiの画面(幅1024px)では1024dp。
  "myDim4": “50vh”、// 160dpiの画面(高さ800px)では400dp。
  "myDim5": "50",     // 50 dp
  "myDim6": "50%",    // 50%(相対ディメンション)
  "myDim7": "auto"    // auto(特殊ディメンション)
}

easing, easings

イージング関数は、従来、アニメーション化されたプロパティの時間経過による変化を定義するために使用されていた一価関数です。イージング関数の詳細については、イージング関数を参照してください。

gradient, gradients

グラデーションは、グラデーションのルールに従って定義されます。

number, numbers

数値リソースは、内部的に倍精度浮動小数点数値として格納されます。数値以外の値が数値に変換される方法については、数値の強制を参照してください。

"numbers": {
  "myNum1": null,       // 0
  "myNum2": false,      // 0
  "myNum3": true,       // 1
  "myNum4": "@myDim1",  // 150(上記のディメンション定義による)
  "myNum5": "@myDim6"   // 0.5(上記のディメンション定義による)
}

string, strings

文字列値は文字列として格納されます。他の型は文字列に変換できます。文字列変換ルールについては、文字列の強制を参照してください。

"strings": {
   "string1": null,          // ""
   "string2": "",            // ""
   "string3": false,         // "false"
   "string4": 23,            // "23"
   "string5": "${@myRed1}",  // "#ff0000ff"(上記の色の定義による)
   "string6": "${@myDim1}",  // "150dp"(上記のディメンション定義による)
   "string7": "${@myDim6}",  // "50%"(上記のディメンション定義による)
}