Alexa Vector Graphics形式(1.1)



Alexa Vector Graphics形式

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

プロパティ

AVGオブジェクトには以下のプロパティがあります。

プロパティ デフォルト 説明
description 文字列 "" このベクターグラフィックの任意の説明です。
height 正の絶対ディメンション 必須 グラフィックの高さです。
item, items AVG項目の配列 [] 描画項目の配列です。各項目は、グループ、パス、またはテキストです。
parameters AVGパラメーターの配列 [] AVGオブジェクトに設定できるパラメーター値の配列です。
resources RESOURCES [] ローカルグラフィック固有のリソースです。
scaleTypeHeight none | grow | shrink | stretch none グラフィックの高さに応じて、viewportの高さがどのように変化するかを指定します。
scaleTypeWidth none | grow | shrink | stretch none グラフィックの幅に応じて、viewportの幅がどのように変化するかを指定します。
styles STYLES {} ローカルグラフィック固有のスタイルです。
type "AVG" 必須 ベクターグラフィックの種類です。
version 1.1 必須 AVG規格の現在のリリースバージョンです。
viewportHeight 正の数値 <height> viewportの高さです。
viewportWidth 正の数値 <width> viewportの幅です。
width 正の絶対ディメンション 必須 グラフィックの幅です。

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

{
  "type": "AVG",
  "version": "1.0",
  "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"
  }
}

高さ

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

item, items

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

resources

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

parameters

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

プロパティ 必須 説明
name 文字列 パラメーターの名前です。
description 文字列 パラメーターの任意の説明です。
type any | string | number | color パラメーターの型です。デフォルトは「any」です。
default any パラメーターに代入するデフォルト値です。デフォルトは、空白の文字列(typeが指定されていない場合)または型に該当する空白の値です。

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

{
  "type": "APL",
  "version": "1.4",
  "graphics": {
    "parameterizedCircle": {
      "type": "AVG",
      "version": "1.0",
      "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つのパラメーター、heightwidth(両方とも数値)があります。これらは、サイズ調整されたviewportWidth値とviewportHeight値です。たとえば、高さstartingPixelHeightのベクターグラフィックがContainerに配置され、新しいサイズのscaledPixelHeightに合わせてサイズ調整されるように指示されているとします。この場合、内部でバインドされるheightwidthの値は次の式で取得されます。

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)の高さと幅をどのように変更するのかを制御します。有効なオプションは次のとおりです。

ScaleType 説明
none viewportのディメンションは変更されません(デフォルト)。
stretch viewportのディメンションは、描画ディメンションの変更に比例して拡大または縮小します。
grow viewportのディメンションは、描画ディメンションの変更に比例して拡大しますが、縮小はしません。
shrink viewportのディメンションは、描画ディメンションの変更に比例して縮小しますが、拡大はしません。

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

    {
      "type": "APL",
      "version": "1.4",
      "graphics": {
        "myPillShape": {
          "type": "AVG",
          "version": "1.0",
          "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"
          ]
        }
      }
    }
左側は非均等のサイズ調整、右側は「stretch」の動作を表します。
左側は非均等のサイズ調整、右側は「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規格のバージョンに設定する文字列です。現時点では「1.0」に設定する必要があります。

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の各ブロックのプロパティは以下のとおりです。

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

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.1",
  "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グラデーションには、以下のプロパティがあります。

プロパティ デフォルト 説明  
type linear radial 必須 グラデーションの種類です。
colorRange 色(color)の配列 必須 各グラデーションの終了点に指定される色です。  
description 文字列 "" このグラデーションの説明です(任意)。  
inputRange 数の配列 [] 入力のグラデーションの終了点です。  
units userSpace boundingBox boundingBox 位置の座標系です。

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

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設定と同じです。

*units*とオブジェクトサイズの対応図です。小さい正方形の辺の長さは100、大きい正方形の辺の長さは200です。

Linear

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

プロパティ デフォルト 説明    
spreadMethod pad / reflect / repeat / pad 定義された範囲外でのグラデーション動作です。
x1 数値 0% グラデーション開始のx位置です。    
x2 数値 100% グラデーション終了のx位置です。    
y1 数値 0% グラデーション開始のy位置です。    
y2 数値 100% グラデーション終了のy位置です。    

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

spreadMethod

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

x1/y1/x2/y2

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

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

Radial

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

プロパティ デフォルト 説明
centerX 数値 50% グラデーションの中心のx位置です。
centerY 数値 50% グラデーションの中心のy位置です。
radius 正の数値 70.71% グラデーションの半径(終端までの距離)です。

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

centerX/centerY

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

radius

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

AVGパターン

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

プロパティ デフォルト 説明
description 文字列 "" このパターンの説明です(任意)。
height 正の数値 必須 パターンの高さです。
item(items) AVG項目の配列 [] 描画項目の配列です。
width 正の数値 必須 パターンの幅です。

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

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

height

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

item, items

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"
      }
    ]
  }
}

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

