Alexa Vector Graphics形式

Alexa Vector Graphics（AVG）形式でAPLドキュメントのベクターグラフィックを定義します。AVGはScalable Vector Graphics（SVG）のパラメーター化されたサブセットであり、SVGを選択するとグラフィックを複数のオペレーティングシステムに移植できます。AVGで定義されたグラフィックは、VectorGraphicコンポーネントを使って表示できます。VectorGraphicコンポーネントでは、APLパッケージ、APLドキュメント、URLのいずれかからAVGオブジェクトを読み込めます。

AVGオブジェクトプロパティ

以下の表は、AVGオブジェクトのプロパティを示しています。

以下の例では、赤で塗りつぶしたひし形を定義しています。

{
  "type": "AVG",
  "version": "1.2",
  "height": 100,
  "width": 100,
  "items": {
    "type": "path",
    "fill": "red",
    "stroke": "blue",
    "strokeWidth": 4,
    "pathData": "M 50 0 L 100 50 L 50 100 L 0 50 z"
  }
}

data

任意のデータ配列です。データ配列が指定されると、グラフィックはdata配列の各要素について、items配列から1つの項目をインフレートします。dataプロパティ、indexプロパティ、lengthプロパティが、データバインディングコンテキストに追加されます。

高さ

AVGオブジェクトのデフォルトの高さ（絶対位置）です。何らかの方法でオーバーライドまたはサイズ調整されない限り、AVGオブジェクトは画面上のこの高さに表示されます。これは絶対ディメンションでなければなりません。

item, items

AVG項目の配列です。配列は描画順です。後の項目が前の項目の上に描画されます。AVG項目には、typeプロパティがあります。

• Group
• Path
• Text

whenプロパティがtrueのitemがインフレートされます。indexプロパティ、lengthプロパティが各項目のデータバインディングコンテキストに追加されます。これは「子項目の1つの配列」インフレーションアルゴリズムです。

dataプロパティに値が含まれる場合は、インフレーションアルゴリズムが変わります。data配列の各項目について、items配列でwhenプロパティがtrueの最初の子項目がインフレートされます。dataプロパティ、indexプロパティ、lengthプロパティが、データバインディングコンテキストに追加されます。これは、「データ配列」インフレーションアルゴリズムです。

lang

AVG全体の言語を設定します。設定すると、APLは、グラフィック内のすべてのAVG Text項目に対してfontFamilyの言語固有のバージョンを探します。有効なフォントが見つからない場合、APLはこのプロパティを無視し、指定されたfontFamilyを使用します。設定しない場合、APLは指定のfontFamilyを使用します。

langプロパティにBCP-47文字列を設定します（例："ja-JP"）。

注： Alexaデバイスには特定の言語のフォントがインストールされていない場合があります。さまざまなデバイスで正常に動作するかどうかエクスペリエンスをテストしてください。

layoutDirection

AVG全体のレイアウト方向を設定します。設定しない場合、デフォルトはLTR（左から右）になります。layoutDirection は、グラフィック内のAVG Text項目に対してtextAnchorプロパティがどのように機能するかを決定します。

このプロパティは、AVG全体のlayoutDirectionを指定します。注：AVG全体のlayoutDirectionはドキュメントから継承されません。指定しない場合、ドキュメントのデフォルトのlayoutDirectionは「LTR」です。

resources

AVGリソースを参照してください。

parameters

AVGデータを評価する際にデータバインディングコンテキストに追加する、名前付きの値の配列です。各パラメーターは以下を含むオブジェクトです。

次のAPLドキュメントでは、colorとstrokeの幅のパラメーターを指定して、円形のベクターグラフィックを定義しています。このドキュメントのContainerは、さまざまなパラメーター設定を使用してグラフィックを3回インフレートします。

{
  "type": "APL",
  "version": "1.9",
  "graphics": {
    "parameterizedCircle": {
      "type": "AVG",
      "version": "1.2",
      "height": 100,
      "width": 100,
      "parameters": [
        {
          "name": "circleColor",
          "type": "color",
          "default": "black"
        },
        {
          "name": "circleBorderWidth",
          "type": "number",
          "default": 2
        }
      ],
      "items": [
        {
          "type": "path",
          "pathData": "M25,50 a25,25 0 1 1 50,0 a25,25 0 1 1 -50,0",
          "stroke": "${circleColor}",
          "strokeWidth": "${circleBorderWidth}",
          "fill": "none"
        }
      ]
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Container",
      "direction": "row",
      "items": {
        "type": "VectorGraphic",
        "source": "parameterizedCircle",
        "width": 100,
        "height": 100,
        "circleColor": "${data.color}",
        "circleBorderWidth": "${data.width}"
      },
      "data": [
        {
          "color": "red",
          "width": 5
        },
        {
          "color": "green",
          "width": 10
        },
        {
          "color": "blue",
          "width": 15
        }
      ]
    }
  }
}

便宜上、名前付きのパラメーターに名前しか指定されていない場合は、簡潔な文字列に短縮できます。

