Google 可视化 API 参考文档

本页面列出了 Google 可视化 API 公开的对象,以及所有可视化图表提供的标准方法。

注意:Google 可视化图表 API 命名空间为google.visualization.*

数组备注

某些浏览器无法正确处理 JavaScript 数组中尾随的逗号,因此请勿使用。 数组中间没有空值。例如:

data = ['a','b','c', ,]; // BAD
data = ['a','b','c'];   // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.

DataTable 类

表示二维的可变值表。如需创建 DataTable 的只读副本(可选择过滤以显示特定值、行或列),请创建 DataView

每一列都会分配一种数据类型,以及几个可选属性,包括 ID、标签和模式字符串。

此外,您还可以向任何单元格、行、列或整个表分配自定义属性(名称/值对)。某些可视化图表支持特定的自定义属性;例如,表可视化图表支持名为“style”的单元格属性,您可以通过该属性为所呈现的表单元格分配内嵌 CSS 样式字符串。可视化图表应在其文档中描述它支持的所有自定义属性。

另请参阅QueryResponse.getDataTable

构造函数

语法

DataTable(opt_data, opt_version)

优化数据
[可选] 用于初始化表的数据。这可以是对填充的表调用 DataTable.toJSON() 返回的 JSON,也可以是包含用于初始化表的数据的 JavaScript 对象。此处对 JavaScript 字面量对象的结构进行了说明。如果未提供此参数,将返回一个新的空数据表。
opt_version
[可选] 一个数值,用于指定所用传输协议的版本。仅供图表工具数据源实现者使用。当前版本为 0.6。

详细说明

DataTable 对象用于保存传入可视化图表的数据。DataTable 是基本的二维表格。每一列中的所有数据都必须具有相同的数据类型。每列都有一个描述符,其中包含其数据类型、该列的标签(可能在可视化图表中显示)和 ID(可用于引用特定列,这是使用列索引的替代方法)。DataTable 对象还支持任意赋给特定值、行、列或整个 DataTable 的映射。可视化图表可以使用这些实现支持其他功能;例如,表可视化图表可以使用自定义属性,让您为各个单元格分配任意类名称或样式。

表中的每个单元格都包含一个值。单元可以具有 null 值,也可以具有由其列指定的类型的值。单元格可以根据需要获取“格式化”版本的数据;这是字符串的数据版本,其格式已被可视化以显示。 可视化图表可以使用(但并非必须)使用格式化版本进行显示,但始终会使用其数据本身进行任何排序或计算(例如确定在图表中的放置位置)。例如,您可以将格式化值“低”、“中”和“高”分配给数字单元格值 1、2 和 3。

如需在调用构造函数后添加数据行,可以为单行调用 addRow(),也可以为多行调用 addRows()。您也可以通过调用 addColumn() 方法来添加列。行和列也有移除方法,但考虑创建一个 DataView,作为 DataTable 选择性视图,而不是移除行或列。

如果您在将 DataTable 传递到可视化图表的 draw() 方法后更改其中的值,则这些更改不会立即更改图表。您必须再次调用 draw() 才能反映任何更改。

注意:Google 图表不会对数据表执行任何验证。(如果包含,则渲染速度会更慢。)如果您提供的数字是您的列需要的字符串,反之亦然。Google 图表会尽力以有意义的方式解读该值,但不会标记错误。

示例

以下示例演示了如何使用字面量字符串实例化和填充 DataTable,并使用与上述 JavaScript 示例相同的数据:

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

以下示例会创建一个新的空 DataTable,然后使用与上面相同的数据手动将其填充:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);
我应该使用 JavaScript 或对象字面量表示法创建 DataTable 吗?

如需创建 DataTable,您可以调用不带参数的构造函数,然后调用下文列出的 addColumn()/addRows() 方法添加值,或者传入已填充的 JavaScript 字面量对象以对其进行初始化。下文介绍了这两种方法。您应该使用哪种方式?

  • 通过调用 addColumn()addRow()addRows(),在 JavaScript 中创建和填充表是非常易读的代码。当您手动输入代码时,此方法很有用。速度慢于使用对象字面量表示法(如下文所述),但在较小的表格中(例如 1000 个单元格)中,您可能不会注意到太多变化。
  • 在大型表中,使用对象字面量表示法直接声明 DataTable 对象要快得多。但是,这可能是一项棘手的语法;如果您可以在代码中生成对象字面量语法,则可以使用此语法,这样可以降低出错的可能性。

 

方法

方法 返回值 说明

addColumn(type, opt_label, opt_id)

addColumn(description_object)

数字

向数据表添加新列,然后返回新列的索引。系统会为新列的所有单元格分配 null 值。此方法有两个签名:

第一个签名具有以下参数:

  • type - 包含列值数据类型的字符串。类型可以是以下项之一:'string', 'number', 'boolean', 'date', 'datetime','timeofday'.
  • opt_label - [可选] 带有列标签的字符串。列标签通常显示为可视化图表的一部分,例如,显示为表中的列标题,或饼图中的图例标签。如果未指定值,则会分配空字符串。
  • opt_id - [可选] ] 列的唯一标识符的字符串。如果未指定值,则会分配空字符串。

第二个签名有一个对象参数,其中具有以下成员:

  • type - 描述列数据类型的字符串。与上述 type 的值相同。
  • label - [可选,字符串] 列的标签。
  • id - [可选,字符串] 列的 ID。
  • role - [可选,字符串] 列的角色
  • pattern - [可选,字符串] 一个数字(或日期)格式字符串,用于指定如何显示列值。

另请参阅getColumnIdgetColumnLabelgetColumnTypeinsertColumngetColumnRole

addRow(opt_cellArray) 数字

向数据表添加新行,并返回新行的索引。

  • opt_cellArray [可选] 一个行对象(采用 JavaScript 表示法),用于指定新行的数据。如果未添加此参数,此方法将仅在表格末尾添加新的空行。此参数是单元格值数组:如果您只想为单元格指定一个值,只需提供单元格值(例如 55 或“hello”即可);如果您想要为单元格指定格式化值和/或属性,请使用单元格对象(例如,{v:55, f:'Fifty-five'})。您可以在同一方法调用中混用简单值和单元格对象)。对于空单元格,请使用 null 或空数组条目。

示例

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.
addRows(numOrArray) 数字

向数据表添加新行,并返回最后添加行的索引。您可以调用此方法来新建空行,也可以使用用于填充行的数据(如下所述)。

  • numOrArray - 数字或数组:
    • Number - 一个数字,用于指定要添加多少未填充的新行。
    • Array - 用于填充一组新行的 row 对象的数组。每行都是一个对象,如 addRow() 中所述。对于空单元格,请使用 null 或空数组条目。

示例

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

另请参阅insertRows

clone() 数据表 返回数据表的克隆。结果是数据表的深度副本,但单元格属性行属性表属性列属性是浅层副本;这意味着非原始属性通过引用复制,但原始属性按值复制。
getColumnId(columnIndex) 字符串 返回由底层表中的列索引指定的给定列的标识符。
对于通过查询检索的数据表,列标识符由数据源设置,并可在使用查询语言时用于引用列。
另请参阅Query.setQuery
getColumnIndex(columnIdentifier) 字符串、数字 返回由此表中的索引(即列索引、ID 或标签)指定的给定列的索引,否则返回 -1。如果 columnIdentifier 是一个字符串,则用于先按 ID 查找列,然后再按标签查找列。
另请参阅getColumnIdgetColumnLabel
getColumnLabel(columnIndex) 字符串 返回由底层表中的列索引指定的给定列的标签。
列标签通常在可视化图表中显示。例如,列标签可以显示为表中的列标题,也可以显示为饼图中的图例标签。
对于通过查询检索的数据表,列标签由数据源或查询语言label 子句设置。
另请参阅setColumnLabel
getColumnPattern(columnIndex) 字符串

返回用于设置指定列值的格式。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

对于通过查询检索的数据表,列模式由数据源或查询语言的 format 子句设置。模式的示例为 '#,##0.00'。如需详细了解模式,请参阅查询语言参考文档

getColumnProperties(columnIndex) 对象

返回指定列中所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在 DataTable 中更改这些值。

  • columnIndex 是要为其检索属性的列的数字索引。
getColumnProperty(columnIndex, name) 自动

返回已命名属性的值,如果未为指定的列设置此类属性,则返回 null。返回类型因属性而异。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • name 是以字符串表示的属性名称。

另请参阅setColumnProperty setColumnProperties

getColumnRange(columnIndex) 对象

返回指定列中值的最小值和最大值。返回的对象具有 minmax 属性。如果范围没有值,minmax 将包含 null

columnIndex 应为大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

getColumnRole(columnIndex) 字符串 返回指定列的角色
getColumnType(columnIndex) 字符串

返回列索引指定的给定列的类型。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

返回的列类型可以是以下项之一:'string', 'number', 'boolean', 'date', 'datetime','timeofday'

getDistinctValues(columnIndex) 对象数组

以升序返回特定列中的唯一值。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

返回对象的类型与 getValue 方法返回的类型相同。

getFilteredRows(filters) 对象数组

返回与所有给定过滤条件匹配的行的行索引。索引按升序返回。此方法的输出可用作 DataView.setRows() 的输入,以更改可视化图表中显示的行集。

filters - 用于描述可接受的单元格值的对象数组。此方法返回与所有给定过滤条件都匹配的行索引。每个过滤条件都是一个具有数字 column 属性的对象,可指定要评估的行中的列索引以及以下各项之一:

  • value 属性,其值必须与指定列中的单元格完全匹配。值必须与列的类型相同;
  • 以下属性之一或两个,与所过滤的列的类型相同:
    • minValue - 单元格的最小值。指定列中的单元格值必须大于或等于此值。
    • maxValue - 单元格的最大值。指定列中的单元格值必须小于或等于此值。
    minValue(或 maxValue)的值为 null 或未定义,这意味着不会强制执行范围的下限(或上限)。

另一个可选属性 test 用于指定要与值或范围过滤结合使用的函数。使用单元格值、行和列索引以及数据表调用该函数。如果应从结果中排除该行,则应返回 false。

示例getFilteredRows([{column: 3, value: 42}, {column: 2, minValue: 'bar', maxValue: 'foo'}, {column: 1, test: (value, rowId, columnId, datatable) => { return value == "baz"; }}]) 返回一个数组,该数组按升序排列第四列(列索引 3)正好为 42 且第三列(列索引 2)介于“bar”和“foo”(含)之间的所有行的索引。

getFormattedValue(rowIndex, columnIndex) 字符串

根据指定的行和列索引,返回单元格的格式化值。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • ColumnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

如需详细了解如何设置列值的格式,请参阅查询语言参考文档

另请参阅setFormattedValue

getNumberOfColumns() 数字 返回表中的列数。
getNumberOfRows() 数字 返回表中的行数。
getProperties(rowIndex, columnIndex) 对象

返回指定单元格内所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在 DataTable 中更改这些值。

  • rowIndex 是单元格的行索引。
  • columnIndex 是单元格的列索引。
getProperty(rowIndex, columnIndex, name) 自动

返回指定属性的值,如果指定的单元格未设置该属性,则返回 null。返回类型因属性而异。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • name 是包含属性名称的字符串。

另请参阅setCell setProperties setProperty

getRowProperties(rowIndex) 对象

返回指定行中所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在 DataTable 中更改这些值。

  • rowIndex 是要检索其属性的行的索引。
getRowProperty(rowIndex, name) 自动

返回已命名属性的值,如果未为指定行设置此类属性,则返回 null。返回类型因属性而异。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • name 是包含属性名称的字符串。

另请参阅setRowProperty setRowProperties

getSortedRows(sortColumns) 数字数组

