VegaChart

  1. Overview
  2. 簡単な例
  3. 読み込んでいます
  4. データ形式
  5. 構成オプション
  6. メソッド
  7. イベント
  8. データポリシー

概要

VegaChart は、VegaVisualize Grammar を使用して作成できる多くの可視化方法の一つです。これは、インタラクティブな可視化設計を作成、保存、共有するための宣言型言語です。Vega を使用すると、可視化の見た目とインタラクティブな動作を JSON 形式で記述し、Canvas または SVG を使用してウェブベースのビューを生成できます。

VegaChart を描画する際は、Vega 可視化文法でグラフを作成する方法の仕様をオプションに含める必要があります。以下ではそのような仕様の例をいくつか示します。また、VegaChart の例のページでも例をいくつか示します。

注: Google Charts VegaChart では、Vega JSON 仕様で指定できる任意の Vega グラフ（ Example Gallery 内のすべてを含む）を描画できますが、 Vega API の呼び出しを必要とする追加機能はまだ利用できません。

棒グラフの簡単な例

棒グラフを描画する VegaChart の簡単な例です。 （元の例、詳細なチュートリアル、Vega グラフエディタの棒グラフをご覧ください）。

Google Chart で棒グラフを生成するもう 1 つの方法ですが、この VegaChart をベースにして、他の棒グラフと縦棒グラフのすべての機能を新しい実装に統合する予定です。

この例では、「data」オプションが次のように置き換えられています。これにより、描画呼び出しによって提供される「datatable」が「table」という別のデータ オブジェクトのソースとして使用され、「table」は Vega 仕様の残りの部分で使用されます。

  'data': [{'name': 'table', 'source': 'datatable'}],