ユーザー定義のパラメーターに加えて、暗黙的に指定される2つのパラメーター、heightとwidth（両方とも数値）があります。これらは、サイズ調整されたviewportWidth値とviewportHeight値です。たとえば、高さstartingPixelHeightのベクターグラフィックがContainerに配置され、新しいサイズのscaledPixelHeightに合わせてサイズ調整されるように指示されているとします。この場合、内部でバインドされるheightとwidthの値は次の式で取得されます。

function calculateScale( double scale, ScaleType scaleType ) {
  switch (scaleType) {
    case "none":
      return 1.0;
    case "grow":
      return scale > 1.0 ? scale : 1.0;
    case "shrink":
      return scale < 1.0 ? scale : 1.0;
    case "stretch":
      return scale;
  }
}

height = viewportHeight * calculateScale( scaledPixelHeight / startingPixelHeight, scaleTypeHeight );
width = viewportWidth * calculateScale( scaledPixelWidth / startingPixelWidth, scaleTypeWidth );

scaleTypeHeightとscaleTypeWidth

scaleTypeHeightプロパティとscaleTypeWidthプロパティは、サイズ調整に応じてグラフィックの内部（viewport）の高さと幅をどのように変更するのかを制御します。有効なオプションは次のとおりです。

「錠剤型」のベクターグラフィック（縦型のスクロールバーやインジケーターなど）を例に挙げてみましょう。グラフィックのデザインは、上部と下部に丸みのある角を持つ縦長の長方形（塗りつぶしなし）です。ベクターグラフィックの縦方向の拡大縮小に応じて、丸みのある角の形状を維持しながら、中央の縦線を拡大縮小します。このグラフィックを簡単に定義するには、viewportが縦方向に拡大縮小するようにし、viewportの高さに応じてパスの縦方向のセグメントを描画する、パラメーター化された式を描画パスに挿入します。次に例を示します。

    {
      "type": "APL",
      "version": "1.9",
      "graphics": {
        "myPillShape": {
          "type": "AVG",
          "version": "1.2",
          "height": 100,
          "width": 100,
          "parameters": [ "myScaleType" ],
          "scaleTypeHeight": "${myScaleType}",
          "items": [
            {
              "type": "path",
              "pathData": "M25,50 a25,25 0 1 1 50,0 l0 ${height-100} a25,25 0 1 1 -50,0 z",
              "stroke": "black",
              "strokeWidth": 20
            }
          ]
        }
      },
      "mainTemplate": {
        "parameters": [
          "payload"
        ],
        "item": {
          "type": "Container",
          "direction": "row",
          "items": {
            "type": "VectorGraphic",
            "source": "myPillShape",
            "width": 100,
            "height": 200,
            "scale": "fill",
            "myScaleType": "${data}"
          },
          "data": [
            "none",
            "stretch"
          ]
        }
      }
    }

この例の左側の画像はviewportを拡大縮小できない場合の動作を示し、右側の画像はviewportが拡大される場合の動作を示しています。左側の画像では、viewportは100×100単位のviewportで描画され、画面上の100×200 dpの長方形に合うように拡大縮小されます。結果として、歪んだ円が作成されます。右側では、viewportのサイズ調整が拡大縮小に設定されているため、グラフィックは100×200単位のviewportで描画されます。heightプロパティはサイズ調整されたviewportの高さにコンテキスト内でバインドされるため、長さ${height - 100}または100単位の縦線のセグメントを追加で使用して、pathDataが描画されます。

styles

AVGスタイルを参照してください。

type

AVGに設定する文字列です。

version

このベクターグラフィックで使用するAVG規格のバージョンに設定する文字列です。

AVGの最新バージョンは1.2です。

AVG 1.2は、APL 1.5以降のバージョンでサポートされます。

viewportHeight

AVGオブジェクトの内部で使用される描画座標の高さです。指定しない場合、デフォルトはheightです。

viewportWidth

AVGオブジェクトの内部で使用される描画座標の幅です。指定しない場合、デフォルトはwidthです。

width

AVGオブジェクトのデフォルトの幅ディメンションです。何らかの方法でオーバーライドまたはサイズ調整されない限り、AVGオブジェクトは画面上にこのスペース幅で表示されます。これは絶対ディメンションでなければなりません。

AVGリソース

AVGグラフィックリソースとは、データバインディングと値の解決によりアクセスできる名前付きエンティティです。AVGリソースの構造は、APL Resourcesと同じです。AVGリソースは、グラフィックが読み込まれるときに評価されます。使用されるデータバインディングのコンテキストは、ドキュメントレベルのresourcesが読み込まれるグローバルドキュメントのデータバインディングコンテキストです。resourcesは静的であり、変更されることはありません。グラフィックresourcesは、@name構文を使ってドキュメントレベルのresourcesを参照できます。

グラフィックresourceブロックのサンプル：

"resources": [
  {
    "color": {
      "accent": "#00CAFF",
      "myBlue": "#66DFFF",
    },
    "number": {
      "lineWidth": 2
    },
    "string": {
      "checkmark": "M0,20 l10,10 l40,-40"
    },
    "pattern": {
      "redCircle": {
        "width": "18",
        "height": "18",
        "item": {
          "type": "path",
          "pathData": "M0,9 a9,9 0 1 1 18,0 a9,9 0 1 1 -18,0",
          "fill: "red"
        }
      }
    }
  },
  {
    "when": "${viewport.width > 1000}",
    "number": {
      "lineWidth": 4
    }
  },
  {
    "when": "${viewport.theme == 'light'}",
    "color": {
      "accent": "#0070BA",
      "myBlue": "@documentDarkBlue"
    }
  }
]

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

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

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