プロパティ デフォルト 説明
description 文字列 "" このスタイルの説明です。
extend, extends スタイル名の配列 [] このスタイルの継承元となるスタイルを一覧にしたものです。順序が後のスタイルが、順序が先のスタイルを上書きするため、順序が重要です。
value, values valueオブジェクトの配列 [] オブジェクトの配列です。

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

プロパティ デフォルト 説明
type "path" 必須 「path」に設定する必要があります。
fill transparent 塗りつぶしの色です。
fillOpacity 数値 1 パスの塗りつぶしの不透明度です。
fillTransform 変換 "" 変換は、塗りつぶしグラデーションまたはパターンに対して適用されます。
pathData 文字列 必須 パスの描画データです。
pathLength 負ではない数値 0 定義する場合、パスの「長さ」を指定します。
stroke transparent 線の描画に使用する色です。
strokeDashArray 長さの配列 [] 破線と空白のパターンです。
strokeDashOffset 長さ 0 破線配列パターンへのオフセットです。
strokeLineCap butt、round、square butt 開いたパスの終端に使用される図形です。
strokeLineJoin bevel、miter、round miter パスの角の描画方法です。
strokeMiterLimit 正の数値 4 図形パスの角が面取りされる場合です。
strokeOpacity 数値 1 パスの線の不透明度です。
strokeTransform 変換 "" 変換は、ストロークグラデーションまたはパターンに対して適用されます。
strokeWidth 数値 1 パスの線の幅です。
style 文字列 "" 適用するスタイル名です。

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

fill

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

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