返回经过排序的表版本,而不修改底层数据的顺序。 如需对基础数据进行永久排序,请调用 sort()。您可以通过多种方式指定排序,具体取决于您传入 sortColumns 参数的类型:

  • 单个数字指定要排序的列的索引。将按升序排序。示例sortColumns(3) 将按第 4 列升序排列。
  • 单个对象,其中包含排序所依据的列索引号,以及可选的布尔值属性 desc。如果 desc 设置为 true,则特定列将按降序排序;否则,按升序排序。示例sortColumns({column: 3}) 将根据第 4 列升序排列;sortColumns({column: 3, desc: true}) 将根据第 4 列按降序排序。
  • 一组索引数组,用于对列索引进行排序。第一个数字是排序依据的主要列,第二个数字是次要列,依此类推。 这意味着,当第一列中的两个值相等时,系统会对下一列中的值进行比较,依此类推。示例sortColumns([3, 1, 6]) 将依次按第 4 列(升序)、第 2 列(升序)以及第 7 列(升序)排序。
  • 对象的数组,其中每个对象都具有用于排序的列索引编号以及可选的布尔值属性 desc。如果 desc 设置为 true,则特定列将按降序排列(默认为按升序排列)。第一个对象是排序依据的主要列,第二个对象是辅助列,依此类推。这意味着,当第一列中的两个值相等时,系统会对下一列中的值进行比较,依此类推。示例sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}]) 将先按第 4 列(升序)排序,然后按降序排序第 2 列,然后按降序排序第 7 列。

返回的值是一个数字数组,每个数字都是一个 DataTable 行的索引。按返回数组的顺序迭代 DataTable 行将导致按指定 sortColumns 排序。输出可用作 DataView.setRows() 的输入,以快速更改可视化图表中显示的一组行。

请注意,排序一定是稳定的:这意味着,如果您按两行相等的值排序,则同一排序将每次都以相同的顺序返回行。
另请参阅排序

示例:如需遍历按第三列排序的行,请使用以下命令:

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}
getTableProperties 对象 返回表中所有属性的映射。
getTableProperty(name) 自动

返回已命名属性的值,如果未为表设置此类属性,则返回 null。返回类型因属性而异。

  • name 是包含属性名称的字符串。

另请参阅setTableProperties setTableProperty

getValue(rowIndex, columnIndex) 对象

返回单元格在给定行索引和列索引处的值。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。

返回值的类型取决于列类型(请参阅 getColumnType):

  • 如果列类型为“字符串”,则值为字符串。
  • 如果列类型为“数字”,则值为数字。
  • 如果列类型为“布尔值”,则值为布尔值。
  • 如果列类型是“日期”或“日期时间”,则值是日期对象。
  • 如果列类型为“timeofday”,则值是一个由四个数字构成的数组:[小时、分钟、秒、毫秒]。
  • 如果单元格值为 null 值,则返回 null
insertColumn(columnIndex, type [,label [,id]])

向特定表中的数据表插入新列。指定索引处或之后的所有现有列都会转移到索引更高。

  • columnIndex 是一个具有新列所需索引的数字。
  • type 应该是包含列值数据类型的字符串。类型可以是以下项之一:'string', 'number', 'boolean', 'date', 'datetime','timeofday'.
  • label 应该是带有列标签的字符串。列标签通常作为可视化图表的一部分显示,例如显示为表中的列标题,或饼图中的图例标签。如果未指定值,则会分配空字符串。
  • id 应该是列的唯一标识符。如果未指定值,则会分配空字符串。

另请参阅addColumn

insertRows(rowIndex, numberOrArray)

在指定的行索引处插入指定的行数。

  • rowIndex 是插入新行的索引编号。系统将从指定索引编号处开始添加行。
  • numberOrArray 是要添加的多个空行,或者要在索引处添加的一个或多个填充的行的数组。如需了解如何添加行对象的数组,请参阅 addRows()

另请参阅addRows

removeColumn(columnIndex)

移除指定索引处的列。

  • columnIndex 应为具有有效列索引的数字。

另请参阅removeColumns

removeColumns(columnIndex, numberOfColumns)

从指定索引处的列移除指定数量的列。

  • numberOfColumns 是要移除的列数。
  • columnIndex 应为具有有效列索引的数字。

另请参阅removeColumn

removeRow(rowIndex)

移除指定索引处的行。

  • rowIndex 应为具有有效行索引的数字。

另请参阅removeRows

removeRows(rowIndex, numberOfRows)

从指定索引处的行中移除指定的行数。

  • numberOfRows 是要移除的行数。
  • rowIndex 应为具有有效行索引的数字。

另请参阅removeRow

setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])

设置单元格的值、格式值和/或属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • value [可选] 是分配给指定单元格的值。为避免覆盖此值,请将此参数设置为 undefined;如需清除此值,请将其设置为 null。值的类型取决于列类型(请参阅 getColumnType()):
    • 如果列类型为“字符串”,则值应为字符串。
    • 如果列类型为“数字”,则值应为数字。
    • 如果列类型为“布尔值”,则值应为布尔值。
    • 如果列类型为“日期”或“日期时间”,则值应为日期对象。
    • 如果列类型为“timeofday”,则值应该是包含四个数字的数组:[小时、分钟、秒、毫秒]。
  • formattedValue [可选] 是一个字符串,其值采用字符串格式。为避免覆盖此值,请将此参数设置为 undefined;如需清除此值并让 API 根据需要将默认格式应用于 value,请将其设置为 null;如需明确设置格式为空的值,请将其设置为空字符串。可视化图表通常会使用格式化值来显示值标签。例如,格式化值可以作为饼图中的标签文本显示。
  • properties [可选] 是具有此单元格额外属性的 Object(名称/值映射)。为避免覆盖此值,请将此参数设置为 undefined;如需清除此值,请将其设置为 null。 某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

另请参阅setValue()setFormattedValue()setProperty()setProperties()

setColumnLabel(columnIndex, label)

设置列的标签。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • label 是一个字符串,其中包含要分配给该列的标签。列标签通常在可视化图表中显示。例如,列标签可以显示为表中的列标题,也可以显示为饼图中的图例标签。

另请参阅getColumnLabel

setColumnProperty(columnIndex, name, value)

设置单列属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • name 是包含属性名称的字符串。
  • value 是要分配给指定列的指定命名属性的任意类型的值。

另请参阅setColumnProperties getColumnProperty

setColumnProperties(columnIndex, properties)

设置多个列属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • properties 是一个 Object(名称/值映射),其中包含此列的其他属性。如果指定了 null,则该列的所有其他属性都将被移除。

另请参阅setColumnProperty getColumnProperty

setFormattedValue(rowIndex, columnIndex, formattedValue)

设置单元格的格式化值。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • formattedValue 是一个字符串,其值采用设置为显示的格式。如需清除此值并让 API 根据需要将默认格式应用于单元格值,请将其设置为 formattedValue null;如需明确设置格式为空的值,请将其设置为空字符串。

另请参阅getFormattedValue

setProperty(rowIndex, columnIndex, name, value)

设置单元格属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • name 是包含属性名称的字符串。
  • value 是要分配给指定单元格的指定命名属性的任意类型的值。

另请参阅setCell setProperties getProperty

setProperties(rowIndex, columnIndex, properties)

设置多个单元格属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。
  • properties 是一个 Object(名称/值映射),其中包含此单元格的其他属性。如果指定了 null,系统会移除该单元格的所有附加属性。

另请参阅setCell setProperty getProperty

setRowProperty(rowIndex, name, value)

设置行属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • name 是包含属性名称的字符串。
  • value 是要分配给指定行指定命名属性的任意类型的值。

另请参阅setRowProperties getRowProperty

setRowProperties(rowIndex, properties)

设置多个行属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化文档,了解受支持的属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • properties 是具有此行的附加属性的 Object(名称/值映射)。如果指定了 null,则系统会移除该行的所有其他属性。

另请参阅setRowProperty getRowProperty

setTableProperty(name, value)

设置单个表属性。某些可视化功能支持通过表格、行、列或单元格属性来修改其显示方式或行为;如需了解哪些属性受支持,请参阅可视化文档。

  • name 是包含属性名称的字符串。
  • value 是要分配给表的指定属性的任意类型的值。

另请参阅setTableProperties getTableProperty

setTableProperties(properties)

设置多个表属性。某些可视化功能支持通过表格、行、列或单元格属性来修改其显示方式或行为;如需了解哪些属性受支持,请参阅可视化文档。

  • properties 是具有表的其他属性的 Object(名称/值映射)。如果指定了 null,表的所有附加属性都将被移除。

另请参阅setTableProperty getTableProperty

setValue(rowIndex, columnIndex, value)

设置单元格的值。除了覆盖任何现有的单元值外,此方法还会清除该单元的任何格式化值和属性。

  • rowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。
  • columnIndex 应是大于或等于零,且小于 getNumberOfColumns() 方法返回的列数。此方法不允许您为此单元格设置格式化值;为此,请调用 setFormattedValue()
  • value 是分配给指定单元格的值。返回值的类型取决于列类型(请参阅 getColumnType):
    • 如果列类型为“字符串”,则值应为字符串。
    • 如果列类型为“数字”,则值应为数字。
    • 如果列类型为“布尔值”,则值应为布尔值。
    • 如果列类型为“日期”或“日期时间”,则值应为日期对象。
    • 如果列类型为“timeofday”,则值应该是包含四个数字的数组:[小时、分钟、秒、毫秒]。
    • 对于任何列类型,该值设置为 null

另请参阅:setCellsetFormattedValuesetPropertysetProperties