boolean

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

"boolean": {
  "a": true,   // True
  "b": null,   // False
  "c": ""      // False
  "d": 22      // True
}

color

色値は、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進数
}

easing

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

gradient

グラデーションは、AVGグラデーションセクションのルールに従って定義されます。次に例を示します。

"gradient": {
  "redWhite": {
    "type": "linear",
    "colorRange": [ "@myRed1", "white"],
    "inputRange": [ 0, 1 ],
    "angle": 90
  }
}

number

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

"numbers": {
  "a": 23,
  "b": "${viewport.width / viewport.height}"
}

pattern

パターンリソースは、パスの塗りつぶしやストロークに使用するAVGグラフィックオブジェクトです。次に例を示します。

"pattern": {
  "CirclePattern": {
    "description": "円の繰り返しパターン",
    "viewportWidth": 20,
    "viewportHeight": 20,
    "width": "25%",
    "height": "25%"
    "items": {
      "type": "path",
      "fill": "red",
      "pathData": "M0,10 a10,10 0 1 1 20,0 a10,10 0 1 1 -20,0"
    }
  }
}

詳細についてはAVGパターンを参照してください。

string

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

"strings": {
   "a": null,          // ""
   "b": "",            // ""
   "c": false,         // "false"
   "d": 23,            // "23"
   "e": "${@myRed1}"   // "#ff0000ff" （上記の色の定義による）
}

when

whenがtrueの場合（または指定されない場合）、このresourceブロックは処理され、定義されたAVGリソースに追加されます。whenがfalseの場合、resourceブロックはスキップされます。

AVGグラデーション

グラデーションとは、塗りつぶしやストロークに使用する陰影の付いた色のことです。AVGは、線形と放射のグラデーションをサポートしています。リソースで指定するAVGグラデーションは一定で、実行時に変更されません。fillまたはstrokeプロパティで直接指定するAVGグラデーションは動的にすることもできます（内部データバインディングプロパティと共に使った場合）。

以下は、線形と放射のグラデーションを含むAVGグラフィックの例です。

{
  "type": "AVG",
  "version": "1.2",
  "width": 358,
  "height": 150,
  "resources": {
    "gradients": {
      "linearGradient": {
        "inputRange": [
          0,
          0.5492504222972973,
          1
        ],
        "colorRange": [
          "#ffffffff",
          "#ff0000ff",
          "#000000ff"
        ],
        "type": "linear",
        "x1": 0.30127709565476446,
        "y1": 0.4259174391256225,
        "x2": 0.7981258206624885,
        "y2": 0.5839892388973439
      },
      "radialGradient": {
        "inputRange": [
          0,
          1
        ],
        "colorRange": [
          "#ffffffff",
          "#ff0000ff"
        ],
        "type": "radial",
        "centerX": 0.6480013075429227,
        "centerY": 0.4348329629565578,
        "radius": 1
      }
    }
  },
  "items": [
    {
      "type": "path",
      "description": "線形の星",
      "fill": "@linearGradient",
      "stroke": "#979797ff",
      "strokeWidth": 1,
      "pathData": "M86.5,120 L38.5955019,144.103326 L47.744447,93.0516628 L8.98889392,56.8966744 L62.547751,49.4483372 L86.5,3 L110.452249,49.4483372 L164.011106,56.8966744 L125.255553,93.0516628 L134.404498,144.103326 L86.5,120 Z"
    },
    {
      "type": "path",
      "description": "放射状の星",
      "fill": "@radialGradient",
      "fillTransform": "translate(0.648001,0.434833) matrix(-0.348987 0.320740 -0.306966 -0.364646 0 0) translate(-0.648001,-0.434833)",
      "stroke": "#979797ff",
      "strokeWidth": 1,
      "pathData": "M261.5,120 L213.595502,144.103326 L222.744447,93.0516628 L183.988894,56.8966744 L237.547751,49.4483372 L261.5,3 L285.452249,49.4483372 L339.011106,56.8966744 L300.255553,93.0516628 L309.404498,144.103326 L261.5,120 Z"
    }
  ]
}

AVGグラデーションはSVGグラデーション標準のサブセットであり、コンポーネントに使用されるグラデーション定義と一致しません。コンポーネントのグラデーションをAVGドキュメントに使用することもできます。ただし、コンポーネントのグラデーションはAVGグラデーションのようには拡大・縮小せず、機能も限られていることから、AVGグラデーションのみを使用することをお勧めします。

共通プロパティ

すべてのAVGグラデーションには、以下のプロパティがあります。

AVGグラデーションには次の2種類があります。

• Linear
• Radial

type

グラデーションのtypeには、必ず"linear"または"radial"の種類を定義する必要があります。

colorRange

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

inputRange

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

指定する場合は、inputRangeが (a) colorRangeと同じ数の要素を持ち、(b) [0,1]の範囲の数値が昇順で並んでいる必要があります。最初の値が0より大きい場合、0と最初の色値の間の色範囲は、最初の色値に固定されます。最後の値が1より小さい場合、最後の値と1の間の色範囲は、最後の色値に固定されます。

