APLのデータ型

APLのデータ型

APLは、データ型のセットをサポートしています。これらのデータ型は、APLドキュメントでプロパティ値を設定するときに使用できます。このドキュメントでは、APLの最新バージョンのAPLデータ型について説明します。

ディメンション

APLのディメンションは、 絶対、相対、特殊ディメンションという3種類で表現できます。

絶対ディメンション

絶対ディメンションは数値のみであり、画面非依存のピクセル数として解釈されます。絶対ディメンションは単位サフィックスが付いた文字列として表現することもできます。単位サフィックスはディメンションの直後に配置される必要があります。下記のようなサフィックスが有効です。

サフィックス 説明 例
dp 画面非依存のピクセル数 20dp
px 画面のピクセル数 10px
vh viewportの高さ（最大値は100）。1vhはviewportの高さの1%です。 50vh
vw viewportの幅（最大値は100）。1vwはviewportの幅の1%です。 33vw

相対ディメンション

相対ディメンションは「X%」形式の文字列として指定します。Xは、有効なJSON数値です。このパーセント値は、データが含まれるコンポーネントのバウンディングボックスに対する割合と解釈されます。バウンディングボックスには、2つのディメンション（幅と高さ）があるため、本質的に水平方向または垂直方向を意味するプロパティ（heightなど）の場合は、適切なディメンションが選択されます。明確な方向が設定されていないプロパティ（borderRadiusTopRightなど）の場合は、バウンディングボックスの幅に対する割合が使用されます。

相対ディメンションは、すべてのコンポーネントのパディングプロパティでサポートされているわけではありません。

相対ディメンションを使用すると依存関係ループが発生し、結果が不確定になる可能性があることに注意してください。たとえば、親Containerのサイズにautoを設定し、子の高さを「50%」に設定した場合、結果は不確定になります。

特殊ディメンション

特殊ディメンションは、特別な処理が設定された名前付きの値です。現在定義されている特殊ディメンションは「auto」のみです。このディメンションでは、コンポーネントのサイズは自然なサイズと等しくなります。たとえば、幅と高さを「auto」に設定したTextコンポーネントは、このテキストが含まれるバウンディングボックスに1行で配置されます。

特殊ディメンションは、Imageコンポーネントのパディングプロパティではサポートされていません。

色

色の値は文字列で指定し、有効なR、G、B、Aタプルへ内部的に変換されます。文法規則は次のとおりです。

color         ::= _ <<基調色>> _
<<基調色>> ::= <<16進数>> | <<関数>> "(" _ <<引数>> _ ")" | <<シンボル>>
<<16進数>>       ::= "#" [0-9a-fA-F]{3,4,6,8}
<<シンボル>>    ::= [a-zA-Z]+
<<関数>>  ::= "rgb" "a"? | "hsl" "a"?
<<引数>>      ::= <<引数>> ( "," _ ARG )*
<<引数>>       ::= <<基調色>> | <<パーセント値>> | <<数値>>
<<パーセント値>>   ::= <<数値>> "%"
<<数値>>    ::= [0-9]+ "." [0-9]* | "." [0-9]+ | [0-9]+
_             ::= [ \t\n\r]*

標準色

標準色では、HTML標準の色を名前指定で参照します。たとえば、「azure」、「burlywood」、「red」などです。

16進数色

色は、#から始まる16進数の文字列として定義することもできます。この文字列は、以下の形式で指定できます。

  • #RGB
  • #RGBA
  • #RRGGBB
  • #RRGGBBAA

rgb／rgba関数

色は、rgb()関数またはrgba()関数として定義することもできます（後者の関数は、前者の別名です）。これらの関数の解釈は、引数の個数に応じて異なります。

  • 引数が2つの場合： 1番目の引数は色、2番目の引数はその色に適用するアルファ値であると判断されます。たとえば、rgba(red,0.2)は、不透明度20%のred色になります。

  • 引数が3つの場合： 引数はそれぞれR、G、Bと解釈されます（それぞれ0以上255以下の整数で指定します）。アルファ値は1.0に設定されます。たとえば、rgba(0,255,0)では、「#00FF00FF」と同じ色が得られます。

  • 引数が4つの場合： 引数はそれぞれR、G、B、Aと解釈されます。R／G／Bの各値は、0以上255以下の整数で指定します。Aの値は、0以上1以下の数値で指定します。

