Alexa Vector Graphics形式（1.0）
（これはAPLの最新バージョンではありません。APLの最新バージョンの資料を参照するには、その他のバージョンオプションをクリックしてください）
Alexa Vector Graphics（AVG）は、ベクターグラフィックを定義するための形式です。AVGはScalable Vector Graphics（SVG）のパラメーター化されたサブセットであり、SVGを選択するとグラフィックを複数のオペレーティングシステムに移植できます。AVGで定義されたグラフィックは、VectorGraphicコンポーネントを使って表示できます。VectorGraphicコンポーネントでは、APLパッケージ、APLドキュメント、URLのいずれかから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つがあります。
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
グループの移動です。
item/items
AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。AVG項目には、作成されたAVG項目を指定するtypeプロパティがあります。現時点では、次の2つがあります。
AVGインフレートアルゴリズム
AVGオブジェクトをインフレートするには、次の手順を行います。
- 新しいデータバインディングコンテキストを作成します。
- 作成したデータバインディングコンテキストに各パラメーターを追加します。パラメーター値は、最初の一致を使用して次の順序で計算されます。
- JSONインフレートロジックから渡されます。たとえば、ユーザーはfillを外部から渡すことができます。詳しくは、
VectorGraphicを参照してください。 - 現在のスタイルから名前別に抽出されます。
- デフォルト値がパラメーターに代入されます。
- JSONインフレートロジックから渡されます。たとえば、ユーザーはfillを外部から渡すことができます。詳しくは、
- AVGオブジェクトについて計算されたviewportの幅と高さをデータバインディングコンテキストに追加します。詳しくは、
scaleTypeHeightとscaleTypeWidthを参照してください。 - データバインディングを適用して、AVG JSON定義をネストされたグループとパスにインフレートします。