units

グラデーション位置の座標系を定義します。userSpace座標系は、オブジェクト描画に指定された座標系に基づいてグラデーションの次元位置を解釈します。これは、SVGのuserSpaceOnUse設定と同じです。boundingBox座標系は、グラデーションの次元位置を解析し、(0,0)の値をパスのバウンディングボックス左上にマッピングし、(1,1)の値をパスのバウンディングボックス右下にマッピングします。boundingBox値は、SVGのobjectBoundingBox設定と同じです。

Linear

線形グラデーションには共通プロパティのほかにも、次のプロパティがあります。

線形グラデーションの場合、spreadMethodは"pad"に設定され、angleが正しくなるようx1、x2、y1、y2の値が計算されます。これにより、unitの正方形の定義どおりに、最初と最後の色がオブジェクトのバウンディング矩形の対角に設定されます。

spreadMethod

線形グラデーションのspreadMethodは、(x1,y1)から(x2,y2)で定義されたボックスの範囲外で繰り返される方法を定義します。

x1/y1/x2/y2

これらの点は、グラデーションボックスの開始点および終了点を定義します。色範囲の最初の色は、(x1,y1)で描画されます。色範囲の最後の色は、(x2, y2)で描画されます。色は、色と入力範囲のルールに従って、これら2つの点の間で線形補間されます。

グラデーションに使用される座標系は、unitsプロパティによって定義されます。unitsプロパティがboundingBoxの場合、これらの値は、オブジェクトの周りをストロークまたは塗りつぶしで囲むバウンディング矩形の割合となります。異なるアスペクト比の図形に同じグラデーションを使用すると、異なる視角で表示されますので注意が必要です。fillTransformとstrokeTransformを使用して、視角を補正できます。

Radial

放射グラデーションには共通プロパティのほかにも、次のプロパティがあります。

放射グラデーションの場合、centerXとcenterYの値は50%に固定され、radiusの値は70.71%に固定されます。これにより、最初の色はオブジェクトの中心に、最後の色はオブジェクトのバウンディング矩形の隅に設定されます。

centerX/centerY

この点により、放射グラデーションの中心を定義します。この点は、unitsプロパティがboundingBoxの場合はオブジェクトの周りを塗りつぶしまたはストロークで描画するバウンディング矩形の割合で定義され、userSpaceの場合はローカル座標で定義されます。

radius

グラデーションの半径は、オブジェクトの周りを塗りつぶしまたはストロークで描画するバウンディング矩形の幅／高さの割合で定義されます。boundingBox単位を使って正方形以外のオブジェクトで描画される放射グラデーションは、グラデーション変化を適用してオブジェクトのアスペクト比を補間するまで、楕円として表示されます。fillTransformとstrokeTransformを使用して、視角を補正できます。

AVGフィルター

AVGフィルターは、AVG項目によって生成されたグラフィックに対して、その項目が表示される前に効果を適用します。

以下は、赤いひし形のグラフィックを作成する例です。DropShadowフィルターは、グラフィックにドロップシャドウを追加します。

{
  "type": "AVG",
  "version": "1.2",
  "width": "120px",
  "height": "120px",
  "items": {
    "type": "path",
    "fill": "red",
    "stroke": "blue",
    "strokeWidth": 4,
    "pathData": "M 60 10 L 110 60 L 60 110 L 10 60 z",
    "filters": [
      {
        "type": "DropShadow",
        "color": "black",
        "horizontalOffset": -3,
        "radius": 3,
        "verticalOffset": 3
      }
    ]
  }
}

フィルターには適用するフィルターのタイプを指定するtypeプロパティがあります。フィルターは定義順に適用されます。

配列内の最初のフィルターは、親AVG項目（複数可）から描画されるグラフィックを入力として受け取ります。配列内の後続の各フィルターは、前のフィルターの出力結果を入力として受け取ります。そして配列内の最後のフィルターの出力が表示されます。

次の表のフィルターを使用できます。

DropShadow

DropShadowフィルターは、入力グラフィックをコピーし、指定されたシャドウの色でRGB値を置き換えます。ソースグラフィックのアルファチャンネルと影の色が積算されて、シャドウアルファの値が決まります。これによりシャドウグラフィックがぼかされ、指定されたオフセットにより変換されて、元の入力グラフィックの背後にコピーされます。オフセットとぼかしの半径の値は、AVG座標で解釈されます。

生成される影は、AVGオブジェクトのディメンションによってバインドされます。DropShadowフィルターは、すべてのAVG項目と、前に描画されたすべてのAVG項目のフィルター結果の背後に影を描画します。

AVGパターン

AVGパターンは、パラメーター化されていない再利用可能なベクターグラフィック要素です。パスのstrokeとfillのプロパティに適用できます。AVGパターンは、以下のプロパティを持つオブジェクトです。

AVGパターンは、AVG patternリソースで定義する必要があります。AVGパターン内の描画操作は、0,0から、width、heightまでのボックスの描画に適用されます。このバウンディングボックス外の描画操作は切り取られます。