sort(sortColumns) 根据指定的排序列对行进行排序。此方法会修改 DataTable。有关排序详细信息的说明,请参阅 getSortedRows()。此方法不会返回已排序的数据。
另请参阅getSortedRows
示例:要先按第三列排序,然后再按第二列排序,请使用:data.sort([{column: 2}, {column: 1}]);
toJSON() 字符串 返回可传入 DataTable 构造函数DataTable 的 JSON 表示法。例如:
{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

构造函数的 JavaScript 字面量数据参数的格式

您可以通过将 JavaScript 字符串字面量对象传递到 data 参数来初始化 DataTable。我们将该对象称为 data 对象。您可以根据以下说明手动编写此对象;如果您知道如何使用 Python,也可使用帮助程序 Python 库,并且您的网站可以使用它。不过,如果您希望手动构建对象,本部分将介绍语法。

首先,我们来看一个简单的 JavaScript 对象示例,该对象介绍了一个包含三行三列的表(字符串、数字和日期类型):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

现在,我们来描述语法:

data 对象包含两个必需的顶级属性 colsrows,以及一个可选的 p 属性,该属性是任意值的映射。

注意:显示的所有属性名称和字符串常量都区分大小写。此外,被描述为采用字符串值的属性应将其值括在引号中。例如,如果要将类型属性指定为数字,可以按如下方式表示:type: 'number';但值本身(数字)可以表示为:v: 42

cols 属性

cols 是描述每列的 ID 和类型的对象数组。每个属性都是一个具有以下属性的对象(区分大小写):

  • type [必需] 列中数据的数据类型。支持以下字符串值(示例包括 v: 属性,将在后面介绍):
    • 'boolean' - JavaScript 布尔值(“true”或“false”)。示例值v:'true'
    • 'number' - JavaScript 数值。示例值v:7v:3.14v:-55
    • “string”- JavaScript 字符串值。示例值v:'hello'
    • 'date' - JavaScript 日期对象(从零开始的月份),时间被截断。示例值v:new Date(2008, 0, 15)
    • 'date' - 包含时间的 JavaScript 日期对象。示例值v:new Date(2008, 0, 15, 14, 30, 45)
    • 'timeofday' - 一个包含三个数字的数组和一个可选的第四个数字,表示小时(0 表示午夜)、分钟、秒和可选毫秒。示例值v:[8, 15, 0]v: [6, 12, 1, 144]
  • id [可选] 列的字符串 ID。不得重复。请使用基本的字母数字字符,因此托管网页无需使用花哨的转义字符即可通过 JavaScript 访问此列。请注意不要选择 JavaScript 关键字。示例id:'col_1'
  • label [可选] 某些可视化图表为此列显示的字符串值。示例label:'Height'
  • pattern [可选] 数据源用来设置数字、日期或时间列值格式的字符串模式。这些信息仅供参考;您可能不需要读取该模式,也不存在此模式。Google 可视化客户端不使用此值(它会读取单元格的格式化值)。如果 DataTable 来自数据源以响应带有 format 子句的查询,那么您在该子句中指定的模式可能会返回此值。推荐的模式标准是 ICU DecimalFormatSimpleDateFormat
  • p [可选] 一个对象,是应用于单元格的自定义值的映射。这些值可以是任何 JavaScript 类型。如果您的可视化图表支持任何单元格级属性,则会对其进行说明;否则,系统会忽略此属性。 示例p:{style: 'border: 1px solid green;'}

cols 示例

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

rows 属性

rows 属性存储了行对象的数组。

每个行对象都有一个名为 c 的必需属性,该属性是该行中的单元格数组。它还具有一个可选的 p 属性,用于定义要分配给整行的任意自定义值的映射。如果您的可视化图表支持任何行级属性,则会对其进行说明;否则,系统会忽略此属性。

单元格对象

表中的每个单元格都由具有以下属性的对象描述:

  • v [可选] 单元格值。数据类型应与列数据类型相匹配。如果单元格为 null,v 属性应为 null,但仍然可以具有 fp 属性。
  • f [可选] v 值的字符串版本,采用适合显示的格式。通常,这些值将匹配,但并非必须匹配,因此,如果您为 v 指定 Date(2008, 0, 1),则应为此属性指定“2008 年 1 月 1 日”或此类字符串。系统不会针对 v 值检查此值。可视化图表不会将此值用于计算,而仅用作显示的标签。如果省略此参数,系统会使用默认格式化程序自动生成 v 的字符串版本。您可以使用自己的格式化程序修改 f 值,也可以使用 setFormattedValue()setCell() 设置值,也可以使用 getFormattedValue() 检索值。
  • p [可选] 一个对象,是应用于单元格的自定义值的映射。这些值可以是任何 JavaScript 类型。如果您的可视化图表支持任何单元格级属性,则会对其进行说明。您可以通过 getProperty()getProperties() 方法检索这些属性。示例p:{style: 'border: 1px solid green;'}

行数组中的单元格应与其在 cols 中的列说明顺序相同。如需指示 null 单元格,您可以指定 null,将数组中的单元格留空,或省略尾随数组成员。因此,如需为前两个单元格指明包含 null 的行,可以指定 [ , , {cell_val}][null, null, {cell_val}]

下面是一个包含三列并填充了三行数据的表格对象示例:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

p 属性

表级 p 属性是应用于整个 DataTable 的自定义值的映射。这些值可以是任何 JavaScript 类型。如果您的可视化图表支持任何数据表级属性,则会对其进行说明;否则,此属性将可供应用使用。 示例p:{className: 'myDataTable'}

DataView 类

底层 DataTable 的只读视图。DataView 只允许选择列和/或行的子集。它还支持对列/行重新排序以及复制列/行。

视图是底层 DataTable 上的实时窗口,而不是数据的静态快照。但是,在更改表本身的结构时,仍请务必小心,如下所述:

  • 在底层表中添加或移除不会反映视图,并且可能导致视图中出现意外行为;您必须从 DataTable 创建新的 DataView 才能获取这些更改。
  • 为底层表添加或移除行是安全的,更改将立即传播到视图(但是,在此项更改后,您必须为任何可视化图表调用 draw() 才能呈现新行集)。请注意,如果您的视图已通过调用某个 setRows() or hideRows() 方法过滤掉行,并且您向底层表添加了行或从中移除行,则行为会发生异常;您必须创建新的 DataView 以反映新表。
  • 更改现有单元格中的单元格值是安全的,更改会立即传播到 DataView(但是,在此项更改后,您必须对任何可视化图表调用 draw(),才能呈现新的单元格值)。

也可以基于其他 DataView 创建 DataView。请注意,每当提到底层表格或视图时,它指的是相应级别的正下方。换言之,它指的是用于构造此 DataView 的数据对象。

DataView 还支持计算列;这些列是使用您提供的函数实时计算的值。例如,您可以包含一个列(前两列的总和),也可以计算另一个列中的日期(日历日期的四分之一)。如需了解详情,请参阅 setColumns()

如果您通过隐藏或显示行或列来修改 DataView,那么在您再次对可视化图表调用 draw() 之前,可视化图表不会受到影响。

您可以将 DataView.getFilteredRows()DataView.setRows() 结合使用,以创建包含有趣数据子集的 DataView,如下所示:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

构造函数

您可以通过以下两种方式创建新的 DataView 实例:

构造函数 1

var myView = new google.visualization.DataView(data)
data
用于初始化视图的 DataTableDataView。默认情况下,该视图会按原始顺序包含底层数据表或视图中的所有列和行。如需在此视图中隐藏或显示行或列,请调用相应的 set...()hide...() 方法。

另见:

setColumns()hideColumns()setRows()hideRows()

 

构造函数 2

此构造函数通过将序列化 DataView 分配给 DataTable 来创建一个新的 DataView。它可以帮助您重新创建使用 DataView.toJSON() 序列化的 DataView

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)
数据
您用于创建 DataView 且调用 DataView.toJSON()DataTable 对象。如果此表与原始表有任何不同,您将收到不可预测的结果。
viewAsJson
DataView.toJSON() 返回的 JSON 字符串。本部分介绍如何在 data DataTable 中显示或隐藏某些行。

方法

方法 返回值 说明
请参阅 DataTable 中的说明。 与等效的 DataTable 方法相同,只是行/列索引引用了视图(而不是底层表/视图)中的索引。
getTableColumnIndex(viewColumnIndex) 数字

返回由给定视图(此视图的索引)指定的指定表(或视图)中的索引。viewColumnIndex 应为大于或等于零的数字,并小于 getNumberOfColumns() 方法返回的列数。如果这是生成的列,则返回 -1。

示例:如果之前调用过 setColumns([3, 1, 4])getTableColumnIndex(2) 将返回 4

getTableRowIndex(viewRowIndex) 数字

返回由该行的索引在此视图指定的给定表(或视图)中的索引。viewRowIndex 应是大于或等于零,且小于 getNumberOfRows() 方法返回的行数。

示例:如果之前调用过 setRows([3, 1, 4])getTableRowIndex(2) 将返回 4

getViewColumnIndex(tableColumnIndex) 数字

返回此视图中的索引,该索引映射到其在底层表(或视图)中的索引指定的给定列。如果存在多个这样的索引,则返回第一个(最小)索引。如果不存在此类索引(指定的列不在视图中),则返回 -1。 tableColumnIndex 应为大于或等于零,且小于底层表/视图的 getNumberOfColumns() 方法返回的列数。

示例:如果之前调用过 setColumns([3, 1, 4])getViewColumnIndex(4) 将返回 2

getViewColumns() 数字数组

按顺序返回此视图中的列。也就是说,如果您使用某个数组调用 setColumns,然后调用 getViewColumns(),应该就会得到一个相同的数组。

getViewRowIndex(tableRowIndex) 数字

返回此视图中的索引,该索引映射到其在底层表(或视图)中的索引指定的给定行。如果存在多个这样的索引,则返回第一个(最小)索引。如果不存在此类索引(指定的行不在视图中),则返回 -1。 tableRowIndex 应为大于或等于零,且小于底层表/视图的 getNumberOfRows() 方法返回的行数。

示例:如果之前调用过 setRows([3, 1, 4])getViewRowIndex(4) 将返回 2

getViewRows() 数字数组

按顺序返回此视图中的行。也就是说,如果您使用某个数组调用 setRows,然后调用 getViewRows(),应该就会得到一个相同的数组。

hideColumns(columnIndexes)

在当前视图中隐藏指定的列。columnIndexes 是一个数字数组,表示要隐藏的列的索引。这些索引是底层表/视图中的索引编号。columnIndexes 中的数字不必按顺序排列(即 [3,4,1] 没有问题)。当您遍历每一列时,将保留其索引顺序。输入已隐藏列的索引编号不会出现错误,但如果输入底层表/视图中不存在的索引,则会引发错误。如需取消隐藏列,请调用 setColumns()

示例:如果您的表包含 10 列,并且依次调用 setColumns([2,7,1,7,9])hideColumns([7,9]),那么视图中的列将为 [2,1]。

hideRows(min, max)

从当前视图中隐藏索引介于介于最小值和最大值(含)之间的所有行。 这是 hideRows(rowIndexes) 的便捷语法。例如,hideRows(5, 10) 等同于 hideRows([5, 6, 7, 8, 9, 10])

hideRows(rowIndexes)

在当前视图中隐藏指定行。rowIndexes 是一个数字数组,表示要隐藏的行的索引。这些索引是底层表/视图中的索引编号。rowIndexes 中的数字不必按顺序排列(即 [3,4,1] 没有问题)。其余行仍保留其索引顺序。为已隐藏的行输入索引编号不是错误,但如果输入底层表/视图中不存在的索引,则会抛出错误。如需取消隐藏行,请调用 setRows()

示例:如果您的表包含 10 行,您依次调用 setRows([2,7,1,7,9])hideRows([7,9]),那么视图中的行将为 [2,1]。

setColumns(columnIndexes)

指定哪些视图会显示在此视图中。所有未指定的列都将被隐藏。 这是底层表/视图中的列索引的数组,或计算列。如果您不调用此方法,则默认显示所有列。该数组还可以包含重复项,以便多次显示同一列。列将按照指定的顺序显示。

  • columnIndexes - 一组数字和/或对象(可以混合使用):
    • 数字用于指定要包含在视图中的源数据列的索引。数据未经修改就保留。如果您需要明确定义角色或其他列属性,请使用 sourceColumn 属性指定对象。
    • 对象用于指定计算列。计算列会即时为每行创建一个值并将其添加到视图。该对象必须具有以下属性:
      • calc [函数] - 为列中的每一行调用的函数,用于计算该单元格的值。函数签名为 func(dataTable, row),其中 dataTable 是源 DataTablerow 是源数据行的索引。该函数应返回一个由 type 指定的类型的值。
      • type [字符串] - calc 函数返回的值的 JavaScript 类型。
      • label [可选,字符串] - 要分配给此生成的列的可选标签。如果未指定,则视图列将不包含任何标签。
      • id [可选,string] - 要分配给此生成的列的可选 ID。
      • sourceColumn - [可选,数字] 用作值的源列;如果指定,则不指定 calctype 属性。这类似于传入数字而不是对象,但允许您为新列指定角色和属性。
      • properties [可选object] - 一个对象,包含要分配给此列的任意属性。如果未指定,则视图列将不包含任何属性。
      • role [可选,字符串] - 要分配给此列的角色如果未指定,则不导入现有角色。

示例

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}
setRows(min, max)

将此视图中的行设置为介于最小值和最大值(含边界值)之间的所有索引(位于底层表/视图中)。以下是 setRows(rowIndexes) 的便捷语法。例如,setRows(5, 10) 等同于 setRows([5, 6, 7, 8, 9, 10])

setRows(rowIndexes)

根据底层表/视图中的索引编号,设置此视图中可见的行。rowIndexes 应为一个索引数组,指定要在视图中显示哪些行。该数组指定显示行的顺序,并且可以复制行。请注意,系统只会显示 rowIndexes 中指定的行;此方法会清除视图中的所有其他行。该数组还可以包含重复项,从而有效地复制此视图中的指定行(例如,setRows([3, 4, 3, 2]) 会导致 3 行在此视图中出现两次)。因此,该数组提供了从底层表/视图到此视图的行的映射。您可以使用 getFilteredRows()getSortedRows() 为此方法生成输入。

示例:如需创建具有底层表/视图第 3 行和零行的视图,请执行以下操作:view.setRows([3, 0])

toDataTable() 数据表 返回 DataTable 对象,其中填充了 DataView 的可见行和列。
toJSON() 字符串 返回此 DataView 的字符串表示法。此字符串不包含实际数据;仅包含 DataView 专用设置,例如可见行和列。您可以存储此字符串并将其传递给静态 DataView.fromJSON() 构造函数以重新创建此视图。其中不包括生成的列

Chart 封装容器类

ChartWrapper 类用于封装图表,并处理图表的所有加载、绘制和数据源查询。此类公开了在图表上设置值并进行绘制的便捷方法。此类有助于简化从数据源读取数据的操作,因为您无需创建查询回调处理程序。您还可以用它来轻松保存图表,以便重复使用。

使用 ChartWrapper 的另一个好处是,您可以通过动态加载来减少库加载次数。此外,您无需明确加载软件包,因为 ChartWrapper 将为您查找和加载图表软件包。 请查看以下示例了解详情。

但是,ChartWrapper 目前仅传播图表抛出的那部分事件:select、ready 和 error。其他事件不会通过 Chart 封装容器实例传输;如需获取其他事件,您必须调用 getChart() 并直接在图表句柄上订阅事件,如下所示:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

构造函数

ChartWrapper(opt_spec)
opt_spec
[可选] - 定义图表的 JSON 对象或该对象的序列化字符串版本。drawChart() 文档中显示了此对象的格式。如果未指定,您必须使用此对象公开的 set... 方法来设置所有适当的属性。

