APL VectorGraphic

APL VectorGraphic

VectorGraphicは、パッケージで定義されている、またはURLから読み込まれたScalable Vector Graphics画像を表示します。グラフィックを定義するには、Alexa Vector Graphic（AVG）形式を使用します。

プロパティ

VectorGraphicコンポーネントには、次のプロパティがあります。

プロパティ 型 デフォルト スタイル設定 動的 説明

align

配置

center

◯

◯

コンポーネント内のベクターグラフィックの配置です。

onFail

コマンド配列

[ ]

✕

✕

ソースが読み込みに失敗したときに実行するコマンド（複数可）です。

onLoad

コマンド配列

[ ]

✕

✕

ソースが読み込まれた後に実行するコマンド（複数可）です。

scale

スケール

none

◯

◯

ベクターグラフィックをコンポーネント内で、拡大または縮小する方法です。

source

URLまたは名前

<none>

✕

✕

ベクターグラフィックのURLまたは直接参照です。

これらのプロパティのほかに、AVGオブジェクトに固有のパラメーターも渡すことができます。

VectorGraphicがイベントのソースまたはターゲットである場合、以下の値がevent.sourceまたはevent.targetに報告されます。

{
  // VectorGraphic固有の値 
  "type": "VectorGraphic",
  "url": URL,          // The URL of the vector graphic

  // 一般的なコンポーネントの値  
  "bind": Map,         // コンポーネントのデータバインディングコンテキストへのアクセス    
  "checked": Boolean,  // チェック済みの状態 
  "disabled": Boolean, // 無効化の状態 
  "focused": Boolean,  // フォーカス状態 
  "height": Number,    // コンポーネントのdp単位の高さ（パディングを含む）        
  "id": ID,            // コンポーネントのID   
  "opacity": Number,   // コンポーネントの不透明度[0～1]    
  "pressed": Boolean,  // 押された状態 
  "uid": UID,          // ランタイムで生成されたコンポーネントの固有ID
  "width": Number      // コンポーネントのdp単位の幅（パディングを含む）        
}

heightおよびwidth

sourceがURLの場合は、コンポーネントでwidthプロパティとheightプロパティを定義する必要があります。定義されていない場合、デフォルトの100ピクセルになります。

sourceがローカルパッケージへの参照またはドキュメントのgraphicsプロパティ内の参照である場合は、heightとwidthをautoに設定できます。この場合、ベクターグラフィックオブジェクトで定義されたheightとwidthが使用されます。

align

コンポーネント内のVectorGraphicの位置を調整します。次のいずれかに設定します。

名前 説明

bottom

最下部に水平中央揃えで配置します。

bottom-left

左下隅に配置します。

bottom-right

右下隅に配置します。

center

水平方向および垂直方向の中央に配置します。

left

左側に垂直中央揃えで配置します。

right

右側に垂直中央揃えで配置します。

top

最上部に水平中央揃えで配置します。

top-left

左上隅に配置します。

top-right

右上隅に配置します。

onFail

リクエストされたURLのsourceが読み込みに失敗したときに実行するコマンドです。

ハンドラーは、sourceが読み込みに失敗したときに1回実行されます。ハンドラーが実行されたら、コンポーネントは無効とみなされます。

onFailハンドラーはコンポーネントのdisplayステータスに影響せず、displayステータスはハンドラーに影響しません。たとえば、VectorGraphicコンポーネントのdisplayプロパティがinvisibleのとき、コンポーネントはスペースを使いますが表示はされません。グラフィックのソースが読み込みに失敗した場合でも、デバイスはグラフィックの読み込みを試行し、onFailのコマンドを実行します。

コンポーネントのonMountハンドラーは、onFailが実行されるかどうかにかかわらず実行されます。このシナリオでは、コンポーネントをグラフィックソースの読み込み前後にマウントして表示することが可能なため、onMountハンドラーが実行されます。

onFailハンドラーは、次の形式のイベントを生成します。

"event": {
  "source": {
    "type": "VectorGraphic",
    "handler": "Fail",
    ...                     // コンポーネントのソースプロパティ  
  },
  "error": STRING,          // 失敗の理由   
  "errorCode": Number       // エラーID 
}

event.sourceの詳細についてはイベントソースを参照してください。

onFailイベントハンドラーは高速モードで実行されます。

onLoad

リクエストされたURLのsourceが読み込まれた後に実行されるコマンドです。

onLoadハンドラーはコンポーネントのdisplayステータスに影響せず、displayステータスはハンドラーに影響しません。たとえば、Imageコンポーネントのdisplayプロパティがinvisibleのとき、コンポーネントはスペースを使いますが表示はされません。グラフィックソースが読み込まれた後も、デバイスはグラフィックの読み込みを試行し、onLoadのコマンドを実行します。