pathまたはtext要素を描画すると、内部では、AVGパターンがまず、オフスクリーンのビットマップにレンダリングされてから、ビットマップシェーダーとして使用されます。パターンがレンダリング中にアップスケールされると、ピクセル化アーティファクトが表示される場合があります。パターンをなるべく小さくしてアップスケールしないようにすることをお勧めします。

height

座標内に描画するのに最適なパターンの高さです。幅と高さの両方が正の数でないと、パターンは描画されません。

item, items

AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。次のような描画項目がすべてサポートされます。

• AVGパス項目
• AVGグループ項目
• AVGテキスト項目

width

座標内に描画するのに最適なパターンの幅です。幅と高さの両方が正の数でないと、パターンは描画されません。

AVGスタイル

AVG stylesは、単一のベクターグラフィック内にのみ適用されるAPL Stylesです。すべてのAVGプロパティにはスタイルを適用できます。APL Stylesの詳細については、APLスタイルの定義と評価を参照してください。

AVGスタイルの定義では、スタイルの名前、継承元となる1つまたは複数の親スタイルのリスト、条件付きで適用されるプロパティ定義の順序付きリストを指定します。

"styles": {
  "BasicButton: {
    "values": [
      {
        "strokeWidth": 5,
        "stroke": "red",
        "fill": "@StandardFillResource"
      },
      {
        "when": "${state.focused}",
        "stroke": "green",
      },
      {
        "when": "${state.pressed}",
        "stroke": "blue"
      }
    ]
  },
  "FancyButton": {
    "extends": "BasicButton",
    "values": [
      {
        "when": "${state.pressed}",
        "stroke": "@FancyButtonGradient"
      }
    ]
  }
}

スタイルの定義ごとに、次のプロパティがあります。

extend, extends

extends配列には、このスタイルの継承元となるスタイル名が順番に並んだ一覧が含まれます。これらのスタイルは、ローカルで定義されたAVGスタイル、グローバルのAPL Styleのいずれかになります。extends配列で参照される2つのスタイルが同じプロパティを定義する場合、リストの後のスタイルでプロパティ定義が上書きされます。

values, values

values配列には、適用するvalueオブジェクトが順番に並んだ一覧が含まれます。各valueオブジェクトは、次の形式になります。

{
  "when": EXPRESSION,
  NAME: VALUE,
  NAME: VALUE,
  :
}

whenプロパティはオプションであり、定義されていない場合のデフォルト値はtrueです。定義されたプロパティは、有効なスタイル設定可能プロパティの名前である必要があります（無効な名前は無視されます）。when句のデータバインディングコンテキストには、グラフィック、ドキュメント、または読み込まれたパッケージの中に以前に表示されたviewport、環境、リソース定義、スタイルが含まれます。

AVG基本項目

AVG基本項目は、一般的なAVG項目プロパティを指定する抽象クラスです。AVG項目の具体的な種類としては、次の3つがあります。

• AVGパス項目
• AVGグループ項目
• AVGテキスト項目

すべてのAVG項目は、次の表にあるプロパティをサポートします。

bind

AVG項目のbindプロパティは、項目およびその子のデータバインディングコンテキストを展開するためのものです。bindプロパティでは、現在のコンテキストを展開するデータバインディングを順序付きで指定します。バインディングには順序があり、以前のバインディングの定義を、それ以降のバインディングで使用できます。バインディング配列の各バインディングオブジェクトには、次の表に記載したプロパティを使用できます。

bindプロパティの評価は、whenプロパティとその他のプロパティとの間に行われます。バインディングは、配列の順序でデータバインディングコンテキストに追加されます。後続のバインディングでは先行するバインディングの結果を使用できます。

以下は、最初のバインディング（AspectRatio）を使う2つのバインディング（ReallyWideとTallish）の例です。

{
  "type": "text",
  "bind": [
    {"name":"AspectRatio","value":"${width/height}"},
    {"name":"ReallyWide","value":"${AspectRatio > 2}"},
    {"name":"Tallish","value":"${AspectRatio < 1}"}
  ],
  "text": "このボックスは${ReallyWide ? '幅が広すぎます' : 'ちょうどよい幅です'}",
  "fill": "${Tallish ? 'blue' : 'green'}"
}

内部のAPLで定義されたデータバインディングプロパティとの競合を避けるには、バインディングプロパティの名前の頭文字を大文字にします。たとえば、aspectRatioではなく、AspectRatioを使います。

バインディングにtypeプロパティがある場合、バインディングの計算結果がその型に割り当てられます（"any"以外）。

以下の例では、TALLプロパティが、現在の幅と高さに応じて"true"か"false"のstring値に割り当てられます。

{
  "bind": {
    "name": "TALL",
    "type": "string",
    "value": "${width < height}"
  }
}

filter、filters

このグループのすべての項目の描画に適用される1つ以上のフィルター操作です。フィルタは、表示される前に適用されます。グループフィルターは、グループのすべての項目が描画され、フィルターが適用された後に適用されます。フィルターの詳細については、AVGフィルターを参照してください。

style

この項目に適用するAVG styleの名前です。詳細については、AVGスタイルを参照してください。

type

インフレートする特定の項目の種類を指定します。次のいずれかになります。

• path – AVGパス項目
• group – AVGグループ項目
• text – AVGテキスト項目

typeプロパティは必須です。

when