方法

Chart 封装容器提供了以下附加方法:

方法 返回值类型 说明
draw(opt_container_ref)

绘制图表。您必须对图表或数据进行任何更改后调用此方法,才能显示更改。

  • opt_container_ref [可选] - 对页面上有效容器元素的引用。如果指定,图表将绘制在其中。否则,图表将在由 containerId 指定的 ID 的元素中绘制。
toJSON() 字符串 返回图表的 JSON 表示法的字符串版本。
clone() 图表封装容器 返回图表封装容器的深层副本。
getDataSourceUrl() 字符串 如果此图表从数据源获取数据,则返回此数据源的网址。否则,返回 null。
getDataTable() google.visualization.DataTable

如果此图表从本地定义的 DataTable 获取数据,系统将返回对图表 DataTable 的引用。如果此图表从数据源获取数据,则返回 null。

下次返回 ChartWrapper.draw() 时,您对返回的对象所做的任何更改都会反映在图表中。

getChartType() 字符串 封装的图表的类名称。如果这是 Google 图表,则无法使用 google.visualization 限定名称。例如,如果这是一个树状图,则会返回“Treemap”,而不是“google.visualization.treemap”。
getChartName() 字符串 返回由 setChartName() 分配的图表名称。
getChart() 图表对象参考 返回对此 Chart 封装容器创建的图表的引用,例如 google.visualization.BarChart google.visualization.ColumnChart 。 在您针对 Chart 封装容器对象调用 draw() 之前,此方法将返回 null,并且会抛出就绪事件。对返回的对象调用的方法将反映在页面上。
getContainerId() 字符串 图表的 DOM 容器元素的 ID。
getQuery() 字符串 此图表的查询字符串(如果有),并查询数据源。
getRefreshInterval() 数字 此图表的任何刷新间隔(如果查询数据源)。零表示不刷新。
getOption(key, opt_default_val) 任何类型

返回指定的图表选项值

  • key - 要检索的选项的名称。可以是限定名称,例如 'vAxis.title'
  • opt_default_value [可选] - 如果指定的值未定义或为 null,则返回此值。
getOptions() 对象 返回此图表的选项对象。
getView() 对象或数组 返回 DataView 初始化程序对象,其格式与 dataview.toJSON() 相同,或者返回此类对象的数组。
setDataSourceUrl(url) 设置要用于此图表的数据源的网址。如果您还为此对象设置了数据表,则系统会忽略数据源网址。
setDataTable(table) 设置图表的 DataTable。传入以下其中一项:null;DataTable 对象;DataTable 的 JSON 表示法;或遵循 arrayToDataTable() 语法的数组。
setChartType(type) 设置图表类型。传入封装后的图表的类名称。如果这是 Google 图表,请勿使用 google.visualization 进行限定。例如,对于饼图,请传入“PieChart”。
setChartName(name) 为图表设置任意名称。除非自定义图表明确使用它,否则它不会显示在图表上的任何位置。
setContainerId(id) 为图表设置包含的 DOM 元素的 ID。
setQuery(query_string) 设置查询字符串(如果此图表查询数据源)。如果指定此值,您还必须设置数据源网址。
setRefreshInterval(interval) 如果此查询查询数据源,则设置此图表的刷新间隔。如果指定此值,您还必须设置数据源网址。零表示不刷新。
setOption(key, value) 设置单个图表选项值,其中 key 是选项名称,value 是值。如需取消设置某个选项,请为该值传入 null。请注意,key 可以是限定名称,例如 'vAxis.title'
setOptions(options_obj) 为图表设置完整的选项对象。
setView(view_spec) 设置 DataView 初始化程序对象,该对象可用作底层数据的过滤器。图表封装容器必须具有来自 DataTable 或数据源的底层数据,才能应用此视图。您可以传入字符串或 DataView 初始化程序对象,就像 dataview.toJSON() 返回的对象一样。您还可以传入由 DataView 初始化程序对象组成的数组,在这种情况下,该数组中的第一个 DataView 会应用于基础数据以创建新的数据表,而第二个 DataView 则会应用于因应用第一个 DataView 而产生的数据表,依此类推。

活动

Chart 封装容器对象会抛出以下事件。请注意,您必须先调用 ChartWrapper.draw(),然后才能抛出任何事件。

名称 说明 属性
error 尝试渲染图表出错时触发。 id、message
ready 此图表已准备好进行外部方法调用。如果您想与图表交互,并在绘制后调用方法,则应在调用 draw 方法之前为此事件设置监听器,并仅在事件触发后调用它们。
select 在用户点击条形或图例时触发。选择图表元素时,系统会选择数据表中的相应单元格;选择图例时,会选择数据表中的相应列。如需了解所选内容,请调用 ChartWrapper.getChart().getSelection()。请注意,仅当底层图表类型抛出选择事件时,系统才会抛出此事件。

示例

以下两个代码段可创建等效的折线图。第一个示例使用 JSON 字面量表示法定义图表;第二个示例使用 Chart 封装容器方法来设置这些值。

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

同一图表,现在使用 setter 方法:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

ChartEditor 类

ChartEditor 类用于打开页内对话框,让用户能够即时自定义可视化。

要使用 ChartEditor,请执行以下操作

  1. 加载 charteditor 软件包。google.charts.load() 中,加载软件包“charteditor”。您无需加载您在编辑器中呈现的图表类型的软件包;图表编辑器会根据需要为您加载所有软件包。
  2. 创建一个 ChartWrapper 对象,以定义可供用户自定义的图表。该图表将显示在对话框中,用户可以使用编辑器重新设计图表、更改图表类型,甚至更改源数据。
  3. 创建一个新的 ChartEditor 实例,并注册以监听“ok”事件。用户点击对话框中的“OK”按钮时,系统会抛出此事件。收到后,您应调用 ChartEditor.getChartWrapper() 来检索用户修改的图表。
  4. 调用 ChartEditor.openDialog(),并传入 ChartWrapper。系统随即会打开该对话框。对话框按钮使用户能够关闭编辑器。只要 ChartEditor 实例在范围内,该实例就会一直可用;它不会在用户关闭对话框后自动销毁。
  5. 要在代码中更新图表,请调用 setChartWrapper()

方法

方法 返回值 说明
openDialog(chartWrapper, opt_options) null

将图表编辑器作为页面上的嵌入式对话框打开。该函数会立即返回,不会等待对话框关闭。如果您未丢失实例的作用域,可以再次调用 openDialog() 以重新打开对话框,但您必须再次传入 Chart 封装容器对象。

  • chart 封装容器 - 一个 ChartWrapper 对象,用于定义要在窗口中呈现的初始图表。该图表必须具有填充的 DataTable,或已连接到有效的数据源。此封装容器会在内部复制到图表编辑器,因此您之后对 Chart 封装容器句柄所做的任何更改都不会反映在图表编辑器的副本中。
  • opt_options - [可选] 包含图表编辑器的任何选项的对象。请参阅下方的选项表。
getChartWrapper() ChartWrapper 返回表示图表的 ChartWrapper,其中包含用户修改。
setChartWrapper(chartWrapper) null

使用此方法可更新编辑器上呈现的图表。

chart 封装容器 - 一个 ChartWrapper 对象,代表要呈现的新图表。图表必须具有填充的 DataTable,或已连接到有效的数据源。

closeDialog() null 关闭图表编辑器对话框。

选项

图表编辑器支持以下选项:

名称 类型 默认 说明
dataSourceInput 元素句柄或“urlbox” null

使用此方法可让用户为图表指定数据源。此属性可以是以下两个值之一:

  • 'urlbox' - 在对话框的可修改文本框中显示图表的数据源网址。用户可以修改此图表,系统将根据新的数据源重新绘制图表。
  • DOM 元素 - 可让您提供用于选择数据源的自定义 HTML 元素。将一个句柄传递给 HTML 元素(无论是在代码中创建的,还是从页面复制的)。 此元素将显示在对话框中。可以借此让用户选择图表的数据源。例如,创建一个包含多个数据源网址或方便用户选择的名称列表的列表。 元素必须实现选择处理程序并用其更改图表的数据源:例如,更改底层 DataTable 或修改图表的 dataSourceUrl 字段。

活动

图表编辑器会抛出以下事件:

名称 说明 属性
ok 用户点击对话框中的“OK”按钮时触发。收到此方法后,您应调用 getChartWrapper() 来检索用户配置的图表。
cancel 用户点击对话框中的“取消”按钮时触发。

示例

以下示例代码会打开一个包含已填充折线图的图表编辑器对话框。如果用户点击“确定”,修改后的图表将保存到页面上的指定 <div> 中。

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

数据操纵方法

google.visualization.data 命名空间包含一些静态方法,用于对 DataTable 对象执行类似 SQL 的操作,例如联接它们或按列值分组。

google.visualization.data 命名空间提供以下方法:

方法 说明
google.visualization.data.group 执行 SQL GROUP BY 操作,以返回按指定列中的值分组的表。
google.visualization.data.join 联接一个或多个键列中的两个数据表。

group()

接受已填充的 DataTable 对象并执行类似于 SQL 的 GROUP BY 操作,返回包含按指定列值分组的行的表。请注意,这不会修改输入 DataTable

返回的表为指定键列中的值的每种组合各占一行。每行都包含键列,外加与匹配键匹配的所有行的汇总列值(例如,指定列中所有值的总和或计数)。

google.visualization.data 命名空间包含几个有用的聚合值(例如 sumcount),但您可以定义自己的聚合值(例如 standardDevification 或 secondHighest)。有关如何定义聚合器的说明将在方法说明后面提供。

语法

google.visualization.data.group(data_table, keys, columns)
数据表
输入 DataTable。这不会通过调用 group() 进行修改。
keys
一个数字和/或对象数组,用于指定作为分组依据的列。结果表包含此数组中的所有列,以及中的所有列。如果是一个数字,则此值为要分组的输入 DataTable 的列索引。如果对象为对象,则该函数将包括可以修改指定列的函数(例如,在该列中的值添加 1)。该对象必须具有以下属性:
  • column - 作为要应用转换的 dt 中的列索引的数字。
  • 修饰符 - 接受一个值(每行中相应单元格的值)并返回修改后的值的函数。此函数用于修改列值以辅助分组:例如,调用 whatQuarter 函数以根据日期列计算季度,这样 API 就可以按季度对行进行分组。计算得出的值将显示在返回的表的键列中。您可将此函数声明内嵌到此对象中,也可将其定义为在代码中其他位置定义的函数(它必须在调用范围内)。该 API 提供了一个简单的修饰符函数此处介绍了如何创建更实用的函数。您必须知道此函数可以接受的数据类型,并仅对该类型的列进行调用。您还必须知道此函数的返回类型,并在下文所述的 type 属性中声明此类型。
  • 类型 - 函数修饰符返回的类型。这应该是 JavaScript 字符串类型名称,例如“数字”或“布尔值”。
  • label - [可选] 字符串字符串,用于在返回的 DataTable 中分配此列。
  • id - [选填] 在返回的 DataTable 中分配此列的字符串 ID。

示例[0][0,2][0,{column:1, modifier:myPlusOneFunc, type:'number'},2]
[可选] 可让您指定要除了输出列之外还要包含在输出表中的列。由于该行组中的所有行都会压缩为一个输出行,因此您必须确定要为该行组显示什么值。例如,您可以选择显示集合中的第一行列的值,还是显示该组中所有行的平均值。 columns 是对象的数组,具有以下属性:
  • column - 指定要显示的列的索引的数字。
  • aggregate - 一个函数,可接受此行组中所有列的数组,并返回要在结果行中显示的单个值。返回值必须是对象的 type 属性指定的类型。下面详细介绍了如何创建您自己的聚合函数。您必须了解此方法接受的数据类型,并仅对相应类型的列调用该方法。该 API 提供了几个有用的聚合函数。有关列表,请参阅下文的提供的聚合函数,或了解如何编写自己的聚合函数
  • type - 聚合函数的返回类型。这应该是 JavaScript 字符串类型名称,例如“数字”或“布尔值”。
  • label - [可选] 在返回的表中要应用于此列的字符串标签。
  • id - [选填] 要返回表中要应用于此列的字符串 ID。

返回值

DataTablekeys 中列出的每列都有一列,columns 中列出的每列各有一列。系统会根据从左到右的键行对表格进行排序。

