重要提示:Google 图表工具的“图片图表”部分自 2012 年 4 月 20 日起已被正式弃用。根据我们的弃用政策,该 API 仍可继续使用。
概览
通用图片图表是一种通用封装容器,适用于由 Google Chart API 生成的所有图表。尝试使用此可视化图表之前,请先阅读 Chart API 文档。请注意,使用此可视化方式,您最多可以发送 16K 的数据,这与直接调用 Chart API 时的 2K 限制不同。
所有数据均使用 DataTable 或 DataView 传递到图表。此外,某些标签作为数据表中的列进行传递。
所有其他 Chart API 网址参数(chd
除外)都将作为选项传递。
开发者:Google
示例
以下列举了几种不同类型的图表。
折线图
<html> <head> <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script> <script type='text/javascript'> google.charts.load("current", {packages:["imagechart"]}); </script> <script type='text/javascript'> google.charts.setOnLoadCallback(drawChart); function drawChart() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('string'); dataTable.addColumn('number'); dataTable.addColumn('string'); // Row data is [chl, data point, point label] dataTable.addRows([ ['January',40,undefined], ['February',60,'Initial recall'], ['March',60,'Product withdrawn'], ['April',45,undefined], ['May',47,'Relaunch'], ['June',75,undefined], ['July',70,undefined], ['August',72,undefined] ]); var options = {cht: 'lc', chds:'0,160', annotationColumns:[{column:2, size:12, type:'flag', priority:'high'},]}; var chart = new google.visualization.ImageChart(document.getElementById('line_div')); chart.draw(dataTable, options); } </script> </head> <body> <div id='line_div'></div> </body> </html>
垂直条形图表
请注意,在封装的条形图中,您无需像自行调用图表时那样指定 chxt='x';如果您不指定轴,则通用图片图表会默认尝试正确设置图表。
<html> <head> <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script> <script type='text/javascript'> google.charts.load("current", {packages:["imagechart"]}); </script> <script type='text/javascript'> google.charts.setOnLoadCallback(drawChart); function drawChart() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('number'); dataTable.addColumn('number'); dataTable.addRows([ [10,50], [50,60], [60,100], [80,40], [40,20] ]); var options = {cht: 'bvs', chs: '300x125', colors:['#4D89F9','#C6D9FD'], chds:'0,160', chxl:'0:|oranges|apples|pears|bananas|kiwis|'}; var chart = new google.visualization.ImageChart(document.getElementById('bar_div')); chart.draw(dataTable, options); } </script> </head> <body> <div id='bar_div'></div> </body> </html>
饼图
<html> <head> <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script> <script type='text/javascript'> google.charts.load("current", {packages:["imagechart"]}); </script> <script type='text/javascript'> google.charts.setOnLoadCallback(drawChart); function drawChart() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('string'); dataTable.addColumn('number'); dataTable.addRows([ ['January',12], ['February',8], ['March',3] ]); var options = {cht: 'p', title: 'Sales per Month', chp: 0.628, chs: '400x200', colors:['#3399CC','#00FF00','#0000FF']}; var chart = new google.visualization.ImageChart(document.getElementById('pie_div')); chart.draw(dataTable, options); } </script> </head> <body> <div id='pie_div'></div> </body> </html>
雷达图表
<html> <head> <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script> <script type='text/javascript'> google.charts.load("current", {packages:["imagechart"]}); </script> <script type='text/javascript'> google.charts.setOnLoadCallback(drawChart); function drawChart() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('number'); dataTable.addColumn('number'); dataTable.addRows([ [100,10], [80,20], [60,30], [30,40], [25,50], [20,60], [10,70] ]); var chart = new google.visualization.ImageChart(document.getElementById('radar_div')); var options = {cht: 'rs', chco: '00FF00,FF00FF', chg: '25.0,25.0,4.0,4.0', chm: 'B,FF000080,0,1.0,5.0|B,FF990080,1,1.0,5.0',}; chart.draw(dataTable, options); } </script> </head> <body> <div id='radar_div'></div> </body> </html>
地图图表
<html> <head> <script type='text/javascript' src='https://www.gstatic.com/charts/loader.js'></script> <script type='text/javascript'> google.charts.load("current", {packages:["imagechart"]}); </script> <script type='text/javascript'> google.charts.setOnLoadCallback(drawChart); function drawChart() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('string'); dataTable.addColumn('number'); dataTable.addRows([ ['DZ',0], ['EG',50], ['MG',50], ['GM',35], ['KE',100], ['ZA',100] ]); var options = {cht: 't', chtm: 'africa', chco: '777777,FFC6A5,FF0000', chs: '440x220'}; var chart = new google.visualization.ImageChart(document.getElementById('map_div')); chart.draw(dataTable, options); } </script> </head> <body> <div id='map_div'></div> </body> </html>
正在加载
google.charts.load
软件包名称为“imagechart”
google.charts.load('current', {'packages': ['imagechart']});
该可视化图表的类名称为 google.visualization.ImageChart
var visualization = new google.visualization.ImageChart(container_div);
数据格式
有两种通用的数据格式:一种用于地图图表,另一种用于所有其他图表。请注意,数据支持的唯一数字格式是 JavaScript 数字类型。
注意:您不应对任何作为数据或选项传递的字符串值进行网址编码。
地图图表
映射图表使用的是包含两个必需列的数据表格:
- 第一列 - [字符串] 国家/地区或州/省/自治区/直辖市代码。
- 第二列 - [数字] 相应国家/地区或州/省/自治区/直辖市的值。
如需了解详情,请参阅地图图表文档。
非地图图表
非地图图表采用的数据表格包含两个可选列(一列在开头,一列在末尾),中间有一个或多个数据列:
- 第一列 - [选填,字符串] 每个条目代表 X 轴上使用的一个标签(等同于
chl
或chxl
参数),用于支持该标签的图表。 - 后续列 - 任意数量的数字列,每列表示一个数据系列。
- 最后列 - [选填,字符串] 数据列后面的任意数量的字符串列,其中每个条目表示支持该标签的图表的数据点标签。如果要使用此列,则必须指定
annotationColumns
选项。
数据将以不同的方式显示,具体取决于图表类型。请参阅相关图表的文档。
关于列索引的注意事项:通用图片图表可视化功能会先从数据表中剥离字符串列,然后再将表发送到 Chart API 服务。因此,此页面定义的选项、方法和事件中的列索引包括索引计数中的字符串列;但是 Chart API 服务处理的任何选项中的列索引(例如 chm
选项)会忽略索引计数中的字符串列。
配置选项
此可视化图表定义了以下选项。您可以在传递给可视化图表的 draw()
方法的选项对象中定义这些选项。
并非所有图表类型都支持以下所有选项;请参阅静态图片图表类型的相关文档。您可以将任何 Chart API 网址参数作为选项传递。例如,图表可视化图表中的网址参数 chg=50,50
可采用以下方式指定:options['chg'] = '50,50'
。
关于颜色的注意事项:colors
、color
和 backgroundColor
等颜色选项是以 Chart API 颜色格式指定的。此格式与 #RRGGBB 格式类似,只不过它包含一个可选的第四个十六进制数字来指示透明度。不支持人类可读的颜色,例如“红色”“绿色”“蓝色”等。Chart API 颜色格式不包含前导 # 符号,但通用图片图表可视化选项将接受带有或不带 # 的颜色代码。
名称 | 类型 | 默认 | 说明 |
---|---|---|---|
annotationColumns | Array<object> | 无 | 各种图表的数据点标签。这是一个对象数组,每个对象都会为图表上的一个数据点分配一个设置了格式的标签。此选项仅适用于支持数据点的图表(请参阅链接的主题以了解哪些数据点),并且数据表必须至少包含一个字符串标签列。 数组中的每个对象都具有以下属性:
示例 - 以下代码段定义了一个 12 像素的黑色文本标签,其文本取自第 0 列,并分配给同一行第 2 列中的数据点: |
backgroundColor | string | '#FFFFFF'(白色) | 图表的背景颜色,采用 Chart API 颜色格式。 |
颜色 | string | 自动选择 | 指定要用于所有系列的基本颜色;每个系列都将是指定颜色的渐变色。颜色以 Chart API 颜色格式指定。如果指定了 colors ,则忽略。 |
颜色 | 数组<字符串> | 自动选择 | 用于为每个数据系列指定特定的颜色。颜色以 Chart API 颜色格式指定。
颜色 i 用于数据列 i;如果数据列数多于颜色,则换行到开头。如果一种颜色的变体适用于所有系列,请改用 color 选项。 |
enableEvents | boolean | false | 使图表抛出用户触发的事件,例如点击或鼠标悬停。 仅支持特定图表类型。请参阅下面的“事件”。 |
fill | boolean | false | 如果为 true,则填充每一行下方的区域。仅适用于折线图。 |
firstHiddenColumn | number | 无 | 数据列索引。列出的列以及后面的所有列不会用于绘制主图表系列元素(例如折线图上的线条或条形图上的条形),而是用作标记和其他注释的数据。请注意,字符串列包含在此索引计数中。 |
高度 | number | 200 | 图表的高度(以像素为单位)。如果缺失或不可接受的范围,则使用所包含元素的高度。如果也超出了可接受范围,系统将使用默认高度。 |
标签 | string | “none” | [仅限饼图] 要为各个切片显示的标签(如果有)。请从以下值中进行选择:
|
传奇 | string | “right” | 图表图例的显示位置(相对于图表)。请指定以下其中一项:“top”“bottom”“left”“right”“none”。在不含图例的图表(如地图图表)中会被忽略。 |
max | number | 最大数据值 | 比例上显示的最大值。对于饼图,将忽略此参数。默认值为最大数据值,但条形图除外,其默认值为最大数据值。当表格中包含多个数据列时,对于条形图,系统会忽略此参数。 |
分钟 | number | 最低数据值 | 比例上显示的最小值。对于饼图,将忽略此参数。默认值为最小数据值,但条形图除外,其默认值为 0。当表格中包含多个数据列时,对于条形图,系统会忽略此参数。 |
showCategoryLabels | boolean | true | 标签是否应显示在类别(即行)轴上。仅适用于折线图和条形图。 |
showValueLabels | boolean | true | 如果为 true,则会在值轴上显示标签。仅适用于折线图和条形图。 |
singleColumnDisplay | number | 无 | 仅呈现指定的数据列。此数字是表中从 0 开始的索引,其中 0 是第一个数据列。分配给单列的颜色与呈现所有列时的颜色相同。不能用于饼图或地图图表。 |
标题 | string | 空字符串 | 图表标题。如果未指定,则不会显示任何标题。等效的图表参数为 chtt 。 |
valueLabelsInterval | number | 自动选择 | 显示值轴标签的时间间隔。例如,如果 min 为 0、max 为 100 且 valueLabelsInterval 为 20,则图表将在 (0, 20, 40, 60, 80 100) 处显示轴标签。 |
宽度 | number | 400 | 图表的宽度,以像素为单位。如果缺失或不可接受的范围,则使用所包含元素的宽度。如果该值也超出了可接受的范围,系统将使用默认宽度。 |
方法
方法 | 返回值类型 | 说明 |
---|---|---|
draw(data, options) |
无 | 绘制地图。 |
getImageUrl() |
字符串 | 返回用于请求图表的 Google Chart API 网址。请注意,此值的长度可以超过 2000 个字符。有关详情,请参阅 Google Chart API。 |
事件
如果您将 enableEvents
属性设置为 true,则支持图表会针对下表中列出的用户事件抛出事件。所有这些事件都会返回一个 event
对象,其中包含以下属性:
type
- 表示事件类型的字符串。region
- 受影响区域的 ID。向原始图表类型添加chof=json
参数可查看可用名称的列表。如需了解详情,请参阅chof=json
。
名称 | 说明 | 类型 Value |
---|---|---|
error |
尝试渲染图表时出错时触发。 | id、message |
onmouseover |
用户将鼠标悬停在图表元素上时触发。 | “mouseover” |
onmouseout |
用户将鼠标远离图表元素时触发。 | “mouseout” |
onclick |
当用户点击图表元素时触发。 | “点击” |
哪些图表支持事件?
任何支持 chof=json
参数的图表都支持抛出事件(即除特殊图表(例如二维码)之外的所有图表)。
事件处理示例
以下示例展示了记录鼠标点击情况的条形。
<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <title> Google Image Events Sample </title> <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script> <script type="text/javascript"> google.charts.load('current', {packages: ['imagechart']}); </script> <script type="text/javascript"> function drawVisualization() { var dataTable = new google.visualization.DataTable(); dataTable.addColumn('number'); dataTable.addColumn('number'); dataTable.addRows([ [10,50], [50,60], [60,100], [80,40], [40,20] ]); var options = {cht: 'bvs', chs: '300x125', colors:['#4D89F9','#C6D9FD'], chds:'0,160', chxl:'0:|oranges|apples|pears|bananas|kiwis|', enableEvents:true}; var chart = new google.visualization.ImageChart(document.getElementById('visualization')); chart.draw(dataTable, options); // Assign event handler google.visualization.events.addListener(chart, 'onclick', mouseEventHandler); } google.charts.setOnLoadCallback(drawVisualization); // Define an event handler function mouseEventHandler(event) { document.getElementById('debugger').innerHTML += "You clicked " + event.region + "<br/>"; } </script> </head> <body style="font-family: Arial;border: 0 none;"> <div id="visualization" style="width: 300px; height: 300px;"></div> <div id="debugger"></div> </body> </html>
数据政策
数据会发送到 Google Chart API 服务。
本地化
此可视化图表支持 Google 图表服务支持的任何本地化。