trueの場合、AVG項目をインフレートします。falseの場合、AVG項目とその子項目をすべて無視します。

AVGパス項目

AVGパス項目では、通常の塗りつぶしと線で表示される形状を1つ以上定義します。AVGパス項目には以下のプロパティがあります。

• すべてのAVG基本項目プロパティ
• 次の表に挙げたパス項目プロパティ

AVGパス項目には以下のプロパティがあります。

少なくとも、fillまたはstrokeのいずれかを指定してください。fillとstrokeのいずれかが指定されていない場合、グラフィックは描画されません。

fill

パスを塗りつぶすために使用する色、グラデーション、またはパターンです。指定しない場合、塗りつぶしは描画されません。

以下は、グラデーションを使って塗りつぶした正方形を作成する例です。

{
  "gradientSquare": {
    "type": "AVG",
    "version": "1.2",
    "height": 100,
    "width": 100,
    "resources": [
      {
        "gradients": {
          "RedWhite": {
            "type": "linear",
            "colorRange": ["red","white"],
            "inputRange": [0,1],
            "angle": 90
          }
        }
      }
    ],
    "items": {
      "type": "path",
      "pathData": "M0,0 L40,0 L40,40 L0,40",
      "fill": "@RedWhite"
    }
  }
}

以下は、繰り返しパターンを使って塗りつぶした正方形を作成する例です。

{
  "patternSquare": {
    "type": "AVG",
    "version": "1.2",
    "height": 100,
    "width": 100,
    "resources": [
      {
        "patterns": {
          "RedCircle": {
            "width": 8,
            "height": 8,
            "items": [
              {
                "type": "path",
                "fill": "red",
                "pathData": "M0,4 a4,4,0,1,1,8,0 a4,4,0,1,1,-8,0"
              }
            ]
          }
        }
      }
    ],
    "items": {
      "type": "path",
      "pathData": "M0,0 L40,0 L40,40 L0,40",
      "fill": "@RedCircle"
    }
  }
}

resourcesとparametersを使えば、これらの定義を1つのAVG定義に統合してから、fillに渡すことができます。

サンプルドキュメント： AVG fillのサンプル

{
  "type": "APL",
  "version": "1.9",
  "theme": "dark",
  "graphics": {
    "squareWithFills": {
      "type": "AVG",
      "version": "1.1",
      "parameters": [
        {
          "name": "myFillType",
          "default": "red"
        }
      ],
      "resources": [
        {
          "gradients": {
            "RedWhite": {
              "type": "linear",
              "colorRange": [
                "red",
                "white"
              ],
              "inputRange": [
                0,
                1
              ],
              "angle": 90
            }
          },
          "patterns": {
            "RedCircle": {
              "width": 8,
              "height": 8,
              "items": [
                {
                  "type": "path",
                  "fill": "red",
                  "pathData": "M0,4 a4,4,0,1,1,8,0 a4,4,0,1,1,-8,0"
                }
              ]
            }
          }
        }
      ],
      "height": 100,
      "width": 100,
      "items": {
        "type": "path",
        "pathData": "M0,0 L40,0 L40,40 L0,40",
        "fill": "${myFillType}"
      }
    }
  },
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100%",
        "height": "100%",
        "paddingTop": "16dp",
        "paddingLeft": "16dp",
        "paddingRight": "16dp",
        "paddingBottom": "16dp",
        "items": [
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "red"
          },
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "@RedWhite"
          },
          {
            "type": "VectorGraphic",
            "source": "squareWithFills",
            "myFillType": "@RedCircle"
          }
        ],
        "direction": "row",
        "alignItems": "center",
        "justifyContent": "center"
      }
    ]
  }
}

fillOpacity

塗りつぶしに適用する不透明度です。塗りつぶしの色には不透明度も適用できます。最終的な塗りつぶしの不透明度は、fillOpacityと、前後のグループおよびホスティングコンポーネントのネストされたopacityプロパティの積になります。

fillTransform

塗りつぶしのグラデーションまたはパターンに対して適用するマトリックス変換です。fillTransformは、単色の塗りつぶしに対しては効果を持ちません。変換の構文については、AVGグループ項目セクションのtransformプロパティを参照してください。

pathData

SVGの「d」仕様で定義されている、1つ以上のパスコマンドを含む文字列です。以下の表は、パスのコマンドをまとめたものです。

正式な定義については、SVGの仕様を参照してください。

pathLength

pathLengthにより、ユーザーが定義した単位でパスの全長を指定できます。この値を使い、pathLength/（実際のパスの長さ）の比率を使って、strokeDashArrayプロパティとstrokeDashOffsetプロパティをスケーリングすることで、距離の計算を調整します。

ユーザーがpathLengthに負の数または0を指定すると、その値は無視されます。

stroke

パスのストロークに使用する色、グラデーション、またはパターンです。指定しない場合、ストロークは描画されません。

以下は、グラデーションストロークを使った正方形を作成する例です。

"resources": {
  "gradients": {
    "RedWhite": {
      "type": "linear",
      "colorRange": [ "red", "white" ],
      "inputRange": [0, 1],
      "angle": 90
    }
  }
}
...
{
  "type": "path",
  "pathData": "M4,4 l32,0 l0,32 l-32,0",
  "strokeWidth": 4,
  "stroke": "@RedWhite"
}

