Vega 图表

  1. Overview
  2. 简单示例
  3. 正在加载
  4. 数据格式
  5. 配置选项
  6. 方法
  7. 事件
  8. 数据政策

概览

VegaChart 是使用 Vega 可视化语法创建的众多可视化之一，Vega 可视化语法是一种用于创建、保存和分享交互式可视化设计的声明性语言。借助 Vega，您能够以 JSON 格式描述可视化的视觉外观和交互行为，并使用 Canvas 或 SVG 生成基于网络的视图。

绘制 VegaChart 时，您必须在选项中添加关于如何以 Vega 可视化语法构建图表的规范。以下列举了一些此类规范的示例，您还可以在 VegaChart 示例页面中找到更多示例。

注意：虽然 Google 图表 VegaChart 可以绘制您可以按照 Vega JSON 规范指定的任何 Vega 图表（包括 示例库中的所有内容），但目前尚不支持需要调用 Vega API 的其他功能。

简单的示例：条形图

下面是一个简单的 VegaChart 示例，可用于绘制条形图。（请参阅原始示例、详细教程以及 Vega 图表编辑器中的条形图。）

虽然这代表了在 Google 图表中生成条形图的另一种方式，但我们计划将其他条形图和柱形图的所有功能集成到基于此 VegaChart 的新实现中。

请注意，在此示例中，“data”选项被替换为以下代码，后者使用绘图调用提供的“datatable”作为另一个名为“table”的数据对象的“来源”，在 Vega 规范的其余部分中也使用“table”。 

  '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);

数据格式

您可以使用 DataTable（或 DataView）以非常类似于其他 Google 图表的方式将数据传递到 VegaChart。主要区别在于，VegaChart 并不依赖列的顺序来确定各列的使用方式，而是让每个列的 ID 与您所指定的特定 Vega 可视化图表的 ID 相同。 例如，创建以下 DataTable 时，这些列的 ID 分别为 'category' 和 'amount'，并且“vega”选项中使用相同的 ID 来引用这些列。

使用 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);

但是，这样只能将一个这样的 DataTable 传递到 VegaChart，而某些 Vega 图表需要多个数据表。我们将在未来的 Google 图表版本中解决这一限制。

在此期间，您可以通过内嵌或从网址加载数据的方式，在 'vega' 'data' 选项中指定需要使用的任何其他数据。 请参见下文，了解这两种情况的示例。

配置选项

名称
chartArea

一个对象，其中包含用于配置图表区域（绘制图表本身，不包括轴和图例）的位置和大小的成员。支持两种格式：数字或数字后跟 %。简单数字是以像素为单位的值；数字后跟 % 表示百分比。示例：chartArea:{left:20,top:0,width:'50%',height:'75%'}

类型：object
默认值：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。

Return Type（返回类型）：none
getAction(actionID)

返回具有所请求的 actionID 的提示操作对象。

返回类型：object
getBoundingBox(id)

返回一个对象，其中包含图表元素 id 的左侧、顶部、宽度和高度。尚未记录 id 的格式（它们是事件处理脚本的返回值），以下是一些示例：

var cli = chart.getChartLayoutInterface();

图表区域的高度
cli.getBoundingBox('chartarea').height
条形图或柱形图第一个系列中第三条柱的宽度
cli.getBoundingBox('bar#0#2').width
饼图第五个楔形的边界框
cli.getBoundingBox('slice#4')
垂直（如柱形）图表的图表数据的边界框：
cli.getBoundingBox('vAxis#0#gridline')
水平（例如条形图）图表数据的边界框：
cli.getBoundingBox('hAxis#0#gridline')

值是相对于图表容器而言的。在绘制图表之后调用此方法。

返回类型：object
getChartAreaBoundingBox()

返回一个对象，其中包含图表内容的左侧、顶部、宽度和高度（即不包括标签和图例）：

var cli = chart.getChartLayoutInterface();

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

值是相对于图表容器而言的。在绘制图表之后调用此方法。

返回类型：object
getChartLayoutInterface()

返回一个对象，其中包含有关图表在屏幕上的位置及其元素的信息。

可以对返回的对象调用以下方法：

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

在绘制图表之后调用此方法。

返回类型：object
getHAxisValue(xPosition, optional_axis_index)

返回 xPosition 处的水平数据值，这是相对于图表容器左边缘的像素偏移量。可以是负数。

示例：chart.getChartLayoutInterface().getHAxisValue(400)。

在绘制图表之后调用此方法。

Return Type（返回类型）：number
getImageURI()

返回已序列化为图片 URI 的图表。

在绘制图表之后调用此方法。

请参阅打印 PNG 图表。

返回类型：字符串
getSelection()

返回所选图表实体的数组。 对于此图表，在任何给定时刻，只能选择一个实体。 Extended description 。

返回类型：选择元素数组
getVAxisValue(yPosition, optional_axis_index)

返回 yPosition 处的垂直数据值，该值是从图表容器上边缘向下偏移的像素值。可以是负数。

示例：chart.getChartLayoutInterface().getVAxisValue(300)。

在绘制图表之后调用此方法。

Return Type（返回类型）：number
getXLocation(dataValue, optional_axis_index)

返回 dataValue 相对于图表容器左边缘的像素 x 坐标。

示例：chart.getChartLayoutInterface().getXLocation(400)。

在绘制图表之后调用此方法。

Return Type（返回类型）：number
getYLocation(dataValue, optional_axis_index)

返回 dataValue 相对于图表容器上边缘的像素 y 坐标。

示例：chart.getChartLayoutInterface().getYLocation(300)。

在绘制图表之后调用此方法。

Return Type（返回类型）：number
removeAction(actionID)

从图表中移除包含所请求 actionID 的提示操作。

返回值类型：none
setAction(action)

设置当用户点击操作文本时要执行的提示操作。

setAction 方法接受一个对象作为其操作参数。此对象应指定 3 个属性：id（所设置的操作的 ID）、text（应显示在操作提示中的文本）和 action（应在用户点击操作文本时应运行的函数）。

任何和所有提示操作都应在调用图表的 draw() 方法之前设置。详细描述。

返回值类型：none
setSelection()

选择指定的图表实体。取消之前的所有选择。 对于此图表，一次只能选择一个实体。 Extended description 。

Return Type（返回类型）：none
clearChart()

清除图表，并释放为其分配的所有资源。

Return Type（返回类型）：none

事件

如需详细了解如何使用这些事件，请参阅基本互动、处理事件和触发事件。

名称
animationfinish

过渡动画完整播放时触发。

属性：无
click

当用户点击图表内部时触发。可用于识别何时点击标题、数据元素、图例条目、轴、网格线或标签。

属性：targetID
error

尝试渲染图表时出错时触发。

属性：id、message
legendpagination

当用户点击图例分页箭头时触发。传回当前图例（从 0 开始）的网页索引和总页数。

属性：currentPageIndex、totalPages
onmouseover

用户将鼠标悬停在视觉实体上时触发。传回相应数据表元素的行和列索引。

属性：行、列
onmouseout

用户将鼠标远离视觉实体时触发。传回相应数据表元素的行和列索引。

属性：行、列
ready

该图表已准备好进行外部方法调用。如果您想与图表交互并在绘制图表后调用方法，则应在调用 draw 方法之前为该事件设置监听器，并仅在事件触发后调用监听器。

属性：无
select

当用户点击视觉实体时触发。如需了解已选择的内容，请调用 getSelection()。

属性：无

数据政策

所有代码和数据都会在浏览器中处理并呈现。系统不会向任何服务器发送任何数据。