APLのデータ型

APLのデータ型

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

ディメンション

APLのディメンションには、 絶対、相対、特殊の3とおりの表現方法があります。

絶対ディメンション

絶対ディメンションは、ディスプレイに依存しないピクセル数として解釈される整数です。絶対ディメンションは、単位サフィックスが付いた文字列として表すこともできます。単位サフィックスはディメンションの直後に続ける必要があります。有効なサフィックスは次のとおりです。

サフィックス 説明 例
dp ディスプレイに依存しないピクセル数。 20dp
px 画面のピクセル数。 10px
vh Viewportの高さ。Viewport全体の高さを100とします。1vhはViewportの高さの1%です。 50vh
vw Viewportの幅。Viewport全体の幅を100とします。1vwはViewportの幅の1%です。 33vw

相対ディメンション

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

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

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

特殊ディメンション

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

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

色

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

color         ::= _ <<basecolor>> _
<<basecolor>> ::= <<hex>> | <<function>> "(" _ <<args>> _ ")" | <<symbol>>
<<hex>>       ::= "#" [0-9a-fA-F]{3,4,6,8}
<<symbol>>    ::= [a-zA-Z]+
<<function>>  ::= "rgb" "a"? | "hsl" "a"?
<<args>>      ::= <<arg>> ( "," _ ARG )*
<<arg>>       ::= <<basecolor>> | <<percent>> | <<number>>
<<percent>>   ::= <<number>> "%"
<<number>>    ::= [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

色は、「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 色の配列 必須 各グラデーション分岐点に割り当てる色です。
description 文字列 "" （任意）このグラデーションの説明です。
inputRange 数値の配列 [] 入力のグラデーション分岐点です。0～1の値で、昇順に並んでいる必要があります。
type linear、radial linear グラデーションの種類です。

たとえば、画像のスクリム（オーバーレイ）用のサンプル線形グラデーションは次のようになります。

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

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

angle

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

colorRange

各グラデーション分岐点に割り当てる色です。色は分岐点の間で線形補間されます。

inputRange

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

type

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

イージング関数

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

イージング関数は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": "2024.3",
  "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次ベジェは、xとyをtの関数として定義します。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)： 座標(x,y)を始点とし、制御点a,b,c,dを使用する3次スプラインです。制御点の値は、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個の出力値へのマッピングが行われます。イージング関数では単一の出力値しかサポートされないため、空間曲線の最初の要素で、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": "2024.3",
  "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つのイージング関数が使用されています。どちらのイージング関数でも、同じ空間パスが適切なspatialヘッダーと共に使用され、関数からXとYの座標が取得されます。時間補間の制御点は非線形です。赤いボックスは(0,0)から「ジャンプ」し、(100,100)に近づくにつれて減速した後、再びゆっくりと加速し始め、(0,0)に近づくにつれて加速度を増します。

以下の例は、このアニメーションを示しています。この例では、アニメーションをアクティブ化するためのTouchWrapperが追加されています。ViewportのStart Animationというテキストをクリックすると、アニメーションが表示されます。

イージング文法

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

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浮動小数点数値のセットです。

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

最終更新日: 2025 年 11 月 04 日