以下は、パターンストロークを使って正方形を作成する例です。

"resources": {
  "patterns": {
    "RedCircle": {
      "width": 8,
      "height": 8,
      "pathData": "M0,4 a4,4,0,1,1,8,0 a4,4,0,1,1,-8,0",
      "fill": "red"
    }
  }
}
...
{
  "type": "path",
  "pathData": "M4,4 l32,0 l0,32 l-32,0",
  "strokeWidth": 4,
  "fill": "@RedCircle"
}

strokeDashArray

strokeDashArrayは、パスのストロークに使用する破線と空白のパターンを定義する数値配列です。配列が空の場合、ストロークは1本となります。配列要素の数が奇数の場合、暗黙的に2倍になります。たとえば、配列[1]は[1 1]と解釈され、[1,2,3]は[1,2,3,1,2,3]と解釈されます。配列の奇数インデックスは破線の長さ（Viewport描画単位）、偶数インデックスは空白の長さ（Viewport描画単位）です。正の数値以外を指定すると、未定義の動作となります。

pathLengthがstrokeDashArrayに影響する：各破線と空白の長さは、pathLengthに対して相対的に解釈されます。

strokeDashArrayの個々の要素は、正の数値である必要があります。strokeDashArrayの要素の和は正の数値である必要があります。長さが0の破線の外観は、strokeLineCapの値によって変わります。「butt」要素の場合は描画されず、「round」要素の場合は直径がstrokeWidthと等しい円となり、「square」要素の場合は辺の長さがstrokeWidthと等しい正方形となります。

strokeDashOffset

strokeDashOffsetは、strokeDashArrayの開始点を、Viewport描画単位で指定した数値分、移動します。たとえば、strokeDashArrayが[2 1]の場合にstrokeDashOffsetに2を指定すると、線の描画はスペースで開始します。

pathLengthがstrokeDashOffsetに影響する：各破線と空白の長さは、pathLengthに対して相対的に解釈されます。

strokeLineCap

strokeLineCapプロパティにより、開いたパスの終端に使用される図形が決まります。

strokeLineJoin

strokeLineJoinプロパティにより、描画されるパスの角のシャープさが決まります。

strokeMiterLimit

strokeMiterLimitプロパティにより、パスのmiterジョイントがどの時点でbevelジョイントに変化するかが決まります。

strokeOpacity

線に適用する不透明度です。線の色には不透明度も適用できます。最終的な線の不透明度は、strokeOpacityと全体的なopacityの積になります。

strokeTransform

ストロークのグラデーションまたはパターンに対して適用するマトリックス変化です。strokeTransformは、単純な色のストロークに対しては効果を持ちません。変換構文については、transformを参照してください。

strokeWidth

線の幅です。デフォルトは1です。線はパスの位置に相対して中央に配置されます。

AVGグループ項目

AVGグループは、その子項目に変換を適用します。AVGグループ項目には、以下のプロパティがあります。

• すべてのAVG基本項目プロパティ
• 次の表に挙げたグループ項目プロパティ

clipPath

切り抜きのパスはpathDataの線で、描画されません。代わりに、グループの子が切り抜かれます。切り抜きは、グループの座標内で行われます。

data

任意のデータ配列です。データ配列が指定されると、AVGグラフィックはdata配列の各要素について、items配列から1つの項目をインフレートします。dataプロパティ、indexプロパティ、lengthプロパティが、データバインディングコンテキストに追加されます。

item, items

AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。AVG項目には、typeプロパティがあります。項目の種類は次の3つです。

• Path
• Group
• Text

whenプロパティがtrueのitemがインフレートされます。indexプロパティ、lengthプロパティが各項目のデータバインディングコンテキストに追加されます。これは「子項目の1つの配列」インフレーションアルゴリズムです。

dataプロパティに値が含まれる場合は、インフレーションアルゴリズムが変わります。data配列の各項目について、items配列でwhenプロパティがtrueの最初の子項目がインフレートされます。dataプロパティ、indexプロパティ、lengthプロパティが、データバインディングコンテキストに追加されます。これは、「データ配列」インフレーションアルゴリズムです。

opacity

このグループに適用する全体的な不透明度です。不透明度は、他の不透明度との積で表されます。

transform

グループのコンテンツに適用する変換です。transformプロパティはSVG構文に従うテキスト文字列です。

transform     ::= ( `rotate` | `scale` | `translate` | `skewX` | `skewY` )*
rotate        ::="rotate" "(" `angle` [ `x` `y` ] ")"
scale         ::="scale" "(" `sx` [ `sy` ] ")"
translate     ::="translate" "(" `x` [ `y` ] ")"
skewX         ::="skewX" "(" `angle` ")"
skewY         ::="skewY" "(" `angle` ")"

数値以外の文字（スペースとコンマを含む）は無視されます。角度は度数で指定します。正の回転値は、グループの起点を中心に時計回りです。座標系は、正のx値が右側、正のy値が下側です。起点は、通常左上にあります。

以下は同等となります。

translate(x)  ⟺ translate(x 0)
scale(s)      ⟺ scale(s s)
rotate(a x y) ⟺ translate(x y) rotate(a) translate(-x -y)