hsl／hsla関数

色は、hsl()関数またはhsla()関数として定義することもできます（後者の関数は、前者の別名です）。これらの関数の解釈は、引数の個数に応じて異なります。

  • 引数が3つの場合： H引数（色合）は、0以上360以下の整数で指定します。S引数（彩度）およびL引数（明度）は、0以上1以下の数値で指定します。A（アルファ）の値は1に設定されます。たとえば、hsl(0, 100%, 50%)は「red」になります。

  • 引数が4つの場合： H引数（色合）は、0以上360以下の整数で指定します。S引数（彩度）、L引数（明度）、A引数（アルファ値）は、0以上1以下の数値で指定します。たとえば、hsla(120, 1, .25, 25%)では、rgb(darkgreen, 0.25)と同じ色が得られます。

透明

色は、「transparent」キーワードとして定義することもできます。このキーワードは、rgba(0,0,0,0)に相当します。

データバインディングの参照

色の式をデータバインディング式の中で定義しないでください。たとえば、次の式は無効になります。

   "color": "${ rgba(0, 0, 255, 20%) }" //間違い

代わりに、計算またはリソース参照を行う文字列のみを評価するデータバインディングロジックを記述してください。

"color": "rgba(0,0,255,20%)" //正しい

グラデーション

グラデーションは、背景やオーバーレイに使用する陰影の付いた色のことです。たとえば、グラデーションレイヤーを画像に適用するには、ImageにoverlayGradientを設定します。

グラデーションは、次のプロパティを持つオブジェクトとして表されます。

プロパティ 型 デフォルト 説明
angle 数値 0 線形グラデーションの角度です。度で表されます。0が上方向で、90が右方向です。
colorRange 色（color）の配列 必須 各グラデーションの終了点に指定される色です。
description 文字列 "" このグラデーションの任意の説明です。
inputRange 数の配列 [] 入力のグラデーションの終了点です。0～1の値で、昇順である必要があります。
type linear、radial linear グラデーションの種類です。

たとえば、画像レイヤーのサンプル線形グラデーションは以下のようになります。

{
  "type": "linear",
  "colorRange": [
    "white",
    "transparent"
  ],
  "inputRange": [
    0,
    0.5
  ]
}

上の例では、グラデーションの一番下は白色になります。グラデーションは50%のところまで、透明まで線形に遷移し、残りの描画領域では透明のままになります。

angle

線形グラデーションの角度です。垂直から時計回りに度数で測定します。0が上、90が右、180が下、270が左になります。角度は任意の値を取りますが、実際の描画はmodulo 360です。

colorRange

各グラデーションの終了点に指定される色です。色は終了点の間で線形補間されます。

inputRange

inputRangeはグラデーションの終了点の位置を指定します。inputRangeが指定されていない場合、最初の色値はグラデーション終了点0、最後の色値はグラデーション終了点1、その他は0～1の間で均等に分散しています。

type

グラデーションには2種類あります。線形と放射です。線形グラデーションは、四角のうちの一角または一辺（角度によって異なる）から開始され、反対側の角または辺まで伸びます。放射グラデーションは常に中心に位置し、もっとも遠い一角が色の最終点になります。放射グラデーションは円形ではなく、周囲のコンテナの形状に応じて楕円形になります。

イージング関数

イージング関数は、数値の入力値（通常は時間）を数値の出力値にマッピングする、連続した単一値の数学関数です。コンピュータープログラミングでは「function」はより一般化された、異なる意味を持つため、このドキュメントでは「イージング関数」という用語を使います。

イージング関数はAnimateItemコマンドで使用され、単一プロパティの動きをアニメーション化する、カスタムの時間ベースのイージング曲線を定義します。次に例を示します。

{
  "type": "AnimateItem",
  "description": "コンポーネントをフェードアウト",
  "componentId": "TargetComponent",
  "duration": 1000,
  "easing": "cubic-bezier(0.5,0.1,1,1)"
  "value": {
    "property": "opacity",
    "to": 0
  }
}

イージング機能を使用して、時間ベースのアニメーションを作成することもできます。たとえば、フレームの背景を連続的に変更するには、次のようにします。

