Alexa Vector Graphics形式（1.0）

Alexa Vector Graphics形式

（これはAPLの最新バージョンではありません。APLの最新バージョンの資料を参照するには、その他のバージョンオプションをクリックしてください）

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

プロパティ
AVGパス項目
- fillOpacity
- fill
- pathData
- strokeOpacity
- stroke
- strokeWidth
AVGグループ項目
AVGインフレートアルゴリズム

プロパティ

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

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

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

{
  "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プロパティがあります。現時点では、次の2つがあります。

Path
Group

parameters

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

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

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

{
  "type": "APL",
  "version": "1.1",
  "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つのパラメーター、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）の高さと幅をどのように変更するのかを制御します。有効なオプションは次のとおりです。

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

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

    {
      "type": "APL",
      "version": "1.1",
      "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"
          ]
        }
      }
    }

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

type

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

version

このベクターグラフィックで使用するAVG規格のバージョンに設定する文字列です。現時点では「1.0」に設定する必要があります。

viewportHeight

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

viewportWidth

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

幅

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

AVGパス項目

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

プロパティ	型	デフォルト	説明
`type`	"path"	必須	「path」に設定する必要があります。
`fillOpacity`	数値	1	パスの塗りつぶしの不透明度です。
`fill`	色	transparent	塗りつぶしの色です。
`pathData`	文字列	必須	パスの描画データです。
`strokeOpacity`	数値	1	パスの線の不透明度です。
`stroke`	色	transparent	線の描画に使用する色です。
`strokeWidth`	数値	1	パスの線の幅です。

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

fillOpacity

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

fill

パスを塗りつぶすために使用する色です。指定しない場合、塗りつぶしは行われません。

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の仕様を参照してください。

strokeOpacity

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

stroke

パスの線に使用する色です。指定しない場合、線は描画されません。

strokeWidth

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

AVGグループ項目

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

プロパティ	型	デフォルト	説明
`type`	”group”	必須	「group」に設定する必要があります。
`opacity`	数値	1.0	グループの不透明度です。
`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座標）です。
`item/items`	AVG項目の配列	[]	子の描画項目の配列です。

変換は、サイズ調整、回転、移動の順に適用されます。

opacity

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

rotation、pivotX、 pivotY

pivotX地点、pivotY地点を中心とした、グループの回転角度（度）です。

scaleXとscaleY

グループの倍率です。

translateXとtranslateY

グループの移動です。

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

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

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