コンポーネントのonMountハンドラーは、onLoadが実行されるかどうかにかかわらず実行されます。VectorGraphicコンポーネントは、グラフィックソースの読み込み前後にマウントして表示することが可能です。

読み込みが成功した場合に生成されるイベントは次の形式になります。

"event": {
  "source": {
    "type": "VectorGraphic",
    "handler": "Load",
    ...                     // コンポーネントのソースプロパティ  
  }
}

event.sourceの詳細についてはイベントソースを参照してください。

onLoadイベントハンドラーは高速モードで実行されます。

scale

コンポーネント内のベクターグラフィックのサイズを調整します。次のいずれかに設定します。

名前 説明

none

グラフィックのサイズは変更されません。バウンディングボックス内での画像の位置を設定するには、alignプロパティを使用します。バウンディングボックスからはみ出たグラフィックは切り捨てられます。

fill

グラフィックの幅がバウンディングボックスの幅に、高さがバウンディングボックスの高さに一致するように不均一にサイズを調整します。

best-fill

バウンディングボックス内にグラフィック全体が表示されるように、グラフィックのサイズを均一に拡大または縮小します。バウンディングボックス内でのサイズ調整後のグラフィックの位置を設定するには、alignプロパティを使用します。

best-fit

バウンディングボックス内にグラフィック全体が収まるように、グラフィックのサイズを均一に拡大または縮小します。alignプロパティは、バウンディングボックス内でサイズ変更されたグラフィックの位置を設定します。

source

ベクターグラフィックデータの場所を定義します。ソースを次のいずれかに設定します。

  • ドキュメントまたは読み込んだパッケージのgraphicsプロパティで定義されている名前
  • ベクターグラフィックの定義を指すURL

アクション可能なプロパティ

VectorGraphicはアクション可能なコンポーネントです。コンポーネントは、すべてのアクション可能なプロパティを継承します。

VectorGraphicコンポーネントはキーのハンドラーを持たないため、コンポーネントは以下のハンドラーを1つ以上定義した場合にのみキーボードフォーカスを受け取ります。

どのハンドラーも定義されていない場合、VectorGraphicがキーボードフォーカスを受け取ることはありません。

タッチ可能なプロパティ

VectorGraphicはタッチ可能なコンポーネントです。コンポーネントは、すべてのタッチ可能なプロパティを継承します。

ユーザーがコンポーネントをタッチしたときに生成されるソースイベントの詳細については、タッチ可能なコンポーネントのプロパティを参照してください。VectorGraphicコンポーネントは以下の固有の値を使用します。

event.source.type = "VectorGraphic"
event.source.value = Boolean    // VectorGraphicのチェック状態

VectorGraphicコンポーネントは、イベントにviewportプロパティを追加します。

"event": {
  "viewport": {
    "x": Number,       // ViewportのイベントのX位置（内部の描画ユニット）         
    "y": Number,       // ViewportのイベントのY位置（内部の描画ユニット）         
    "width": Number,   // Viewportの幅（内部の描画ユニット）      
    "height": Number,  // Viewportの高さ（内部の描画ユニット）      
    "inBounds": Boolean,  // イベントがViewportの境界内にある場合はTrue        
  }
}

VectorGraphicコンポーネントのバウンディングボックス内部に表示されるAVGは、VectorGraphic自体よりも小さくても大きくても構いません。

  • event.viewport.inBoundsプロパティを使って、変換されたAVGの境界内でイベントが発生したかどうかを判断します。
  • event.inBoundsプロパティを使って、VectorGraphicコンポーネントの境界内でイベントが発生したかどうかを判断します。

任意の組み合わせが可能です。イベントは、VectorGraphicコンポーネントの内部でAVGの外部であることも、VectorGraphicコンポーネントの外部でAVGの内部であることも可能です。

AVGオブジェクトパラメーター

Alexa Vector Graphic（AVG）オブジェクトはパラメーターを受け取れます。パラメーターを使用すると、色や特定の値（回転など）をグラフィックに渡すことができます。パラメーター値は、VectorGraphicコンポーネント自体の通常のプロパティとして渡されます。たとえば、fillColorをパラメーターとして受け取るグラフィックがある場合、次のようにレンダリングできます。

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "fillColor": "#ffff00"
}

明示的なプロパティ（上記のfillColorなど）とスタイル設定可能プロパティの両方を渡すことができます。たとえば、disabled状態で色が変わるバッテリーを作成するには、次のスタイルを定義します。

{
  "styles": {
    "batteryStyle": {
      "values": [
        {
          "fillColor": "#ffff00"
        },
        {
          "when": "${state.disabled}",
          "fillColor": "#ff00ff"
        }
      ]
    }
  }
}

次に、このスタイルをVectorGraphicコンポーネントで使用します。

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "style": "batteryStyle"
}