{
  "type": "APL",
  "version": "1.8",
  "resources": [
    {
      "easing": {
        "ease1": "line(0,0) line(500,255) end(1000,0)",
        "ease2": "line(0,255) line(500,255) line(700,0) end(800,255)"
      }
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "TouchWrapper",
      "items": {
        "type": "Frame",
        "width": "100%",
        "height": "100%",
        "bind": {
          "name": "t",
          "value": "${elapsedTime % 1000}"
        },
        "backgroundColor": "rgb(${@ease1(t)},${@ease2(t)},0)"
      }
    }
  }
}

このドキュメントは、慣例的にイージング関数の入力値をxとして参照します。出力値は、yと呼ばれるxの関数です。イージング関数の入力値は常に時間であると考えがちですが、これは誤りです。そのような要件はありません。イージング関数は連続した数学関数であり、使い方は自由です。

イージング文法は、3つの基本的な方法でイージング曲線を定義できます。

  • 単純イージング関数は、AnimateItemコマンドとともに使うようデザインされています。これらは、0~1の入力値を0~1の出力値にマッピングします。
  • 直線とベジェ曲線の区分イージング関数は、任意の入力値を任意の出力値にマッピングします。
  • 空間イージング関数は2次元または3次元で定義されたパスに沿って位置をマッピングします。

単純イージング関数

単純イージング関数は、AnimateItemコマンドとともに使うようデザインされています。イージング関数は常に(0,0)で始まり、(1,1)で終了します。イージングカーブの一般的な記述方法は、2つあります。

  • cubic-bezier(x1,y1,x2,y2)： CSS規格に従って、始点(0,0)と終点(1,0)を持つ3次ベジェ曲線を定義します。パラメーター化された値の(x1, y1)と(x2, y2)は、曲線の内部制御点を定義します。通常、0から1の間となります。関数は次のように定義されます。

    x(t) = 3*x1*t*(1-t)^2 + 3*x2*t^2*(1-t) + t^3
y(t) = 3*y1*t*(1-t)^2 + 3*y2*t^2*(1-t) + t^3

    3次ベジェは、tの関数としてxとyを定義します。y(x)を計算するために、xの入力値を使ってtを特定し、yの計算に使います。

  • path(x1,y1,...,xN,yN)： (0,0)から(1,1)までの区分線形関数です。x値は、昇順で0から1の間でなければなりません。y値は任意です。(0,0)と(1,1)の終了値は暗黙的に示されます。

以下のイージングカーブが事前定義されています。

名前 デフォルト値
linear path()
ease cubic-bezier(0.25, 0.10, 0.25, 1.00)
ease-in cubic-bezier(0.42, 0.00, 1.00, 1.00)
ease-out cubic-bezier(0.00, 0.00, 0.58, 1.00)
ease-in-out cubic-bezier(0.42, 0.00, 0.58, 1.00)

区分イージング関数

区分イージング関数は、任意の入力値を任意の出力値にマッピングします。区分イージング関数は、1次と3次の線分をつなぐことにより定義します。各線分は、開始座標を定義します。最後の線分は、終了座標を定義する「end」線分である必要があります。要素は次のようになります。

  • line(x,y): 座標(x, y)から始まる直線。直線は、次の線分の座標で終了します。tの関数として線形補間された値（tは0～1）は次のようになります。

    x(t) = x1(t) + (x2(t) - x1(t)) * t
y(t) = y1(t) + (y2(t) - y1(t)) * t

    これは、現在の座標(x1, y1)から次のセグメントの座標(x2, y2)までを補間します。

  • curve(x,y,a,b,c,d): 3次スプラインは、制御点a,b,c,dを使用する座標(x,y)から始まります。制御点の値は、0～1の間でなければなりません。tの関数として線形補間された値（tは0～1）は次のようになります。

    x(t) = x1(t) + (x2(t) - x1(t)) * f(a,c,t)
y(t) = y1(t) + (y2(t) - y1(t)) * f(b,d,t)
f(p1,p2,t) = 3*p1*t*(1-t)^2 + 3*p2*t^2*(1-t) + t^3

    これは、現在の座標(x1, y1)から次のセグメントの座標(x2, y2)までを補間します。

  • end(x,y): 最後の点です。