示例

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

提供的修饰符函数

该 API 提供了以下修饰符函数,您可以将其传递到modifier 参数来自定义分组行为。

功能 输入数组类型 返回值类型 说明
google.visualization.data.month 日期 number 给定日期,它将返回一个从零开始的月份值(0、1、2 等)。

提供的聚合函数

该 API 提供了以下汇总函数,您可以将其传递到aggregate 参数数组。

功能 输入数组类型 返回值类型 说明
google.visualization.data.avg number number 传入的数组的平均值。
google.visualization.data.count 任意类型 number 组中的行数。系统会统计 null 值和重复值。
google.visualization.data.max 数字、字符串、日期 数字、字符串、日期、null 数组中的最大值。对于字符串,这是指按字典顺序排序的列表中的第一项;对于日期值,则为最新日期。系统会忽略 null。如果没有上限,则返回 null。
google.visualization.data.min 数字、字符串、日期 数字、字符串、日期、null 数组中的最小值。对于字符串,这是指按字典顺序排序的列表中的最后一项;对于日期值,则是最早的日期。系统会忽略 null。如果没有最小值,则返回 null。
google.visualization.data.sum number number 数组中所有值的总和。

创建修饰符函数

您可以创建修饰符函数,以便在 group() 函数对行进行分组之前对键值执行简单的转换。此函数接受一个单元格的值,对其执行操作(例如,将值加 1),然后返回该值。输入和返回类型不必是同一类型,但调用方必须知道输入和输出类型。下面是一个接受日期并返回季度的函数示例:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

创建聚合函数

您可以创建一个聚合函数,用于接受行组中的一组列值并返回单个数字:例如,返回计数或值平均值。下面是提供的计数聚合函数的实现,它会返回相应行组中的行数的计数:

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

此方法将两个数据表(DataTableDataView 对象)联接到一个结果表中,类似于 SQL JOIN 语句。您需要在两个表之间指定一个或多个列对(列),输出表会根据您指定的联接方法包括行:只有两个键都匹配的行;一个表中的所有行;或两个表中的所有行(无论键是否匹配)。结果表仅包含键列以及您指定的任何其他列。请注意,dt2 不能有重复的键,但 dt1 可以。“键”一词是指所有键列值的组合,而不是特定的键列值;因此,如果某行有单元格值 A | B | C,第 0 和 1 列是键列,则该行的键为 AB。

语法

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);
DT1
填充以与 dt2 联接的 DataTable
DT2
要与 dt1 联接的已填充 DataTable。此表不能有多个相同的键(一个键是键列值的组合)。
joinMethod
用于指定联接类型的字符串。如果 dt1 有多个行与 dt2 行匹配,则输出表将包含所有匹配的 dt1 行。从以下值中进行选择:
  • “full”- 无论键是否匹配,输出表都包含这两个表中的所有行。不匹配的行将包含空单元格条目;系统会联接匹配的行。
  • “inner”- 过滤的完全联接,仅包含键匹配的行。
  • “left”- 输出表包含 dt1 中的所有行,无论 dt2 中是否存在匹配行。
  • “right”- 输出表包含 dt2 中的所有行,无论 dt1 中是否存在匹配行。
keys
要从两个表中比较的键列的数组。每对都是一个双元素数组,第一个是 dt1 中的键,第二个是 dt2 中的键。此数组可以按其索引、ID 或标签指定列,请参阅 getColumnIndex
两个表中的列必须具有相同的类型。所有指定的键都必须根据 joinMethod 提供的规则进行匹配,以包含表中的行。输出表中始终包含键列。只有 dt1(左侧表)可以包含重复键;dt2 中的键必须是唯一的。这里的“键”一词是指一组唯一的键列,而不是单个列值。例如,如果您的键列是 A 和 B,则下表将仅包含唯一键值(因此可以用作 dt2):
B
Jen 红色
Jen 蓝色
Fred 红色
示例[[0,0], [2,1]] 会将两个表中的第一列、dt1 中的第三列与 dt2 中的第二列进行比较。
dt1 列
dt1 中要包含在输出表中的列的数组,以及 dt1 的键列。此数组可以按其索引、ID 或标签指定列,请参阅 getColumnIndex
dt2Columns
dt2 中要包含在输出表中的列的数组,以及 dt2 的键列。此数组可以按其索引、ID 或标签指定列,请参阅 getColumnIndex

返回值

包含键列、dt1Columnsdt2ColumnsDataTable。此表格按键列从左到右排序。当 joinMethod 为“inner”时,应填充所有键单元格。对于其他联接方法,如果未找到匹配的键,则表中所有不匹配的键单元都将为 null。

示例

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

格式化程序

