APL VectorGraphic

APL VectorGraphic

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

プロパティ

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

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

align

配置

center

◯

◯

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

onFail

コマンドの配列

[ ]

×

×

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

onLoad

コマンドの配列

[ ]

×

×

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

parameters

パラメーターの配列

{}

×

◯

ベクターグラフィックに渡すパラメーターのオプションのマップです。

scale

スケール

none

◯

◯

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

source

URLまたは名前

<none>

×

◯

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

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

{
  // VectorGraphic固有の値
  "type": "VectorGraphic",
  "url": URL,          // ベクターグラフィックのURL

  // 一般的なコンポーネントの値
  "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回実行されます。ハンドラーが実行されたら、コンポーネントは無効とみなされます。

sourcesプロパティに新しい値を設定すると、ハンドラーを再度トリガーできます。onFailハンドラーは、新しい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のプロパティの詳細については、eventプロパティを参照してください。

onFailイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

onLoad

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

sourcesプロパティに新しい値を設定すると、ハンドラーを再度トリガーできます。onLoadハンドラーは、新しいsource値に対して最大1回実行されます。

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

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

読み込み成功時に生成されるイベントの形式は次のとおりです。

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

event.sourceのプロパティの詳細については、eventプロパティを参照してください。

onLoadイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

parameter、parameters

parametersプロパティは、文字列名とソースベクターグラフィックのparametersのパラメーターに対応する値のマップです。マップのキーと値には、実行時に適用されるデータバインディングが含まれます。

scale

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

名前 説明

none

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

fill

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

best-fill

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

best-fit

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

source

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

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

次の例は、sourceが動的な値に設定されたVectorGraphicを示しています。ユーザーがボタンをクリックすると、SetValueコマンドによってGraphicIndex値が更新され、表示されるグラフィックが変更されます。

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

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

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

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

タッチ可能なプロパティ

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

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

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

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

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

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

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

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

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

Alexa Vector Graphic（AVG）オブジェクトは、色やその他の値（回転など）を渡すパラメーターを受け取ることができます。これらのパラメーターは、次の2つの方法のいずれかで渡すことができます。

  • パラメーターのマップをコンポーネントのparametersプロパティに渡します。
  • VectorGraphicコンポーネントでパラメーターを直接設定します。

たとえば、FillColorパラメーターを受け入れるグラフィックがあるとします。

以下は、parametersマップを使用してFillColorに値を渡す方法を示しています。

{
  "type": "VectorGraphic",
  "source": "iconBattery",
  "parameters": {
    "FillColor": "#ffff00"
  }
}

または、以下も有効です。

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

これら2つの方法を組み合わせてパラメーターを渡すことはできません。parametersマップを指定した場合、VectorGraphicに追加されたプロパティはグラフィックのパラメーターとして解釈されません。

明示的なプロパティ（上記の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ハンドラーを使用して切り替えボタンを作成する方法を示しています。

スライドバーのVectorGraphicの例

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

このページは役に立ちましたか？

最終更新日: 2025 年 12 月 12 日