イージング関数は、開始点の前と終了点の後は「フラット」であるとみなされます。たとえば、終了点がend(10,100)の場合、10より大きなすべての入力値に対して100を返します。

空間イージング関数

空間イージング関数は、N次元（通常は2次か3次）の空間でコンポーネントがどのように移動するかを定義するのに有効です。空間曲線の各点には、時間と座標のタプルが含まれます。空間曲線の各曲線分には、曲線の形状を決める入力および出力の相対制御点があります。空間曲線に沿った距離は、各曲線分の3次イージング関数で定義されます。

本来、空間曲線は単一の入力値からN個の出力値にマッピングされます。イージング関数がサポートするのは1つの出力値のみのため、空間曲線の最初の要素がN個の出力値のどれを使うかを定義します。空間イージング曲線の要素は次のとおりです。

  • spatial(dof, index): dof（通常は2次または3次の自由度）で空間イージング関数の開始点を定義し、indexで出力値を選択します。
  • scurve(x, y+, tout+, tin+, a, b, c, d): 入力パラメーターxと空間座標y+の空間で開始する3次スプラインです。スプライン制御点のy+からの相対位置は、tout+値（タンジェントアウト）によって指定されます。スプラインの終点は、次の曲線分によって指定されます。スプライン制御点の次の曲線分からの相対位置は、tin+値（タンジェントイン）によって指定されます。制御点a-dは、開始値と終了値（次の曲線分によって指定される）の間でx値がどのように線形補間されるかを定義します。
  • send(x, y+): 空間イージング関数の最後の曲線分を定義します。

以下は、空間イージング関数の動作を表す例です。

{
  "type": "APL",
  "version": "1.8",
  "resources": {
    "strings": {
      "PATH": "scurve(0, 0,0, 100,0, 0,50, 0.2,0.0, 0.6,0.6)",
      "PATH2": "scurve(50, 100,100, 0,100, 0,50, 0.2,0.2, 0.6,0)",
      "PATH3": "send(1000, 0, 0)"
    },
    "easing": {
      "FX": "spatial(2,0) ${@PATH} ${@PATH2} ${@PATH3}",
      "FY": "spatial(2,1) ${@PATH} ${@PATH2} ${@PATH3}"
    }
  },
  "mainTemplate": {
    "items": {
      "type": "Frame",
      "width": 20,
      "height": 20,
      "backgroundColor": "red",
      "bind": {
        "name": "t",
        "value": "${elapsedTime % 1000}"
      },
      "transform": {
        "translateX": "${@FX(t)}",
        "translateY": "${@FY(t)}"
      }
    }
  }
}

この例では、小さな赤いボックス（フレーム）が(0,0)と(100,100)の間で連続アニメーション化されます。x座標に1つ、y座標に1つ、計2つのイージング関数が使われています。どちらのイージング関数にも同じ空間パスが使われており、適切な空間ヘッダーを使って関数からXとYの座標を取得しています。時間の線形補間の制御点は線状ではなく、赤いボックスは(0,0)からジャンプし、(100,100)に近づくにつれて減速して、(0,0)に近づくにつれて徐々に再加速し始めます。

イージング文法

イージングの文法は次のように定義されます。

easing          ::= predefined | path | cubicbezier | segmented | spatialcurve
predefined      ::= "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out"
path            ::= "path" "(" coords ("," coords)* ")"
cubicbezier     ::= "cubic-bezier" "(" controlpoints ")"
segmented       ::= ( line | curve )+ end
line            ::= "line" "(" coords ")"
curve           ::= "curve" "(" coords "," controlpoints ")"
end             ::= "end" "(" coords ")"
spatialcurve    ::= spatial ( scurve )+ send
spatial         ::= "spatial" "(" DOF "," INDEX ")"
scurve          ::= "scurve" "(" X "," Y_{DOF} "," TOUT_{DOF} "," TIN_{DOF} "," controlpoints ")"
send            ::= "send" "(" X "," Y_{DOF} ")"
coords          ::= X "," Y
controlpoints   ::= A "," B "," C "," D

個々の要素A、B、C、D、X、Yは、浮動小数点数値です。VALUE\_{DOF}構文は、コンマ区切りのDOF浮動小数点数値のセットです。

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

最終更新日: 2021 年 10 月 22 日