Google 可视化 API 提供了一些格式设置工具,可用于在可视化图表中重新设置数据格式。这些格式化程序会更改所有行中指定列的格式化值。请注意:

  • 格式化程序只会修改设置了格式的值,而不会修改基础值。例如,显示的值将为“$1,000.00”,但底层值仍为“1000”。
  • 格式化程序一次只影响一列;要重新设置多列的格式,请对要更改的每一列应用格式化程序。
  • 如果您还使用用户定义的格式化程序,则某些 Google 可视化格式化程序会覆盖所有用户定义的格式化程序。
  • 应用于数据的实际格式来自使用该 API 加载的语言区域。 如需了解详情,请参阅加载包含特定语言区域的图表

    重要提示:格式化程序只能与 DataTable 一起使用,不能与 DataView 一起使用(DataView 对象为只读)。

    以下是使用格式化程序的常规步骤:

    1. 获取已填充的 DataTable 对象。
    2. 对于您要重新设置格式的每一列,请按以下步骤操作:
      1. 创建一个对象,用于指定格式化程序的所有选项。这是一个包含一组属性和值的基本 JavaScript 对象。请参阅格式化程序的文档,了解受支持的属性。(可选,您可以传入用于指定选项的对象字面量表示法对象。)
      2. 创建格式化程序,并传入选项对象。
      3. 调用 formatter.format(table, colIndex),传入 DataTable 和要重新格式化的数据的列(从零开始)。请注意,您只能对每个列应用一个格式化程序;应用第二个格式化程序只是会覆盖第一个格式化程序的效果。
        重要提示:许多格式设置工具要求使用 HTML 标记显示特殊格式;如果可视化图表支持 allowHtml 选项,您应将其设置为 true。

    以下示例将日期列的格式日期值更改为使用长日期格式(“2009 年 1 月 1 日”):

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Employee Name');
    data.addColumn('date', 'Start Date');
    data.addRows(3);
    data.setCell(0, 0, 'Mike');
    data.setCell(0, 1, new Date(2008, 1, 28));
    data.setCell(1, 0, 'Bob');
    data.setCell(1, 1, new Date(2007, 5, 1));
    data.setCell(2, 0, 'Alice');
    data.setCell(2, 1, new Date(2006, 7, 16));
    
    // Create a formatter.
    // This example uses object literal notation to define the options.
    var formatter = new google.visualization.DateFormat({formatType: 'long'});
    
    // Reformat our data.
    formatter.format(data, 1);
    
    // Draw our data
    var table = new google.visualization.Table(document.getElementById('dateformat_div'));
    table.draw(data, {showRowNumber: true});

    大多数格式化程序都公开了以下两个方法:

    方法 说明
    google.visualization.formatter_name(options)

    构造函数,其中 formatter_name 是具体的 formatterclass 名称。

    • options - 一个通用 JavaScript 对象,用于指定该格式化程序的选项。此对象是一个通用对象,具有属性/值对,其中包含该格式设置工具专用的属性。请参阅适用于您的特定格式化程序的文档,了解受支持的选项。下面是调用 DateFormat 对象的构造函数的两种示例方法,传入以下两个属性:
    // Object literal technique
    var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5});
    
    // Equivalent property setting technique
    var options = new Object();
    options['formatType'] = 'long';
    options['timeZone'] = -5;
    var formatter = new google.visualization.DateFormat(options);
    format(data, colIndex)

    重新设置指定列中数据的格式。

    • data - 这是一个 DataTable,其中包含要重新设置格式的数据。您不能在此处使用 DataView。
    • colIndex - 要设置格式的列的索引(从零开始)。要设置多列的格式,您必须使用不同的 colIndex 值多次调用此方法。

     

    Google 可视化 API 提供了以下格式化程序:

    格式化程序名称 说明
    箭头格式 添加向上或向下箭头,指示单元格值是高于还是低于指定值。
    BarFormat 添加一个彩色条形,其方向和颜色表示单元格值是高于还是低于指定值。
    颜色格式 根据值是否位于指定范围内,对单元格进行着色。
    日期格式 设置日期或日期时间值的格式,有几种不同的格式,包括“2009 年 1 月 1 日”、“1/1/09”和“2009 年 1 月 1 日”。
    数字格式 设置数值各方面的格式。
    PatternFormat 将同一行上的单元格值以及任意文本连接到一起。

    箭头格式

    向数值单元格添加向上或向下箭头,具体取决于该值是高于还是低于指定的基值。如果等于基准值,则不会显示箭头。

    选项

    ArrowFormat 支持以下选项,并传入构造函数:

    选项 说明
    base

    一个数字,表示基准值,用于与单元格值进行比较。如果该单元格的值较高,则该单元格会包括一个绿色的向上箭头;如果单元格的值越小,该单元格将包含一个红色的向下箭头;如果相同,则不包含任何箭头。

    示例代码

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Department');
    data.addColumn('number', 'Revenues Change');
    data.addRows([
      ['Shoes', {v:12, f:'12.0%'}],
      ['Sports', {v:-7.3, f:'-7.3%'}],
      ['Toys', {v:0, f:'0%'}],
      ['Electronics', {v:-2.1, f:'-2.1%'}],
      ['Food', {v:22, f:'22.0%'}]
    ]);
    
    var table = new google.visualization.Table(document.getElementById('arrowformat_div'));
    
    var formatter = new google.visualization.ArrowFormat();
    formatter.format(data, 1); // Apply formatter to second column
    
    table.draw(data, {allowHtml: true, showRowNumber: true});

    BarFormat

    向数字单元格添加彩色条,以指示单元格的值是高于还是低于指定的基值。

    选项

    BarFormat 支持以下选项,并传入构造函数:

    选项

    示例

    说明
    base 一个数字,用作要比较的单元格值的基本值。如果单元格值较高,则会绘制在基数右侧;如果值较低,则会绘制在左边。默认值为 0。
    colorNegative 表示柱形的负值部分的字符串。可能的值为“red”、“green”和“blue”;默认值为“red”。
    colorPositive 指示条形正值部分颜色的字符串。可能的值包括“red”、“green”和“blue”。默认值为“blue”。
    drawZeroLine 一个布尔值,用于指示当存在负值时是否绘制 1 像素的深色基线。 暗线可增强扫描条的视觉效果。默认值为“false”。
    max 条形范围的最大值。默认值为表格中的最大值。
    min 条形范围的最小数值。默认值为表格中的最小值。
    showValue 如果为 true,则显示值和柱形;如果为 false,则仅显示柱形。默认值为 true。
    width 每个条形的粗细(以像素为单位)。默认值为 100。

    示例代码

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Department');
    data.addColumn('number', 'Revenues');
    data.addRows([
      ['Shoes', 10700],
      ['Sports', -15400],
      ['Toys', 12500],
      ['Electronics', -2100],
      ['Food', 22600],
      ['Art', 1100]
    ]);
    
    var table = new google.visualization.Table(document.getElementById('barformat_div'));
    
    var formatter = new google.visualization.BarFormat({width: 120});
    formatter.format(data, 1); // Apply formatter to second column
    
    table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

    ColorFormat(颜色格式)

    根据数字单元格的值为数字单元格的前景或背景分配颜色。此格式设置方法很不同寻常,因为它不会在构造函数中获取其选项。相反,在调用 format() 之前,您应根据需要多次调用 addRange()addGradientRange(),以添加颜色范围。颜色能以任何可接受的 HTML 格式指定,例如“black”、“#000000”或“#000”。

    方法

    ColorFormat 支持以下方法:

    方法 说明
    google.visualization.ColorFormat() 构造函数。不接受参数。
    addRange(from, to, color, bgcolor)

    指定单元格的前景颜色和/或背景颜色,具体取决于单元格的值。 系统会为具有指定 from - to 范围中的值的所有单元格分配 colorbgcolor。务必要知道该范围不包含边界值,因为创建一个介于 1—1000 与 1000—2000 之间的范围并不涵盖值 1000!

    • from - [String, Number, Date, 日期, or TimeOfDay] 范围的下限(含边界值),或为 null。如果为 null,则匹配 -∞。字符串边界按字母顺序与字符串值进行比较。
    • to - [String, Number, Date, 日期, or TimeOfDay] 范围的高边界值(非边界值),或为 null。如果为 null,则匹配 +∞。字符串边界按字母顺序与字符串值进行比较。
    • color - 要应用于匹配单元格中的文本的颜色。值可以是“#RRGGBB”值或定义的颜色常量(例如“#FF0000”或“red”)。
    • bgcolor - 要应用于匹配单元格背景的颜色。值可以是“#RRGGBB”值或定义的颜色常量(例如“#FF0000”或“red”)。
    addGradientRange(from, to, color, fromBgColor, toBgColor)

    根据单元格值指定某个范围内的背景颜色。系统会根据单元格值在从下边界颜色到上边界颜色的范围内缩放颜色。请注意,此方法无法像 addRange() 一样比较字符串值。提示:颜色范围通常不容易让观看者准确测量;最简单且最容易读取的范围是从完全饱和的颜色到白色(例如,#FF0000 - FFFFFF)。

    • from - [数字、日期、日期时间或 TimeOfDay] 范围的下限(含边界值),或为 null。如果为 null,则匹配 -∞.
    • to - [Number, Date, Date, or TimeOfDay] 范围的上边界(非边界),或为 null。如果为 null,则匹配 +∞.
    • color - 要应用于匹配单元格中的文本的颜色。对于所有单元格而言,此颜色都是相同的,无论它们的值如何。
    • fromBgColor - 位于值的低端的单元格的背景颜色。值可以是“#RRGGBB”值或定义的颜色常量(例如“#FF0000”或“red”)。
    • toBgColor - 将渐变值保存在渐变效果顶部的单元格的背景颜色。值可以是“#RRGGBB”值或定义的颜色常量(例如“#FF0000”或“red”)。

     

    format(dataTable, columnIndex) format() 格式应用于指定列的标准方法。

    示例代码

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Department');
    data.addColumn('number', 'Revenues');
    data.addRows([
      ['Shoes', 10700],
      ['Sports', -15400],
      ['Toys', 12500],
      ['Electronics', -2100],
      ['Food', 22600],
      ['Art', 1100]
    ]);
    
    var table = new google.visualization.Table(document.getElementById('colorformat_div'));
    
    var formatter = new google.visualization.ColorFormat();
    formatter.addRange(-20000, 0, 'white', 'orange');
    formatter.addRange(20000, null, 'red', '#33ff33');
    formatter.format(data, 1); // Apply formatter to second column
    
    table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

    日期格式

    以各种方式设置 JavaScript Date 值的格式,包括“2016 年 1 月 1 日”“1 月 1 日”和“2016 年 1 月 1 日”。

    选项

    DateFormat 支持以下选项,并传入构造函数:

    选项 说明
    formatType

    日期的快速格式设置选项。支持以下字符串值,并将日期格式重新设置为 2016 年 2 月 28 日,如下所示:

    • “short”- 短格式:例如,“2016 年 2 月 28 日”
    • “medium”- 媒介格式:例如,“2016 年 2 月 28 日”
    • “long”- 长格式:例如,“2016 年 2 月 28 日”

    您不能同时指定 formatTypepattern

    pattern

    要应用于该值的自定义格式模式,类似于 ICU 日期和时间格式。例如:var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"});

    您不能同时指定 formatTypepattern。您可以在下一部分中详细了解模式。

    timeZone 显示日期值的时区。这是一个数值,表示 GMT + 此时区数量(可为负数)。默认情况下,创建日期对象时假定使用的是其创建计算机所在的时区;此选项用于以不同时区显示该值。例如,如果您在位于英国格林尼治的计算机上将日期对象设置为下午 5 点,并将时区指定为 -5(options['timeZone'] = -5,或美国东部太平洋时间),则显示的值将是中午 12 点。

    方法

    DateFormat 支持以下方法:

    方法 说明
    google.visualization.DateFormat(options)

    构造函数。如需了解详情,请参阅上面的选项部分。

    format(dataTable, columnIndex) 将格式应用于指定列的标准 format() 方法。
    formatValue(value)

    返回给定值的格式化值。此方法不需要 DataTable

    示例代码

    function drawDateFormatTable() {
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Employee Name');
      data.addColumn('date', 'Start Date (Long)');
      data.addColumn('date', 'Start Date (Medium)');
      data.addColumn('date', 'Start Date (Short)');
      data.addRows([
        ['Mike', new Date(2008, 1, 28, 0, 31, 26),
                 new Date(2008, 1, 28, 0, 31, 26),
                 new Date(2008, 1, 28, 0, 31, 26)],
        ['Bob', new Date(2007, 5, 1, 0),
                new Date(2007, 5, 1, 0),
                new Date(2007, 5, 1, 0)],
        ['Alice', new Date(2006, 7, 16),
                  new Date(2006, 7, 16),
                  new Date(2006, 7, 16)]
      ]);
    
      // Create three formatters in three styles.
      var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
      var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
      var formatter_short = new google.visualization.DateFormat({formatType: 'short'});
    
      // Reformat our data.
      formatter_long.format(data, 1);
      formatter_medium.format(data,2);
      formatter_short.format(data, 3);
    
      // Draw our data
      var table = new google.visualization.Table(document.getElementById('dateformat_div'));
      table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
    }

    详细了解日期模式

    下面更详细地介绍了支持的模式:

    这些格式类似于 ICU 日期和时间格式,但尚不支持以下格式:A D F g Y u w W。为避免与模式发生冲突,您希望在输出中显示的任何字面量文本都应用英文单引号括住,但单引号除外,后者应加倍:例如,"K 'o''clock.'"

    模式 说明 输出示例
    GG 代数。 “广告”
    yy 或 yyyy 1996
    M

    一年中的月。1 月:

    • M 产生 1
    • MM 生成 01
    • MMM 在 1 月出产
    • M 月 1 月

    “7 月”

    “07”

    d 一月中的天。额外的“d”值将添加前导零。 10
    小时 12 小时制的小时。额外的“h”值将添加前导零。 12
    H 24 小时制的小时值。额外的 HK' 值将添加前导零。 0
    m 一小时中的分钟。额外的“M”值将添加前导零。 30
    一分钟中的秒。额外的 's' 值将添加前导零。 55
    S 小数部分。额外的“S”值右侧将填充零。 978
    E

    星期几。“Tuesday”的输出如下所示:

    • E 产生 T
    • 二氧化碳当量或二氧化碳当量
    • EEEE,制作周二

    “星期二”

    “星期二”

    aa 上午/下午 “PM”
    k 一天中的小时 (1~24)。额外的“k”值将添加前导零。 24
    K AM/PM 中的小时 (0~11)。额外的“k”值将添加前导零。 0
    z

    时区。对于时区 5,生成“UTC+5”

    “世界协调时间 (UTC) +5”
    Z

    采用 RFC 822 格式的时区。对于时区 -5:

    Z、ZZ、ZZZ -0500

    ZZZZ 和更多农产品“GMT -05:00”

    “-0800”

    “GMT -05:00”

    v

    时区(通用)。

    “其他/GMT-5”
    ' 按 Esc 键可显示文字 '日期='
    单引号 'yy

    数字格式

    描述数值列应采用的格式。格式设置选项包括指定要用作千位标记的前缀符号(如美元符号)或标点符号。

    选项

    NumberFormat 支持以下选项,并传入构造函数:

    选项 说明
    decimalSymbol

    用作十进制标记的字符。默认值为点 (.)。

    fractionDigits

    一个数字,用于指定小数点后可显示的位数。默认值为 2。如果您指定的数字超过数字包含的数量,则较小的值将显示零。截断的值将四舍五入(即向上舍入为 5)。

    groupingSymbol 用于将十进制数字左边的字符分为三组的字符。默认值为英文逗号 (,)。
    negativeColor 负值的文本颜色。无默认值。值可以是任何可接受的 HTML 颜色值,如“red”或“#FF0000”。
    negativeParens 一个布尔值,其中 true 表示负值应用括号括起来。 默认值为 true。
    pattern

    格式字符串。提供后,系统会忽略除 negativeColor 之外的所有其他选项。

    格式字符串是 ICU 模式集的子集。例如,对于值 10、7.5 和 0.5,{pattern:'#,###%'} 将导致输出值为“1,000%”、“750%”和“50%”。

    prefix 值的字符串前缀,例如“$”。
    suffix 值的字符串后缀,例如“%”。

    方法

    NumberFormat 支持以下方法:

    方法 说明
    google.visualization.NumberFormat(options)

    构造函数。如需了解详情,请参阅上面的选项部分。

    format(dataTable, columnIndex) format() 格式应用于指定列的标准方法。
    formatValue(value)

    返回给定值的格式化值。此方法不需要 DataTable

    示例代码

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Department');
    data.addColumn('number', 'Revenues');
    data.addRows([
      ['Shoes', 10700],
      ['Sports', -15400],
      ['Toys', 12500],
      ['Electronics', -2100],
      ['Food', 22600],
      ['Art', 1100]
    ]);
    
    var table = new google.visualization.Table(document.getElementById('numberformat_div'));
    
    var formatter = new google.visualization.NumberFormat(
        {prefix: '$', negativeColor: 'red', negativeParens: true});
    formatter.format(data, 1); // Apply formatter to second column
    
    table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

    图案格式

    使您能够将指定列的值与任意文本合并到一个列中。例如,如果您有一个名为“名字”的列,还有一个包含姓氏的列,则可以在第三列中填充“{last name}”和“{first name}”。此格式化程序未遵循构造函数和 format() 方法的惯例。有关说明,请参阅下文中的“方法”部分。

    方法

    PatternFormat 支持以下方法:

    方法 说明
    google.visualization.PatternFormat(pattern)

    构造函数。不接收选项对象。相反,它接受字符串模式参数。这是一个字符串,用于说明要放入目标列中的列值以及任意文本。在字符串中嵌入占位符以指示要嵌入另一列中的值。占位符为 {#},其中 # 是要使用的源列的索引。索引是下面 format() 方法的 srcColumnIndices 数组中的索引。如需添加文字 { 或 } 字符,请按如下方式对其进行转义:\{ 或 \}。如需添加文字 \ 符号,请将其转义为 \\。

    示例代码

    以下示例演示了用于创建锚点元素的模式的构造函数,其中第一个和第二个元素取自 format() 方法:

    var formatter = new google.visualization.PatternFormat(
      '<a href="mailto:{1}">{0}</a>');
    format(dataTable, srcColumnIndices, opt_dstColumnIndex)

    标准格式调用,以及一些其他参数:

    • dataTable - 要操作的 DataTable。
    • srcColumnIndices - 一个或多个要提取作为基础 DataTable 中源的列索引(从零开始)的数组。它将用作构造函数中 pattern 参数的数据源。列编号必须按排序顺序。
    • opt_dstColumnIndex - [可选] 要在其中放置 pattern 操作输出的目标列。如果未指定,则 srcColumIndices 中的第一个元素将用作目的地。

    请参见表格后面的格式示例。

    以下是一些四列表格的一些输入和输出示例。

    Row before formatting (4 columns, last is blank):
    John  |  Paul  |  Jones  |  [empty]
    
    var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
    formatter.format(data, [0,1,2], 3);
    Output:
      John  |  Paul  |  Jones  |  John Paul Jones
    
    var formatter = new google.visualization.PatternFormat("{1}, {0}");
    formatter.format(data, [0,2], 3);
    Output:
      John  |  Paul  |  Jones  |  Jones, John

    示例代码

    以下示例演示了如何组合两列中的数据来创建电子邮件地址。它使用 DataView 对象隐藏原始源列:

    var data = new google.visualization.DataTable();
    data.addColumn('string', 'Name');
    data.addColumn('string', 'Email');
    data.addRows([
      ['John Lennon', 'john@beatles.co.uk'],
      ['Paul McCartney', 'paul@beatles.co.uk'],
      ['George Harrison', 'george@beatles.co.uk'],
      ['Ringo Starr', 'ringo@beatles.co.uk']
    ]);
    
    var table = new google.visualization.Table(document.getElementById('patternformat_div'));
    
    var formatter = new google.visualization.PatternFormat(
        '<a href="mailto:{1}">{0}</a>');
    // Apply formatter and set the formatted value of the first column.
    formatter.format(data, [0, 1]);
    
    var view = new google.visualization.DataView(data);
    view.setColumns([0]); // Create a view with the first column only.
    
    table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

    GadgetHelper

    辅助程序类,用于简化编写使用 Google 可视化 API 的小工具的过程。

    构造函数

    google.visualization.GadgetHelper()

    方法

    方法 返回值 说明
    createQueryFromPrefs(prefs) google.visualization.Query 静态。创建新 google.visualization.Query 实例,并根据小工具偏好设置中的值设置其属性。参数 prefs 的类型为 _IG_Prefs
    1. 偏好设置 _table_query_url 用于设置查询数据源网址。
    2. 偏好设置 _table_query_refresh_interval 用于设置查询刷新间隔(以秒为单位)。
    validateResponse(response) 布尔值 静态。参数 response 的类型为 google.visualization.QueryResponse。如果响应包含数据,则返回 true。如果查询执行失败并且响应不包含数据,则返回 false。如果发生错误,此方法会显示错误消息。

    查询类

    您可以使用以下对象将数据查询发送到外部数据源,例如 Google 电子表格。

    查询

    表示发送到数据源的查询。

    构造函数

    google.visualization.Query(dataSourceUrl, opt_options)

    参数

    dataSourceUrl
    [要向其发送查询的必需字符串] 网址。有关 Google 电子表格,请参阅图表文档
    优化选项
    [可选,对象] 请求的选项映射。注意:如果您访问受限数据源,则不应使用此参数,以下是受支持的属性:
    • sendMethod - [可选,字符串] 指定用于发送查询的方法。选择以下字符串值之一:
      • 'xhr' - 使用 XmlHttpRequest 发送查询。
      • 'scriptInjection' - 使用脚本注入发送查询。
      • 'makeRequest' - [仅适用于已废弃的小工具] 使用 Gadget API makeRequest() 发送查询。如果指定,还应指定 makeRequestParams
      • 'auto' - 使用由数据源网址中的 tqrt 网址参数指定的方法。tqrt 可以具有以下值:“xhr”、“scriptInjection”或“makeRequest”。如果 tqrt 缺失或包含无效值,则对于同一网域请求,默认值为“xhr”;对于跨网域请求,默认值为“scriptInjection”。
    • makeRequestParams - 对象makeRequest() 查询的参数映射。仅当 sendMethod 为“makeRequest”时使用和必需。

    方法

    方法 返回值 说明
    abort() 停止使用 setRefreshInterval() 启动的自动查询发送。
    setRefreshInterval(seconds)

    将查询设置为从首次显式调用 send 开始,每指定的时长(秒数)自动调用 send 方法。seconds 是一个大于或等于零的数字。

    如果您使用此方法,则应先调用该方法,然后再调用 send 方法。

    如需取消此方法,您可以再次调用它(默认为零),或者调用 abort()

    setTimeout(seconds) 设置在引发超时错误之前等待数据源响应的秒数。seconds 是一个大于零的数字。
    默认超时时间为 30 秒。如果使用此方法,则应先调用 send,再调用该方法。
    setQuery(string) 设置查询字符串。string 参数的值应该是有效的查询。
    如果使用此方法,则应在调用 send 方法之前调用此方法。 详细了解查询语言
    send(callback) 将查询发送到数据源。callback 应该是在数据源响应时调用的函数。回调函数将收到一个类型为 google.visualization.QueryResponse 的参数。

    查询响应

    表示从数据源收到的查询执行的响应。此类的实例会作为参数传递给在调用 Query.send 时设置的回调函数。

    方法

    方法 返回值 说明
    getDataTable() 数据表 返回数据源返回的数据表。如果查询执行失败并且未返回任何数据,则返回 null
    getDetailedMessage() 字符串 返回失败查询的详细错误消息。如果查询执行成功,此方法将返回空字符串。返回的消息是一条面向开发者的消息,可能包含技术信息,例如“{salary} 列不存在”。
    getMessage() 字符串 为失败的查询返回简短的错误消息。如果查询执行成功,此方法将返回空字符串。返回的消息是一条供最终用户使用的简短消息,例如“查询无效”或“访问遭拒”。
    getReasons() 字符串数组 返回一个包含零个或更多条目的数组。每个条目都是一个短字符串,其中包含在执行查询时引发的错误或警告代码。可能的代码:
    • access_denied 用户无权访问数据源。
    • invalid_query 指定的查询含有语法错误。
    • data_truncated 由于输出大小限制,未返回与查询选项匹配的一个或多个数据行。(警告)。
    • timeout 查询在预期时间内没有响应。
    hasWarning() 布尔值 如果查询执行有任何警告消息,则返回 true
    isError() 布尔值 如果查询执行失败,并且响应不包含任何数据表,则返回 true。如果查询执行成功且响应包含数据表,则返回 <false>。

    错误显示

    该 API 提供了若干函数来帮助您向用户显示自定义错误消息。要使用这些函数,请在页面上提供一个容器元素(通常是 <div>),API 会在此元素中绘制格式化的错误消息。此容器可以是可视化容器元素,也可以是仅用于出现错误的容器。如果您指定可视化图表包含元素,则可视化图表将会显示错误消息。然后,调用以下相应的函数以显示或移除错误消息。

    所有函数都是命名空间 google.visualization.errors 中的静态函数。

    许多可视化图表都可能会引发错误事件;请参阅下面的错误事件以了解详情。

    您可以在查询封装容器示例中查看自定义错误示例。

    功能 返回值 说明
    addError(container, message, opt_detailedMessage, opt_options) 用于标识已创建的错误对象的字符串 ID 值。这是页面上的唯一值,可用于移除错误或查找其包含的元素。

    使用指定的文本和格式向指定的页面元素添加错误显示块。

    • container - 要在其中插入错误消息的 DOM 元素。如果找不到该容器,该函数将抛出 JavaScript 错误。
    • message - 要显示的字符串消息。
    • opt_detailedMessage - 可选的详细消息字符串。默认情况下,这是鼠标悬停文字,但您可以在下文所述的 opt_options.showInToolTip 属性中更改此文字。
    • opt_options - 可选对象,具有为消息设置各种显示选项的属性。支持的选项如下:
      • showInTooltip - 一个布尔值,其中 true 仅显示详细消息,false 表示简短消息在容器正文中显示的详细消息。默认值为 true。
      • type - 一个字符串,用于描述错误类型,该字符串决定了应将哪些 CSS 样式应用于此消息。支持的值为“error”和“warning”。默认值为“error”。
      • style - 错误消息的样式字符串。此样式将替换应用于警告类型 (opt_options.type) 的所有样式。示例:'background-color: #33ff99; padding: 2px;' 默认值是空字符串。
      • removable - 布尔值,其中 true 表示消息可由用户的鼠标点击关闭。默认值为 false。
    addErrorFromQueryResponse(container, response)

    字符串 ID 值,用于标识已创建的错误对象;如果响应未指示错误,则返回 null。这是页面上的唯一值,可用于移除错误或查找其包含的元素。

    将查询响应和错误消息容器传递给此方法:如果查询响应指示查询错误,则在指定页面元素中显示错误消息。如果查询响应为 null,该方法将抛出 JavaScript 错误。将查询处理程序中收到的 QueryResponse 传递给此消息,以显示错误。它还会根据类型设置错误的显示样式(错误或警告,类似于 addError(opt_options.type)

    • container - 要在其中插入错误消息的 DOM 元素。如果找不到该容器,该函数将抛出 JavaScript 错误。
    • response - 您的查询处理程序在响应查询时收到的 QueryResponse 对象。如果此值为 null,该方法将抛出 JavaScript 错误。
    removeError(id) 布尔值:如果移除了错误,则返回 true,否则返回 false。

    从页面中移除由 ID 指定的错误。

    • id - 使用 addError()addErrorFromQueryResponse() 创建的错误的字符串 ID。
    removeAll(container)

    从指定容器中移除所有错误块。如果指定的容器不存在,则会抛出错误。

    • container - 包含要移除的错误字符串的 DOM 元素。如果找不到该容器,该函数将抛出 JavaScript 错误。
    getContainer(errorId) 处理包含指定错误的 DOM 元素的句柄;如果找不到,则为 null。

    用于检索包含 errorID 指定的错误的容器元素的句柄。

    • errorId - 使用 addError()addErrorFromQueryResponse() 创建的错误的字符串 ID。

    事件

    大多数可视化图表都会触发事件,以表明发生了一些事情。作为图表的用户,您可能经常希望监听这些事件。如果您编写您自己的可视化图表,可能还需要自行触发此类事件。

    通过以下方法,开发者可以监听事件、移除现有事件处理脚本或在可视化图表中触发事件。

    addListener()

    调用此方法可注册由托管在您网页上的可视化图表触发的事件。您应记录哪些事件参数(如果有)将传递给处理函数。

    google.visualization.events.addListener(source_visualization,
      event_name, handling_function)
    source_visualization
    来源可视化实例的句柄。
    event_name
    要监听的事件的字符串名称。可视化图表应记录它抛出的事件。
    handling_function(订单处理功能)
    source_visualization 触发 event_name 事件时要调用的本地 JavaScript 函数的名称。处理函数会将所有事件参数作为参数传递。

    返回结果

    新监听器的监听器处理程序。如有必要,该处理程序可以稍后通过调用 google.visualization.events.removeListener() 移除此监听器。

    示例

    以下是注册接收选择事件的示例

    var table = new google.visualization.Table(document.getElementById('table_div'));
    table.draw(data, options);
    
    google.visualization.events.addListener(table, 'select', selectHandler);
    
    function selectHandler() {
      alert('A table row was selected');
    }

    addOneTimeListener()

    这与 addListener() 相同,但适用于只应监听一次的事件。此事件的后续抛出不会调用处理函数。

    例如,每次绘制都会导致 ready 事件被抛出。如果您只想让第一个 ready 执行您的代码,则需要 addOneTimeListener,而不是 addListener

    removeListener()

    调用此方法可取消注册现有事件监听器。

    google.visualization.events.removeListener(listener_handler)
    listener_Handler
    google.visualization.events.addListener() 返回的要移除的监听器处理程序。

    removeAllListeners()

    调用此方法可取消注册特定可视化图表实例的所有事件监听器。

    google.visualization.events.removeAllListeners(source_visualization)
    source_visualization
    应移除所有事件监听器的源可视化实例的句柄。

    trigger()

    由可视化实现者调用。在可视化图表中调用此方法,可以触发具有任意名称和一组值的事件。

    google.visualization.events.trigger(source_visualization, event_name,
      event_args)
    source_visualization
    来源可视化实例的句柄。如果您从发送可视化图表定义的方法内调用此函数,只需传入 this 关键字即可。
    event_name
    调用事件的字符串名称。您可以根据需要选择任何字符串值。
    event_args
    [可选] 传递给接收方法的名称/值对映射。例如:{message: "Hello there!",得分: 10, name: "Fred"}。如果不需要事件,您可以传递 null;接收器应该准备好为此参数接受 null。

    示例

    下面是一个可视化图表示例,在调用它的 onclick 方法时,该方法会抛出名为“select”的方法。它不会传回任何值。

    MyVisualization.prototype.onclick = function(rowIndex) {
      this.highlightRow(this.selectedRow, false); // Clear previous selection
      this.highlightRow(rowIndex, true); // Highlight new selection
    
      // Save the selected row index in case getSelection is called.
      this.selectedRow = rowIndex;
    
      // Trigger a select event.
      google.visualization.events.trigger(this, 'select', null);
    }

    标准可视化方法和属性

    每个可视化图表都应公开以下一组必需的和可选的方法和属性。不过请注意,我们并未强制实施类型检查,因此您应该阅读每个可视化图表的文档。

    注意:这些方法位于可视化图表的命名空间中,而不是位于 google.visualization 命名空间中。

    构造函数

    构造函数应具有可视化图表类的名称,并返回该类的实例。

    visualization_class_name(dom_element)
    dom_element
    指向应在其中嵌入可视化图表的 DOM 元素的指针。

    示例

    var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

    draw()

    在网页上绘制可视化图表。在后台,这可能是从服务器提取图形,或者使用关联的可视化代码在网页上创建图形。每当数据或选项发生更改时,您都应调用此方法。该对象应在传递给构造函数的 DOM 元素内绘制。

    draw(data[, options])
    数据
    一个 DataTableDataView,用于存储用于绘制图表的数据。没有从图表中提取 DataTable 的标准方法。
    options
    [可选] 自定义选项的名称/值对的映射。例如高度和宽度、背景颜色和字幕。可视化图表文档应列出可用的选项,如果您未指定此参数,则应支持默认选项。 您可以使用 JavaScript 对象字面量语法传入选项映射,例如: {x:100, y:200, title:'An Example'}

    示例

    chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

    getAction()

    此可视化操作也可通过具有提示并允许执行提示操作的可视化图表公开。

    返回包含请求的 actionID 的提示操作对象。

    示例

    // Returns the action object with the ID 'alertAction'.
    chart.getAction('alertAction');

    getSelection()

    如果可视化图表希望让您访问图形中当前选定的数据,则可以视情况选择公开这些信息。

    selection_array getSelection()

    返回结果

    selection_array:一个由所选对象组成的数组,其中的每个对象都描述用于创建可视化图表的底层数据元素(DataViewDataTable)。每个对象都具有 row 和/或 column 属性,并且具有底层 DataTable 中所选项的行和/或列的索引。如果 row 属性为 null,则所选项为列;如果 column 属性为 null,则选择范围为一行;如果二者均为非 null 值,则表示所选择的具体数据项。您可以调用 DataTable.getValue() 方法来获取所选项目的值。检索到的数组可以传入 setSelection() 中。

    示例

    function myClickHandler(){
      var selection = myVis.getSelection();
      var message = '';
    
      for (var i = 0; i < selection.length; i++) {
        var item = selection[i];
        if (item.row != null && item.column != null) {
          message += '{row:' + item.row + ',column:' + item.column + '}';
        } else if (item.row != null) {
          message += '{row:' + item.row + '}';
        } else if (item.column != null) {
          message += '{column:' + item.column + '}';
        }
      }
      if (message == '') {
        message = 'nothing';
      }
      alert('You selected ' + message);
    }

    removeAction()

    此可视化操作也可通过具有提示并允许执行提示操作的可视化图表公开。

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

    示例

    // Removes an action from chart with the ID of 'alertAction'.
    chart.removeAction('alertAction');

    setAction()

    此可视化操作也可通过具有提示并允许执行提示操作的可视化图表公开。仅适用于核心图表(条形图、柱形图、折线图、散点图、组合图、气泡图、饼图、甜甜圈、K 线图、直方图、阶梯面积)。

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

    setAction(action object)

    setAction 方法将对象作为其操作参数。此对象应指定 3 个属性:id - 所设置操作的 ID;text - 应显示在操作提示中的文本;action - 当用户点击操作文本时应运行的函数。

    所有提示提示操作均应在调用图表的 draw() 方法之前设置。

    示例

    // Sets a tooltip action which will pop an alert box on the screen when triggered.
    chart.setAction({
      id: 'alertAction',
      text: 'Trigger Alert',
      action: function() {
        alert('You have triggered an alert');
      }
    });

    setAction 方法还可以定义另外两个属性:visibleenabled。这些属性应是返回 boolean 值的函数,用于指示提示操作是否可见和/或已启用。

    示例

    // The visible/enabled functions can contain any logic to determine their state
    // as long as they return boolean values.
    chart.setAction({
      id: 'alertAction',
      text: 'Trigger Alert',
      action: function() {
        alert('You have triggered an alert');
      },
      visible: function() {
        return true;
      },
      enabled: function() {
        return true;
      }
    });

    setSelection()

    (可选)选择可视化图表中的数据条目,例如面积图中的点或条形图中的条形图。调用此方法时,可视化图表应直观地指明新选择是什么。setSelection() 的实现不应触发“select”事件。可视化图表可能会忽略部分选择。例如,一个可能仅显示所选行的表可能会忽略其 setSelection() 实现中的单元格或列元素,也可以选择整个行。

    每次调用此方法时,系统都会取消选择所有选定项,并应用传入的新选择列表。没有显式取消选择各个项的方法;如需取消选择个别项,请使用项 保持选中状态;如需取消选择所有元素,请调用 setSelection()setSelection(null)setSelection([])

    setSelection(selection_array)
    selection_array
    一个由对象组成的数组,其中每个对象都有一个数字行和/或列属性。rowcolumn 是数据表中所选内容的行号或列数(从零开始)。如需选择整列,请将 row 设置为 null;要选择整行,请将 column 设置为 null。示例setSelection([{row:0,column:1},{row:1, column:null}]) 会选择 (0,1) 处的单元格和第 1 行。

    各种静态方法

    本部分包含 google.visualization 命名空间中提供的各种实用方法。

    arrayToDataTable()

    此方法接受一个二维数组,并将其转换为 DataTable。

    列数据类型由所提供的数据自动确定。您也可以使用数组第一行(即列标题行)中的对象字面量表示法指定列数据类型;也可使用可选数据角色,但必须使用对象字面量表示法明确定义它们。对象字面量表示法还可用于任何单元格,以便您定义单元格对象

    语法

    google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)
    twoDArray
    一个二维数组,其中每一行代表数据表中的一行。如果 opt_firstRowIsData 为 false(默认值),则第一行将解释为标题标签。系统会自动根据提供的数据解释每列的数据类型。如果单元格没有值,请酌情指定 null 或空值。
    opt_firstRowIsData
    第一行是否定义了标题行。如果为 true,则假定所有行都是数据。如果为 false,则第一行被视为标题行,且值将分配为列标签。默认值为 false。

    返回结果

    新的 DataTable

    示例

    以下代码演示了创建同一 DataTable 对象的三种方法:

    // Version 1: arrayToDataTable method
    var data2 = google.visualization.arrayToDataTable([
      [{label: 'Country', type: 'string'},
       {label: 'Population', type: 'number'},
       {label: 'Area', type: 'number'},
       {type: 'string', role: 'annotation'}],
      ['CN', 1324, 9640821, 'Annotated'],
      ['IN', 1133, 3287263, 'Annotated'],
      ['US', 304, 9629091, 'Annotated'],
      ['ID', 232, 1904569, 'Annotated'],
      ['BR', 187, 8514877, 'Annotated']
    ]);
    
    // Version 2: DataTable.addRows
    var data3 = new google.visualization.DataTable();
    data3.addColumn('string','Country');
    data3.addColumn('number','Population');
    data3.addColumn('number','Area');
    data3.addRows([
      ['CN', 1324, 9640821],
      ['IN', 1133, 3287263],
      ['US', 304, 9629091],
      ['ID', 232, 1904569],
      ['BR', 187, 8514877]
    ]);
    
    // Version 3: DataTable.setValue
    var data = new google.visualization.DataTable();
    data.addColumn('string','Country');
    data.addColumn('number', 'Population');
    data.addColumn('number', 'Area');
    data.addRows(5);
    data.setValue(0, 0, 'CN');
    data.setValue(0, 1, 1324);
    data.setValue(0, 2, 9640821);
    data.setValue(1, 0, 'IN');
    data.setValue(1, 1, 1133);
    data.setValue(1, 2, 3287263);
    data.setValue(2, 0, 'US');
    data.setValue(2, 1, 304);
    data.setValue(2, 2, 9629091);
    data.setValue(3, 0, 'ID');
    data.setValue(3, 1, 232);
    data.setValue(3, 2, 1904569);
    data.setValue(4, 0, 'BR');
    data.setValue(4, 1, 187);
    data.setValue(4, 2, 8514877);

    drawChart()

    此方法会在单次调用中创建图表。使用此方法的优势在于它需要的代码更少,并且您可以将可视化图表序列化并保存为文本字符串以重复使用。此方法不会为创建的图表返回句柄,因此您无法分配方法监听器来捕获图表事件。

    语法

    google.visualization.drawChart(chart_JSON_or_object)
    chart_JSON_or_object
    具有以下属性(区分大小写)的 JSON 字面量字符串或 JavaScript 对象:
    属性 类型 必需 默认 说明
    图表类型 字符串 必需 可视化图表的类名称。对于 Google 图表,可以省略 google.visualization 软件包名称。如果尚未加载相应的可视化库,并且这是 Google 可视化,此方法将为您加载该库;您必须明确加载第三方可视化。示例TablePieChartexample.com.CrazyChart
    容器 ID 字符串 必需 网页上用于托管可视化图表的 DOM 元素的 ID。
    选项 对象 选填 一个描述可视化选项的对象。您可以使用 JavaScript 字面量表示法,也可以提供对象的句柄。示例"options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
    数据表 对象 选填 用于填充可视化图表的 DataTable。这可以是 DataTable 的文本 JSON 字符串表示形式(如上文所述),也可以是已填充的 google.visualization.DataTable 对象的句柄,或者类似于 arrayToDataTable(opt_firstRowIsData=false) 接受的二维数组。您必须指定此属性或 dataSourceUrl 属性。
    dataSourceUrl 字符串 选填 用于填充图表数据的数据源查询(例如 Google 电子表格)。您必须指定此属性或 dataTable 属性。
    搜索查询 字符串 选填 如果指定了 dataSourceUrl,您可以根据需要使用可视化查询语言指定类似于 SQL 的查询字符串来过滤或操纵数据。
    刷新间隔 数字 选填 可视化图表应刷新其查询来源的频率(以秒为单位)。请仅在指定 dataSourceUrl 时使用此项。
    视图 对象或数组 选填 设置 DataView 初始化程序对象,该对象可用作对基础数据的过滤条件(由 dataTabledataSourceUrl 参数定义)。 您可以传入字符串或 DataView 初始化程序对象,例如 dataview.toJSON() 返回的对象。 示例"view": {"columns": [1, 2]} 还可以传入 DataView 初始化程序对象的数组,在这种情况下,数组中的第一个 DataView 会应用于底层数据以创建新的数据表,第二个 DataView 会应用于因应用第一个 DataView 而产生的数据表,依此类推。

    示例

    基于电子表格数据源创建表格图表,并添加 SELECT A,D WHERE D > 100 ORDER BY D 查询

    <script type="text/javascript">
      google.charts.load('current');  // Note: No need to specify chart packages.
      function drawVisualization() {
        google.visualization.drawChart({
          "containerId": "visualization_div",
          "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
          "query":"SELECT A,D WHERE D > 100 ORDER BY D",
          "refreshInterval": 5,
          "chartType": "Table",
          "options": {
            "alternatingRowStyle": true,
            "showRowNumber" : true
          }
       });
     }
    google.charts.setOnLoadCallback(drawVisualization);
    </script>

    以下示例会创建相同的表,但会在本地创建 DataTable

    <script type='text/javascript'>
      google.charts.load('current');
      function drawVisualization() {
        var dataTable = [
          ["Country", "Population Density"],
          ["Indonesia", 117],
          ["China", 137],
          ["Nigeria", 142],
          ["Pakistan", 198],
          ["India", 336],
          ["Japan", 339],
          ["Bangladesh", 1045]
        ];
        google.visualization.drawChart({
          "containerId": "visualization_div",
          "dataTable": dataTable,
          "refreshInterval": 5,
          "chartType": "Table",
          "options": {
            "alternatingRowStyle": true,
            "showRowNumber" : true,
          }
        });
      }
      google.charts.setOnLoadCallback(drawVisualization);
    </script>

    以下示例传入了图表的 JSON 字符串表示法(您可能已从文件加载图表):

    <script type="text/javascript">
      google.charts.load('current');
      var myStoredString = '{"containerId": "visualization_div",' +
        '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
        '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
        '"refreshInterval": 5,' +
        '"chartType": "Table",' +
        '"options": {' +
        '   "alternatingRowStyle": true,' +
        '   "showRowNumber" : true' +
        '}' +
      '}';
      function drawVisualization() {
        google.visualization.drawChart(myStoredString);
      }
      google.charts.setOnLoadCallback(drawVisualization);
    </script>

    drawToolbar()

    这是可以附加到许多可视化图表的工具栏元素的构造函数。通过此工具栏,用户可以将可视化图表数据导出为不同的格式,或者提供嵌入式的可视化图表版本,以便在不同位置使用。如需了解详情和查看代码示例,请参阅工具栏页面