ベクターグラフィックスは、transformプロパティでデータバインディング式を使用できます。たとえば、アナログ時計の分針を正しく回転させるには、次のように記述します。

"transform": "rotate(${Time.minutes(localTime)*6})"

代替の変換プロパティ

状況によっては、サイズ調整、回転、移動の段階ごとに変換プロパティを記述する方が簡単な場合があります。代替の変換プロパティは、明示的な一連のプロパティを提供します。これらのプロパティは、transformプロパティが指定されていない場合にのみ利用できます。transformプロパティが指定されている場合、これらのプロパティは無視されます。

変換は、サイズ調整、回転、移動の順に適用されます。transformプロパティを使って、同等の変換を次のように定義できます。

"transform": "translate(tx ty) rotate(rotation px py) scale(sx sy)"

AVGテキスト項目

AVGテキスト項目は、1行のテキストとして表示されます。AVGテキスト項目には以下のプロパティがあります。

• すべてのAVG基本項目プロパティ
• 次の表に挙げたテキスト項目プロパティ

テキスト項目がストロークと塗りつぶしの両方で描画される場合、塗りつぶしがまず描画されて、ストロークがそれに重なって描画されます。

AVGテキスト項目には、AVGパス項目およびTextコンポーネントと同じプロパティが複数あります。

テキスト項目の例：

{
  "type": "AVG",
  "version": "1.2",
  "height": 60,
  "width": 150,
  "items": [
    {
      "type": "path",
      "pathData": "M0,0 l150,0 l0,60 l-150,0 Z",
      "fill": "#d8d8d8"
    },
    {
      "type": "text",
      "fill": "red",
      "fontFamily": "amazon-ember, sans-serif",
      "fontSize": 60,
      "text": "Hello",
      "x": 75,
      "y": 50,
      "textAnchor": "middle"
    }
  ]
}

fill

fillプロパティの動作は、パス項目のfillプロパティと同じです。

fillOpacity

fillOpacityプロパティの動作は、パス項目のopacityプロパティと同じです。

fillTransform

塗りつぶしのグラデーションまたはパターンに対して適用するマトリックス変換です。fillTransformは、単色の塗りつぶしに対しては効果を持ちません。変換構文については、transformを参照してください。

fontFamily

fontFamilyプロパティの動作は、TextコンポーネントのfontFamilyプロパティと同じです。

fontSize

フォントのサイズです。Viewport単位で表します。デフォルトは40です。

fontStyle

fontStyleプロパティの動作は、TextコンポーネントのfontStyleプロパティと同じです。

fontWeight

fontWeightプロパティの動作は、TextコンポーネントのfontWeightプロパティと同じです。

letterSpacing

文字間に追加するスペースです。負の値を指定できます。デフォルトは0です。文字間隔はViewport単位で指定します。

stroke

strokeプロパティの動作は、パス項目のstrokeプロパティと同じです。

strokeOpacity

strokeOpacityプロパティの動作は、パス項目のstrokeOpacityプロパティと同じです。

strokeTransform

ストロークのグラデーションまたはパターンに対して適用するマトリックス変化です。strokeTransformは、単純な色のストロークに対しては効果を持ちません。変換構文については、transformを参照してください。

strokeWidth

strokeWidthプロパティの動作は、パス項目のstrokeWidthプロパティと同じです。

text

表示するテキストを指定します。表示されるテキストは、Textコンポーネントのtextプロパティで使用される書式ルールのサブセットをサポートします。インラインマークアップ文字列（「<br>」や「<em>」など）は無視され、表示されません。マークアップ文字を表示するには、文字実体参照で置き換える必要があります。

数値実体参照は10進数と16進数で表記できます。たとえば、©は©または©と表記できます。

文字列「Copyright &\#169; 2018, Simon \&amp; Schuster. \<br\>\<em\>All Rights Reserved\</em\>」は、1行に表示されます。

Copyright © 2018, Simon & Shuster.All Rights Reserved

textAnchor

始点（x, y）を基準としたテキストの方向。以下の表は、オプションをまとめたものです。

x

テキストのベースラインのx座標です。textAnchorプロパティは、テキストが左または右方向に続くか、この点を中心にセンタリングされるかを制御します。

y

テキストのベースラインのy座標です。textAnchorプロパティは、テキストが左または右方向に続くか、この点を中心にセンタリングされるかを制御します。

AVGインフレートアルゴリズム

AVGオブジェクトをインフレートするには、次の手順を行います。

1. 新しいデータバインディングコンテキストを作成します。
2. 作成したデータバインディングコンテキストに各パラメーターを追加します。パラメーター値は、最初の一致を使用して次の順序で計算されます。
   1. JSONインフレートロジックから渡されます。たとえば、ユーザーはfillを外部から渡すことができます。詳しくは、VectorGraphicを参照してください。
   2. 現在のスタイルから名前別に抽出されます。
   3. デフォルト値がパラメーターに代入されます。
3. AVGオブジェクトについて計算されたviewportのwidthとheightをデータバインディングコンテキストに追加します。詳しくは、scaleTypeHeightとscaleTypeWidthを参照してください。
4. データバインディングを適用して、AVG JSON定義をネストされたグループ、パス、テキストオブジェクトにインフレートします。

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