<html>
  <head>
    <script src='https://www.gstatic.com/charts/loader.js'></script>
    <script>
      google.charts.load('upcoming', {'packages': ['vegachart']}).then(drawChart);

      function drawChart() {
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
          ['D', 91],
          ['E', 81],
          ['F', 53],
          ['G', 19],
          ['H', 87],
        ]);

        const options = {
          "vega": {
            "$schema": "https://vega.github.io/schema/vega/v4.json",
            "width": 500,
            "height": 200,
            "padding": 5,

            'data': [{'name': 'table', 'source': 'datatable'}],

            "signals": [
              {
                "name": "tooltip",
                "value": {},
                "on": [
                  {"events": "rect:mouseover", "update": "datum"},
                  {"events": "rect:mouseout",  "update": "{}"}
                ]
              }
            ],

            "scales": [
              {
                "name": "xscale",
                "type": "band",
                "domain": {"data": "table", "field": "category"},
                "range": "width",
                "padding": 0.05,
                "round": true
              },
              {
                "name": "yscale",
                "domain": {"data": "table", "field": "amount"},
                "nice": true,
                "range": "height"
              }
            ],

            "axes": [
              { "orient": "bottom", "scale": "xscale" },
              { "orient": "left", "scale": "yscale" }
            ],

            "marks": [
              {
                "type": "rect",
                "from": {"data":"table"},
                "encode": {
                  "enter": {
                    "x": {"scale": "xscale", "field": "category"},
                    "width": {"scale": "xscale", "band": 1},
                    "y": {"scale": "yscale", "field": "amount"},
                    "y2": {"scale": "yscale", "value": 0}
                  },
                  "update": {
                    "fill": {"value": "steelblue"}
                  },
                  "hover": {
                    "fill": {"value": "red"}
                  }
                }
              },
              {
                "type": "text",
                "encode": {
                  "enter": {
                    "align": {"value": "center"},
                    "baseline": {"value": "bottom"},
                    "fill": {"value": "#333"}
                  },
                  "update": {
                    "x": {"scale": "xscale", "signal": "tooltip.category", "band": 0.5},
                    "y": {"scale": "yscale", "signal": "tooltip.amount", "offset": -2},
                    "text": {"signal": "tooltip.amount"},
                    "fillOpacity": [
                      {"test": "datum === tooltip", "value": 0},
                      {"value": 1}
                    ]
                  }
                }
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(document.getElementById('chart-div'));
        chart.draw(dataTable, options);
      }
    </script>
  </head>

  <body>
    <div id="chart-div" style="width: 700px; height: 250px;"></div>
  </body>

</html>

読み込んでいます

google.charts.load パッケージ名は "vegachart" です。

google.charts.load("current", {packages: ["vegachart"]});

ビジュアリゼーションのクラス名は google.visualization.VegaChart です。

var visualization = new google.visualization.VegaChart(container);

データ形式

VegaChart には、DataTable（または DataView）を使って、他の Google グラフと同様の方法でデータを渡すことができます。主な違いは、VegaChart では、列の使用方法を決定する際に列の順序に依存するのではなく、各列の ID が、指定した特定の Vega ビジュアリゼーションに期待される ID と同じであることに依存します。たとえば、次の DataTable は、'category' と 'amount' の ID を持つ列で作成され、同じ ID がこれらの列を参照する「vega」オプションで使用されます。

DataTable あり
        const dataTable = new google.visualization.DataTable();
        dataTable.addColumn({type: 'string', 'id': 'category'});
        dataTable.addColumn({type: 'number', 'id': 'amount'});
        dataTable.addRows([
          ['A', 28],
          ['B', 55],
          ['C', 43],
        ]);

        const options = {
          'vega': {
            ...
            // Here we create the Vega data object named 'datatable',
            // which will be passed in via the draw() call with a DataTable.
            'data': {'name': 'datatable'},

            'scales': [
              {
                'name': 'yscale',
                // Here is an example of how to use the 'amount' field from 'datatable'.
                'domain': {'data': 'datatable', 'field': 'amount'},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);
Vega インライン データを使用
        // A DataTable is required, but it may be empty.
        const dataTable = new google.visualization.DataTable();
        const options = {
          'vega': {
            // Here the data is specified inline in the Vega specification.
            "data": [
              {
               "name": "table",
                "values": [
                  {"category": "A", "amount": 28},
                  {"category": "B", "amount": 55},
                  {"category": "C", "amount": 43},
                ]
              }
            ],

            'scales': [
              {
                'name': 'yscale',
                // Here is how Vega normally uses the 'amount' field from 'table'.
                "domain": {"data": "table", "field": "category"},
              }
            ]
          }
        };

        const chart = new google.visualization.VegaChart(
          document.getElementById('chart-div'));
        chart.draw(dataTable, options);

ただし、この方法で VegaChart に渡すことができる DataTable は 1 つのみです。また、一部の Vega チャートでは複数のデータテーブルが必要です。この制限は、Google Charts の今後のリリースで対処する予定です。

それまでの間、使用する必要がある追加データを 'vega' 'data' オプションに指定することができます。それには、データをインラインで読み込むか、URL から読み込みます。両方の例を以下に示します。

構成オプション

名前
chartArea

グラフ領域（グラフ自体が描画される場所。軸と凡例を除く）の配置とサイズを構成するメンバーを持つオブジェクト。サポートされている形式は、数字、または数字の後に % が続く形式です。単純な数字はピクセル単位の値で、数字の後に % を続けるとパーセンテージになります。例: chartArea:{left:20,top:0,width:'50%',height:'75%'}

タイプ: オブジェクト
デフォルト: null
chartArea.bottom

下枠線からグラフを描画する距離。

タイプ: 数値または文字列
デフォルト: auto
chartArea.left

左の枠線からグラフを描画する距離。

タイプ: 数値または文字列
デフォルト: auto
chartArea.right

右の枠線からグラフを描画する距離。

タイプ: 数値または文字列
デフォルト: auto
chartArea.top

上枠線からグラフを描画する距離。

タイプ: 数値または文字列
デフォルト: auto
chartArea.width

グラフ領域の幅。

タイプ: 数値または文字列
デフォルト: auto
chartArea.height

グラフ領域の高さ。

タイプ: 数値または文字列
デフォルト: auto
身長

グラフの高さ（ピクセル単位）。

タイプ: 数値
デフォルト: 含まれる要素の高さ
幅

グラフの幅（ピクセル単位）。

タイプ: 数値
デフォルト: 含まれる要素の幅

メソッド

メソッド
draw(data, options)

グラフを描画します。グラフは、ready イベントが発生した後にのみ、それ以上のメソッド呼び出しを受け入れます。Extended description。

戻り値の型: none
getAction(actionID)

リクエストされた actionID でツールチップ アクション オブジェクトを返します。

戻り値の型: オブジェクト
getBoundingBox(id)

グラフ要素 id の左、上、幅、高さを含むオブジェクトを返します。id の形式はまだ文書化されていません（これらはイベント ハンドラの戻り値です）が、以下に例を示します。

var cli = chart.getChartLayoutInterface();

グラフ領域の高さ
cli.getBoundingBox('chartarea').height
横棒グラフまたは縦棒グラフの 1 つ目の系列における 3 つ目の棒の幅
cli.getBoundingBox('bar#0#2').width
円グラフの 5 番目のくさびの境界ボックス
cli.getBoundingBox('slice#4')
縦棒グラフ（縦棒グラフなど）のグラフデータの境界ボックス:
cli.getBoundingBox('vAxis#0#gridline')
横棒グラフなど）のグラフデータの境界ボックス:
cli.getBoundingBox('hAxis#0#gridline')

値はグラフのコンテナを基準とします。グラフが描画された後に呼び出されます。

戻り値の型: オブジェクト
getChartAreaBoundingBox()

グラフ コンテンツの左、上、幅、高さを含むオブジェクトを返します（ラベルと凡例を除く）。

var cli = chart.getChartLayoutInterface();

cli.getChartAreaBoundingBox().left
cli.getChartAreaBoundingBox().top
cli.getChartAreaBoundingBox().height
cli.getChartAreaBoundingBox().width

値はグラフのコンテナを基準とします。グラフが描画された後に呼び出されます。

戻り値の型: オブジェクト
getChartLayoutInterface()

グラフの画面上の位置とその要素に関する情報を含むオブジェクトを返します。

返されたオブジェクトに対して、次のメソッドを呼び出すことができます。

  • getBoundingBox
  • getChartAreaBoundingBox
  • getHAxisValue
  • getVAxisValue
  • getXLocation
  • getYLocation

グラフが描画された後に呼び出されます。

戻り値の型: オブジェクト
getHAxisValue(xPosition, optional_axis_index)

xPosition の水平データ値（グラフ コンテナの左端からのピクセル オフセット）を返します。負の値を指定できます。

例: chart.getChartLayoutInterface().getHAxisValue(400)。

グラフが描画された後に呼び出されます。

戻り値の型: number
getImageURI()

画像の URI としてシリアル化されたグラフを返します。

グラフが描画された後に呼び出されます。

PNG チャートの印刷をご覧ください。

戻り値の型: string
getSelection()

選択したグラフ エンティティの配列を返します。 このグラフでは、任意の時点で選択できるエンティティは 1 つのみです。 Extended description 。

戻り値の型: 選択要素の配列
getVAxisValue(yPosition, optional_axis_index)

yPosition の垂直データ値（グラフ コンテナの上端からのピクセル オフセット）を返します。負の値を指定できます。

例: chart.getChartLayoutInterface().getVAxisValue(300)。

グラフが描画された後に呼び出されます。

戻り値の型: number
getXLocation(dataValue, optional_axis_index)

グラフのコンテナの左端を基準とする dataValue のピクセル x 座標を返します。

例: chart.getChartLayoutInterface().getXLocation(400)。

グラフが描画された後に呼び出されます。

戻り値の型: number
getYLocation(dataValue, optional_axis_index)

グラフのコンテナの上端を基準とする dataValue のピクセル y 座標を返します。

例: chart.getChartLayoutInterface().getYLocation(300)。

グラフが描画された後に呼び出されます。

戻り値の型: number
removeAction(actionID)

リクエストされた actionID を持つツールチップ アクションをグラフから削除します。

戻り値の型: none
setAction(action)

ユーザーがアクション テキストをクリックしたときに実行されるツールチップ アクションを設定します。

setAction メソッドは、アクション パラメータとしてオブジェクトを受け取ります。このオブジェクトでは、id（設定するアクションの ID）、text（アクションのツールチップに表示するテキスト）、action（ユーザーがアクション テキストをクリックしたときに実行する関数）の 3 つのプロパティを指定する必要があります。

すべてのツールチップ アクションは、グラフの draw() メソッドを呼び出す前に設定する必要があります。詳細な説明。

戻り値の型: none
setSelection()

指定したグラフ エンティティを選択します。前の選択をキャンセルします。このグラフでは、一度に 1 つのエンティティしか選択できません。 Extended description 。

戻り値の型: none
clearChart()

チャートを消去し、割り当て済みリソースをすべて解放します。

戻り値の型: none

イベント

これらのイベントの使用方法について詳しくは、基本的なインタラクティビティ、イベントの処理、イベントを発生させるをご覧ください。

名前
animationfinish

遷移アニメーションの完了時に呼び出されます。

Properties（プロパティ）: なし
click

ユーザーがグラフ内をクリックすると呼び出されます。タイトル、データ要素、凡例のエントリ、軸、グリッド線、ラベルがクリックされたタイミングを識別するために使用できます。

プロパティ: targetID
error

グラフのレンダリング中にエラーが発生したときに呼び出されます。

プロパティ: id、message
legendpagination

ユーザーが凡例のページ分け用の矢印をクリックすると呼び出されます。現在の凡例のゼロベースのページ インデックスと総ページ数を返します。

プロパティ: currentPageIndex、totalPages
onmouseover

ユーザーがビジュアル エンティティにカーソルを合わせたときに呼び出されます。対応するデータテーブル要素の行インデックスと列インデックスを渡します。

プロパティ: row、column
onmouseout

ユーザーがビジュアル エンティティからマウス離れたときに呼び出されます。対応するデータテーブル要素の行インデックスと列インデックスを渡します。

プロパティ: row、column
ready

グラフで外部メソッド呼び出しの準備が整いました。グラフを操作し、描画後にメソッドを呼び出す場合は、draw メソッドを呼び出す前にこのイベントのリスナーを設定し、イベントが発生した後にのみ呼び出す必要があります。

Properties（プロパティ）: なし
select

ユーザーがビジュアル エンティティをクリックしたときに呼び出されます。選択された内容を確認するには、getSelection() を呼び出します。

Properties（プロパティ）: なし

データポリシー

すべてのコードとデータはブラウザで処理されてレンダリングされます。データはどのサーバーにも送信されません。