VectorGraphicを定義する形式について詳しくは、Alexa Vector Graphics形式を参照してください。

VectorGraphicの例

基本VectorGraphicの例

以下の例は、iconWifi3というAVGを100x100のボックスに表示するVectorGraphicを示しています。

{
  "type": "VectorGraphic",
  "source": "iconWifi3",
  "width": 100,
  "height": 100,
  "scale": "best-fit"
}

切り替えボタンのVectorGraphicの例

VectorGraphicコンポーネントは、タッチ可能なコンポーネントです。つまり、コンポーネントはポインターのイベントに応答します。以下の例は、onPressハンドラーを使用して切り替えボタンを作成する方法を示しています。

{
  "type": "APL",
  "version": "1.9",
  "graphics": {
    "ToggleButton": {
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "On"
      ],
      "width": 150,
      "height": 90,
      "items": [
        {
          "type": "path",
          "description": "背景の形状",
          "pathData": "M45,88 A43,43,0,0,1,45,2 L105,2 A43,43,0,0,1,105,88 Z",
          "stroke": "#979797",
          "fill": "${On ? 'green' : '#d8d8d8' }",
          "strokeWidth": 2
        },
        {
          "type": "group",
          "description": "Button",
          "translateX": "${On ? 60: 0}",
          "items": {
            "type": "path",
            "pathData": "M45,82 A36,36,0,0,1,45,8 A36,36,0,1,1,45,82 Z",
            "fill": "white",
            "stroke": "#979797",
            "strokeWidth": 2
          }
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "VectorGraphic",
      "source": "ToggleButton",
      "bind": {
        "name": "IsOn",
        "value": false
      },
      "On": "${IsOn}",
      "onPress": {
        "type": "SetValue",
        "property": "IsOn",
        "value": "${!IsOn}"
      }
    }
  }
}

スライドバーのVectorGraphicの例

以下の例は、onDown、onMove、onUpの各ハンドラーを使用してスライドバーを作成する方法を示しています。

{
  "type": "APL",
  "version": "1.9",
  "graphics": {
    "Slider": {
      "type": "AVG",
      "version": "1.2",
      "parameters": [
        "ButtonPosition",
        "ShowButton"
      ],
      "width": 150,
      "height": 90,
      "scaleTypeWidth": "stretch",
      "items": [
        {
          "type": "path",
          "description": "スライダーの背景",
          "pathData": "M45,55 a10,10,0,0,1,0,-20 l${width-90},0 a10,10,0,0,1,0,20 Z",
          "stroke": "#979797",
          "fill": "#d8d8d8",
          "strokeWidth": 2,
          "opacity": 0.4
        },
        {
          "type": "path",
          "description": "スライダーの塗りつぶし",
          "pathData": "M45,55 a10,10,0,0,1,0,-20 l${ButtonPosition *(width-90)},0 a10,10,0,0,1,0,20 Z",
          "stroke": "#979797",
          "fill": "#88e",
          "strokeWidth": 2
        },
        {
          "type": "group",
          "description": "Button",
          "translateX": "${ButtonPosition * (width - 90)}",
          "opacity": "${ShowButton ? 1 : 0}",
          "items": {
            "type": "path",
            "pathData": "M45,82 a36,36,0,0,1,0,-76 a36,36,0,1,1,0,76 Z",
            "fill": "#88e",
            "stroke": "white",
            "strokeWidth": 6
          }
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "VectorGraphic",
      "source": "Slider",
      "scale": "fill",
      "width": "100%",
      "bind": [
        {
          "name": "Position",
          "value": 0.50
        },
        {
          "name": "OldPosition",
          "value": 0.50
        },
        {
          "name": "ShowButton",
          "value": false
        }
      ],
      "ButtonPosition": "${Position}",
      "ShowButton": "${ShowButton}",
      "onDown": [
        {
          "type": "SetValue",
          "property": "ShowButton",
          "value": true
        },
        {
          "type": "SetValue",
          "property": "OldPosition",
          "value": "${Position}"
        },
        {
          "type": "SetValue",
          "property": "Position",
          "value": "${0, Math.clamp((event.viewport.x - 45) / (event.viewport.width - 90), 1)}"
        }
      ],
      "onUp": [
        {
          "type": "SetValue",
          "property": "ShowButton",
          "value": false
        },
        {
          "type": "SetValue",
          "description": "離れた場所でポインターをリリースした場合に位置をリセットします",
          "when": "${!event.inBounds}",
          "property": "Position",
          "value": "${OldPosition}"
        }
      ],
      "onMove": {
        "type": "SetValue",
        "property": "Position",
        "value": "${0, Math.clamp((event.viewport.x - 45) / (event.viewport.width - 90), 1)}"
      }
    }
  }
}