{
  "gradientSquare": {
    "type": "AVG",
    "version": "1.1",
    "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.1",
    "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に渡すことができます。

色、グラデーション、パターン塗りつぶしの例
色、グラデーション、パターン塗りつぶしの例

fillOpacity

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

fillTransform

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

pathData

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

コマンド パラメーター 説明

M, m

(x,y)+

絶対座標で次のサブパスの先頭に移動します。追加のペアは暗黙的な「L」コマンドです。「m」バリアントでは相対座標を使用します。

L, l

(x,y)+

現在位置から新しい位置まで、絶対座標で線を描画します。追加の線でペアを反復処理させることができます。「l」バリアントでは相対座標を使用します。

H, h x+ 絶対座標(H)または相対座標(h)で横線を描画します。
V, v y+ 絶対座標(H)または相対座標(h)で縦線を描画します。

C, c

(x1,y1,x2,y2,x,y)+

x1、y1、x2、y2を制御点として、現在の地点からx、yにベジェ曲線を描画します。絶対座標(C)または相対座標(c)を使用します。

S, s

(x2,y2,x,y)+

x 2、y 2を曲線の終点の制御点として、現在の地点からx、yまで滑らかなベジェ曲線を描画します。絶対座標(S)または相対座標(s)を使用します。

Q, q

(x1,y1,x,y)+

x1、y1を制御点として、x座標、y座標まで2次ベジェ曲線を描画します。絶対座標(Q)または相対座標(q)です。

T, t

(x,y)+

x座標、y座標まで滑らかな2次ベジェ曲線を描画します。この場合、制御点は前の曲線から引き継がれます。絶対座標(T)または相対座標(t)です。

A, a

Z, z

(rx ry angle large-arc-flag sweep-flag x y)+

x座標、y座標まで楕円弧曲線を描画します。楕円の半径はrx、ryです。楕円の回転は角度です。フラグでは、描画する円弧の部分と方向を選択します。絶対座標(A)または相対座標(a)です。始点と終点の間の直線を使用して、現在のサブパスを閉じます。サブパスを閉じても塗りつぶしは影響を受けませんが、線は影響を受けます。

正式な定義については、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描画単位)です。正の数値以外を指定すると、未定義の動作となります。

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

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

strokeDashArray=[0,6]の3本の線。上から、strokeLineCapに「round」、「square」、「butt」が指定されています。

strokeDashOffset

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

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

strokeLineCap

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

strokeLineJoin

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

strokeMiterLimit

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

strokeOpacity

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

strokeTransform

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

strokeWidth

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

style

この項目に適用するAVG styleの名前です。すべてのパス項目プロパティにはスタイルを適用できます。

AVGグループ項目

AVGグループは、子に変換を適用するために使用されます。AVGグループ項目には、以下のプロパティがあります。

プロパティ デフォルト 説明
type ”group” 必須 「group」に設定する必要があります。
clipPath 文字列 なし 切り抜きのパスです。
item, items AVG項目の配列 [] 子の描画項目の配列です。
opacity 数値 1.0 グループの不透明度です。
style 文字列 "" 適用するスタイル名です。
transform 変換 "" グループのコンテンツに適用する変換です。

clipPath

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

item, items

AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。AVG項目には、作成されたAVG項目を指定するtypeプロパティがあります。AVGは、以下のタイプをサポートします。

opacity

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

style

この項目に適用するAVG styleの名前です。すべてのグループ項目プロパティにスタイルを適用できます。

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プロパティが指定されている場合、これらのプロパティは無視されます。

プロパティ デフォルト 説明
rotation 数値 0 グループの回転角度(度)です。
pivotX 数値 0 回転ピボット点のX座標(viewport座標)です。
pivotY 数値 0 回転ピボット点のY座標(viewport座標)です。
scaleX 数値 1.0 X軸方向の倍率係数です。
scaleY 数値 1.0 X軸方向の倍率係数です。
translateX 数値 0 X座標の移動(viewport座標)です。
translateY 数値 0 Y座標の移動(viewport座標)です。

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

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

AVGテキスト項目

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

プロパティ デフォルト 説明
type "text"(テキスト)を指定します。 必須 この項目がテキスト項目であることを示します。
fill 色、グラデーション、パターン black テキストの塗りつぶし色、グラデーション、またはパターンです。
fillOpacity 数値 1 テキストの塗りつぶしの不透明度です。
fillTransform 変換 "" 変換は、塗りつぶしグラデーションまたはパターンに対して適用されます。
fontFamily 文字列 sans-serif フォントファミリーの名前です。
fontSize 正の数値 40 フォントサイズです。
fontStyle normal, italic normal フォントのスタイルです。
fontWeight normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900 normal フォントの太さです。
letterSpacing 数値 0 文字間に追加するスペースです。
stroke 色、グラデーション、パターン transparent テキストストロークの色、グラデーション、またはパターンです。
strokeOpacity 数値 1 パスストロークの不透明度です。
strokeTransform 変換 "" 変換は、ストロークグラデーションまたはパターンに対して適用されます。
strokeWidth 負ではない数値 0 テキストストロークの幅です。
style 文字列 "" 適用するスタイル名です。
text 文字列 "" 表示するテキストを指定します。
textAnchor start、middle、end start 開始点からテキストが続く方向です。
x 数値 0 X座標の開始点(Viewport座標)です。
y 数値 0 Y座標の開始点(Viewport座標)です。

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

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

テキスト項目の例:

{
  "type": "AVG",
  "version": "1.1",
  "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プロパティと同じです。

style

この項目に適用するAVG styleの名前です。すべてのテキスト項目プロパティにスタイルを適用できます。

text

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

実体 文字 説明
&amp; & アンパサンド
&lt; < 小なり記号
&gt; > 大なり記号
&\#nn; 任意 10進数のUnicodeコードポイントです。「nn」は有効な整数です。
&\#xnn;   16進数のUnicodeコードポイントです。「nn」は有効な16進数です。

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

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

Copyright © 2018, Simon & Shuster.All Rights Reserved

textAnchor

開始点(x,y)からテキストが続く方向です。以下のオプションを利用できます。

名前 説明
start テキストは開始点(x,y)から開始します。左から右に記述する言語の場合、テキストは右方向に続きます。右から左に記述する言語の場合、テキストは左方向に続きます。
middle テキストは、開始点(x,y)を中心にセンタリングされます。
end テキストは、開始点(x,y)で終了します。左から右に記述する言語の場合、テキストは左方向に続きます。右から左に記述する言語の場合、テキストは右方向に続きます。

x

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

y

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

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

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

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