本页面列出了 Google 可视化 API 公开的对象,以及所有可视化图表提供的标准方法。
注意:Google 可视化图表 API 命名空间为google.visualization.*
- DataTable 类
- DataView 类
- Chart 封装容器类
- ChartEditor 类
- 数据操纵方法
- 格式化程序
- GadgetHelper 类
- 查询类
- 错误显示类
- 事件
- google.visualization.events.addListener()
- google.visualization.events.addOneTimeListener()
- google.visualization.events.removeListener()
- google.visualization.events.removeAllListeners()
- google.visualization.events.trigger()
- 标准可视化方法和属性
- 各种静态方法
数组备注
某些浏览器无法正确处理 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'}] ]);
如需创建 DataTable
,您可以调用不带参数的构造函数,然后调用下文列出的 addColumn()
/addRows()
方法添加值,或者传入已填充的 JavaScript 字面量对象以对其进行初始化。下文介绍了这两种方法。您应该使用哪种方式?
-
通过调用
addColumn()
、addRow()
和addRows()
,在 JavaScript 中创建和填充表是非常易读的代码。当您手动输入代码时,此方法很有用。速度慢于使用对象字面量表示法(如下文所述),但在较小的表格中(例如 1000 个单元格)中,您可能不会注意到太多变化。 -
在大型表中,使用对象字面量表示法直接声明
DataTable
对象要快得多。但是,这可能是一项棘手的语法;如果您可以在代码中生成对象字面量语法,则可以使用此语法,这样可以降低出错的可能性。
方法
方法 | 返回值 | 说明 |
---|---|---|
或
|
数字 |
向数据表添加新列,然后返回新列的索引。系统会为新列的所有单元格分配 第一个签名具有以下参数:
第二个签名有一个对象参数,其中具有以下成员:
另请参阅:getColumnId、getColumnLabel、getColumnType、insertColumn、getColumnRole |
addRow(opt_cellArray) |
数字 |
向数据表添加新行,并返回新行的索引。
示例: 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) |
数字 |
向数据表添加新行,并返回最后添加行的索引。您可以调用此方法来新建空行,也可以使用用于填充行的数据(如下所述)。
示例: 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 查找列,然后再按标签查找列。另请参阅:getColumnId、getColumnLabel |
getColumnLabel(columnIndex) |
字符串 |
返回由底层表中的列索引指定的给定列的标签。 列标签通常在可视化图表中显示。例如,列标签可以显示为表中的列标题,也可以显示为饼图中的图例标签。 对于通过查询检索的数据表,列标签由数据源或查询语言的 label 子句设置。另请参阅:setColumnLabel |
getColumnPattern(columnIndex) |
字符串 |
返回用于设置指定列值的格式。
对于通过查询检索的数据表,列模式由数据源或查询语言的 |
getColumnProperties(columnIndex)
|
对象 |
返回指定列中所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在
|
getColumnProperty(columnIndex, name)
|
自动 |
返回已命名属性的值,如果未为指定的列设置此类属性,则返回
|
getColumnRange(columnIndex) |
对象 |
返回指定列中值的最小值和最大值。返回的对象具有
|
getColumnRole(columnIndex) |
字符串 | 返回指定列的角色。 |
getColumnType(columnIndex) |
字符串 |
返回列索引指定的给定列的类型。
返回的列类型可以是以下项之一: |
getDistinctValues(columnIndex) |
对象数组 |
以升序返回特定列中的唯一值。
返回对象的类型与 |
getFilteredRows(filters) |
对象数组 |
返回与所有给定过滤条件匹配的行的行索引。索引按升序返回。此方法的输出可用作
另一个可选属性
示例: |
getFormattedValue(rowIndex, columnIndex)
|
字符串 |
根据指定的行和列索引,返回单元格的格式化值。
如需详细了解如何设置列值的格式,请参阅查询语言参考文档。 另请参阅:setFormattedValue |
getNumberOfColumns() |
数字 | 返回表中的列数。 |
getNumberOfRows() |
数字 | 返回表中的行数。 |
getProperties(rowIndex, columnIndex)
|
对象 |
返回指定单元格内所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在
|
getProperty(rowIndex, columnIndex, name)
|
自动 |
返回指定属性的值,如果指定的单元格未设置该属性,则返回
|
getRowProperties(rowIndex)
|
对象 |
返回指定行中所有属性的映射。请注意,属性对象通过引用返回,因此,在检索到的对象中更改值也会在
|
getRowProperty(rowIndex, name)
|
自动 |
返回已命名属性的值,如果未为指定行设置此类属性,则返回
|
getSortedRows(sortColumns) |
数字数组 |
返回经过排序的表版本,而不修改底层数据的顺序。
如需对基础数据进行永久排序,请调用
返回的值是一个数字数组,每个数字都是一个
请注意,排序一定是稳定的:这意味着,如果您按两行相等的值排序,则同一排序将每次都以相同的顺序返回行。 示例:如需遍历按第三列排序的行,请使用以下命令: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); } |
getTableProperties
|
对象 | 返回表中所有属性的映射。 |
getTableProperty(name) |
自动 |
返回已命名属性的值,如果未为表设置此类属性,则返回
|
getValue(rowIndex, columnIndex) |
对象 |
返回单元格在给定行索引和列索引处的值。
返回值的类型取决于列类型(请参阅 getColumnType):
|
insertColumn(columnIndex, type [,label [,id]])
|
无 |
向特定表中的数据表插入新列。指定索引处或之后的所有现有列都会转移到索引更高。
另请参阅:addColumn |
insertRows(rowIndex, numberOrArray) |
无 |
在指定的行索引处插入指定的行数。
另请参阅:addRows |
removeColumn(columnIndex) |
无 |
移除指定索引处的列。
另请参阅:removeColumns |
removeColumns(columnIndex, numberOfColumns)
|
无 |
从指定索引处的列移除指定数量的列。
另请参阅:removeColumn |
removeRow(rowIndex) |
无 |
移除指定索引处的行。
另请参阅:removeRows |
removeRows(rowIndex, numberOfRows) |
无 |
从指定索引处的行中移除指定的行数。
另请参阅:removeRow |
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])
|
无 |
设置单元格的值、格式值和/或属性。
另请参阅:setValue()、setFormattedValue()、setProperty()、setProperties()。 |
setColumnLabel(columnIndex, label)
|
无 |
设置列的标签。
另请参阅:getColumnLabel |
setColumnProperty(columnIndex, name, value)
|
无 |
设置单列属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。
|
setColumnProperties(columnIndex, properties)
|
无 |
设置多个列属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。
|
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
无 |
设置单元格的格式化值。
另请参阅:getFormattedValue |
setProperty(rowIndex, columnIndex, name, value)
|
无 |
设置单元格属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。
|
setProperties(rowIndex, columnIndex, properties)
|
无 |
设置多个单元格属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。
|
setRowProperty(rowIndex, name, value)
|
无 |
设置行属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化图表文档,了解受支持的属性。
|
setRowProperties(rowIndex, properties)
|
无 |
设置多个行属性。某些可视化图表支持行、列或单元格属性来修改其显示方式或行为;请参阅可视化文档,了解受支持的属性。
|
setTableProperty(name, value)
|
无 |
设置单个表属性。某些可视化功能支持通过表格、行、列或单元格属性来修改其显示方式或行为;如需了解哪些属性受支持,请参阅可视化文档。
|
setTableProperties(properties) |
无 |
设置多个表属性。某些可视化功能支持通过表格、行、列或单元格属性来修改其显示方式或行为;如需了解哪些属性受支持,请参阅可视化文档。
|
setValue(rowIndex, columnIndex, value) |
无 |
设置单元格的值。除了覆盖任何现有的单元值外,此方法还会清除该单元的任何格式化值和属性。
|
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 对象包含两个必需的顶级属性 cols
和 rows
,以及一个可选的 p
属性,该属性是任意值的映射。
注意:显示的所有属性名称和字符串常量都区分大小写。此外,被描述为采用字符串值的属性应将其值括在引号中。例如,如果要将类型属性指定为数字,可以按如下方式表示:type: 'number'
;但值本身(数字)可以表示为:v: 42
cols
属性
cols
是描述每列的 ID 和类型的对象数组。每个属性都是一个具有以下属性的对象(区分大小写):
-
type
[必需] 列中数据的数据类型。支持以下字符串值(示例包括 v: 属性,将在后面介绍):-
'boolean' - JavaScript 布尔值(“true”或“false”)。示例值:
v:'true'
-
'number' - JavaScript 数值。示例值:
v:7
、v:3.14
、v:-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]
-
'boolean' - JavaScript 布尔值(“true”或“false”)。示例值:
-
id
[可选] 列的字符串 ID。不得重复。请使用基本的字母数字字符,因此托管网页无需使用花哨的转义字符即可通过 JavaScript 访问此列。请注意不要选择 JavaScript 关键字。示例:id:'col_1'
-
label
[可选] 某些可视化图表为此列显示的字符串值。示例:label:'Height'
-
pattern
[可选] 数据源用来设置数字、日期或时间列值格式的字符串模式。这些信息仅供参考;您可能不需要读取该模式,也不存在此模式。Google 可视化客户端不使用此值(它会读取单元格的格式化值)。如果DataTable
来自数据源以响应带有 format 子句的查询,那么您在该子句中指定的模式可能会返回此值。推荐的模式标准是 ICU DecimalFormat 和 SimpleDateFormat。 -
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
属性存储了行对象的数组。
每个行对象都有一个名为 c
的必需属性,该属性是该行中的单元格数组。它还具有一个可选的 p
属性,用于定义要分配给整行的任意自定义值的映射。如果您的可视化图表支持任何行级属性,则会对其进行说明;否则,系统会忽略此属性。
表中的每个单元格都由具有以下属性的对象描述:
-
v
[可选] 单元格值。数据类型应与列数据类型相匹配。如果单元格为 null,v
属性应为 null,但仍然可以具有f
和p
属性。 -
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
-
用于初始化视图的
DataTable
或DataView
。默认情况下,该视图会按原始顺序包含底层数据表或视图中的所有列和行。如需在此视图中隐藏或显示行或列,请调用相应的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)
|
数字 |
返回由给定视图(此视图的索引)指定的指定表(或视图)中的索引。
示例:如果之前调用过 |
getTableRowIndex(viewRowIndex) |
数字 |
返回由该行的索引在此视图指定的给定表(或视图)中的索引。
示例:如果之前调用过 |
getViewColumnIndex(tableColumnIndex)
|
数字 |
返回此视图中的索引,该索引映射到其在底层表(或视图)中的索引指定的给定列。如果存在多个这样的索引,则返回第一个(最小)索引。如果不存在此类索引(指定的列不在视图中),则返回 -1。
示例:如果之前调用过 |
getViewColumns() |
数字数组 |
按顺序返回此视图中的列。也就是说,如果您使用某个数组调用 |
getViewRowIndex(tableRowIndex) |
数字 |
返回此视图中的索引,该索引映射到其在底层表(或视图)中的索引指定的给定行。如果存在多个这样的索引,则返回第一个(最小)索引。如果不存在此类索引(指定的行不在视图中),则返回 -1。
示例:如果之前调用过 |
getViewRows() |
数字数组 |
按顺序返回此视图中的行。也就是说,如果您使用某个数组调用 |
hideColumns(columnIndexes) |
无 |
在当前视图中隐藏指定的列。
示例:如果您的表包含 10 列,并且依次调用 |
hideRows(min, max) |
无 |
从当前视图中隐藏索引介于介于最小值和最大值(含)之间的所有行。
这是 |
hideRows(rowIndexes) |
无 |
在当前视图中隐藏指定行。
示例:如果您的表包含 10 行,您依次调用 |
setColumns(columnIndexes) |
无 |
指定哪些视图会显示在此视图中。所有未指定的列都将被隐藏。 这是底层表/视图中的列索引的数组,或计算列。如果您不调用此方法,则默认显示所有列。该数组还可以包含重复项,以便多次显示同一列。列将按照指定的顺序显示。
示例: // 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) |
无 |
根据底层表/视图中的索引编号,设置此视图中可见的行。
示例:如需创建具有底层表/视图第 3 行和零行的视图,请执行以下操作: |
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) |
无 |
绘制图表。您必须对图表或数据进行任何更改后调用此方法,才能显示更改。
|
toJSON() |
字符串 | 返回图表的 JSON 表示法的字符串版本。 |
clone() |
图表封装容器 | 返回图表封装容器的深层副本。 |
getDataSourceUrl() |
字符串 | 如果此图表从数据源获取数据,则返回此数据源的网址。否则,返回 null。 |
getDataTable() |
google.visualization.DataTable |
如果此图表从本地定义的
下次返回 |
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) |
任何类型 |
返回指定的图表选项值
|
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,请执行以下操作:
-
加载
charteditor
软件包。 在google.charts.load()
中,加载软件包“charteditor”。您无需加载您在编辑器中呈现的图表类型的软件包;图表编辑器会根据需要为您加载所有软件包。 -
创建一个
ChartWrapper
对象,以定义可供用户自定义的图表。该图表将显示在对话框中,用户可以使用编辑器重新设计图表、更改图表类型,甚至更改源数据。 -
创建一个新的 ChartEditor 实例,并注册以监听“ok”事件。用户点击对话框中的“OK”按钮时,系统会抛出此事件。收到后,您应调用
ChartEditor.getChartWrapper()
来检索用户修改的图表。 -
调用
ChartEditor.openDialog()
,并传入ChartWrapper
。系统随即会打开该对话框。对话框按钮使用户能够关闭编辑器。只要ChartEditor
实例在范围内,该实例就会一直可用;它不会在用户关闭对话框后自动销毁。 - 要在代码中更新图表,请调用
setChartWrapper()
。
方法
方法 | 返回值 | 说明 |
---|---|---|
openDialog(chartWrapper, opt_options) |
null |
将图表编辑器作为页面上的嵌入式对话框打开。该函数会立即返回,不会等待对话框关闭。如果您未丢失实例的作用域,可以再次调用
|
getChartWrapper() |
ChartWrapper |
返回表示图表的 ChartWrapper ,其中包含用户修改。 |
setChartWrapper(chartWrapper) |
null |
使用此方法可更新编辑器上呈现的图表。
chart 封装容器 - 一个 |
closeDialog() |
null | 关闭图表编辑器对话框。 |
选项
图表编辑器支持以下选项:
名称 | 类型 | 默认 | 说明 |
---|---|---|---|
dataSourceInput |
元素句柄或“urlbox” | null |
使用此方法可让用户为图表指定数据源。此属性可以是以下两个值之一:
|
活动
图表编辑器会抛出以下事件:
名称 | 说明 | 属性 |
---|---|---|
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
命名空间包含几个有用的聚合值(例如 sum 和 count),但您可以定义自己的聚合值(例如 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。
返回值
DataTable
,keys 中列出的每列都有一列,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()
此方法将两个数据表(DataTable
或 DataView
对象)联接到一个结果表中,类似于 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
。
返回值
包含键列、dt1Columns 和 dt2Columns 的 DataTable
。此表格按键列从左到右排序。当 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 可视化格式化程序会覆盖所有用户定义的格式化程序。
- 获取已填充的
DataTable
对象。 - 对于您要重新设置格式的每一列,请按以下步骤操作:
- 创建一个对象,用于指定格式化程序的所有选项。这是一个包含一组属性和值的基本 JavaScript 对象。请参阅格式化程序的文档,了解受支持的属性。(可选,您可以传入用于指定选项的对象字面量表示法对象。)
- 创建格式化程序,并传入选项对象。
-
调用
formatter
.format(table, colIndex)
,传入DataTable
和要重新格式化的数据的列(从零开始)。请注意,您只能对每个列应用一个格式化程序;应用第二个格式化程序只是会覆盖第一个格式化程序的效果。
重要提示:许多格式设置工具要求使用 HTML 标记显示特殊格式;如果可视化图表支持allowHtml
选项,您应将其设置为 true。
应用于数据的实际格式来自使用该 API 加载的语言区域。 如需了解详情,请参阅加载包含特定语言区域的图表。
重要提示:格式化程序只能与 DataTable
一起使用,不能与 DataView
一起使用(DataView
对象为只读)。
以下是使用格式化程序的常规步骤:
以下示例将日期列的格式日期值更改为使用长日期格式(“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 名称。
// 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) |
重新设置指定列中数据的格式。
|
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 范围中的值的所有单元格分配 color 和 bgcolor。务必要知道该范围不包含边界值,因为创建一个介于 1—1000 与 1000—2000 之间的范围并不涵盖值 1000!
|
addGradientRange(from, to, color, fromBgColor,
toBgColor)
|
根据单元格值指定某个范围内的背景颜色。系统会根据单元格值在从下边界颜色到上边界颜色的范围内缩放颜色。请注意,此方法无法像
|
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 日,如下所示:
您不能同时指定 |
pattern |
要应用于该值的自定义格式模式,类似于 ICU 日期和时间格式。例如:
您不能同时指定 |
timeZone |
显示日期值的时区。这是一个数值,表示 GMT + 此时区数量(可为负数)。默认情况下,创建日期对象时假定使用的是其创建计算机所在的时区;此选项用于以不同时区显示该值。例如,如果您在位于英国格林尼治的计算机上将日期对象设置为下午 5 点,并将时区指定为 -5(options['timeZone'] = -5 ,或美国东部太平洋时间),则显示的值将是中午 12 点。 |
方法
DateFormat
支持以下方法:
方法 | 说明 |
---|---|
google.visualization.DateFormat(options) |
构造函数。如需了解详情,请参阅上面的选项部分。 |
format(dataTable, columnIndex) |
将格式应用于指定列的标准 format() 方法。 |
formatValue(value) |
返回给定值的格式化值。此方法不需要 |
示例代码
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 月:
|
“7 月” “07” |
d | 一月中的天。额外的“d”值将添加前导零。 | 10 |
小时 | 12 小时制的小时。额外的“h”值将添加前导零。 | 12 |
H | 24 小时制的小时值。额外的 HK' 值将添加前导零。 | 0 |
m | 一小时中的分钟。额外的“M”值将添加前导零。 | 30 |
秒 | 一分钟中的秒。额外的 's' 值将添加前导零。 | 55 |
S | 小数部分。额外的“S”值右侧将填充零。 | 978 |
E |
星期几。“Tuesday”的输出如下所示:
|
“星期二” “星期二” |
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 |
格式字符串。提供后,系统会忽略除
格式字符串是 ICU 模式集的子集。例如,对于值 10、7.5 和 0.5, |
prefix |
值的字符串前缀,例如“$”。 |
suffix |
值的字符串后缀,例如“%”。 |
方法
NumberFormat
支持以下方法:
方法 | 说明 |
---|---|
google.visualization.NumberFormat(options) |
构造函数。如需了解详情,请参阅上面的选项部分。 |
format(dataTable, columnIndex) |
将 format() 格式应用于指定列的标准方法。 |
formatValue(value) |
返回给定值的格式化值。此方法不需要 |
示例代码
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) |
构造函数。不接收选项对象。相反,它接受字符串模式参数。这是一个字符串,用于说明要放入目标列中的列值以及任意文本。在字符串中嵌入占位符以指示要嵌入另一列中的值。占位符为
示例代码以下示例演示了用于创建锚点元素的模式的构造函数,其中第一个和第二个元素取自 var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); |
format(dataTable, srcColumnIndices,
opt_dstColumnIndex)
|
标准格式调用,以及一些其他参数:
请参见表格后面的格式示例。 |
以下是一些四列表格的一些输入和输出示例。
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
|
validateResponse(response) |
布尔值 |
静态。参数 response 的类型为 google.visualization.QueryResponse。如果响应包含数据,则返回 true 。如果查询执行失败并且响应不包含数据,则返回 false 。如果发生错误,此方法会显示错误消息。
|
查询类
您可以使用以下对象将数据查询发送到外部数据源,例如 Google 电子表格。
- 查询 - 封装传出数据请求。
- QueryResponse - 处理来自数据源的响应。
查询
表示发送到数据源的查询。
构造函数
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”时使用和必需。
-
sendMethod - [可选,字符串] 指定用于发送查询的方法。选择以下字符串值之一:
方法
方法 | 返回值 | 说明 |
---|---|---|
abort() |
无 |
停止使用 setRefreshInterval() 启动的自动查询发送。
|
setRefreshInterval(seconds)
|
无 |
将查询设置为从首次显式调用 如果您使用此方法,则应先调用该方法,然后再调用
如需取消此方法,您可以再次调用它(默认为零),或者调用 |
setTimeout(seconds) |
无 |
设置在引发超时错误之前等待数据源响应的秒数。seconds 是一个大于零的数字。默认超时时间为 30 秒。如果使用此方法,则应先调用 send ,再调用该方法。
|
setQuery(string) |
无 |
设置查询字符串。string 参数的值应该是有效的查询。如果使用此方法,则应在调用 send 方法之前调用此方法。
详细了解查询语言。
|
send(callback) |
无 |
将查询发送到数据源。callback 应该是在数据源响应时调用的函数。回调函数将收到一个类型为 google.visualization.QueryResponse 的参数。 |
查询响应
表示从数据源收到的查询执行的响应。此类的实例会作为参数传递给在调用 Query.send 时设置的回调函数。
方法
方法 | 返回值 | 说明 |
---|---|---|
getDataTable() |
数据表 |
返回数据源返回的数据表。如果查询执行失败并且未返回任何数据,则返回 null 。 |
getDetailedMessage() |
字符串 | 返回失败查询的详细错误消息。如果查询执行成功,此方法将返回空字符串。返回的消息是一条面向开发者的消息,可能包含技术信息,例如“{salary} 列不存在”。 |
getMessage() |
字符串 | 为失败的查询返回简短的错误消息。如果查询执行成功,此方法将返回空字符串。返回的消息是一条供最终用户使用的简短消息,例如“查询无效”或“访问遭拒”。 |
getReasons() |
字符串数组 |
返回一个包含零个或更多条目的数组。每个条目都是一个短字符串,其中包含在执行查询时引发的错误或警告代码。可能的代码:
|
hasWarning() |
布尔值 | 如果查询执行有任何警告消息,则返回 true 。 |
isError() |
布尔值 |
如果查询执行失败,并且响应不包含任何数据表,则返回 true 。如果查询执行成功且响应包含数据表,则返回 <false>。 |
错误显示
该 API 提供了若干函数来帮助您向用户显示自定义错误消息。要使用这些函数,请在页面上提供一个容器元素(通常是 <div>
),API 会在此元素中绘制格式化的错误消息。此容器可以是可视化容器元素,也可以是仅用于出现错误的容器。如果您指定可视化图表包含元素,则可视化图表将会显示错误消息。然后,调用以下相应的函数以显示或移除错误消息。
所有函数都是命名空间 google.visualization.errors
中的静态函数。
许多可视化图表都可能会引发错误事件;请参阅下面的错误事件以了解详情。
您可以在查询封装容器示例中查看自定义错误示例。
功能 | 返回值 | 说明 |
---|---|---|
addError(container, message, opt_detailedMessage,
opt_options)
|
用于标识已创建的错误对象的字符串 ID 值。这是页面上的唯一值,可用于移除错误或查找其包含的元素。 |
使用指定的文本和格式向指定的页面元素添加错误显示块。
|
addErrorFromQueryResponse(container, response) |
字符串 ID 值,用于标识已创建的错误对象;如果响应未指示错误,则返回 null。这是页面上的唯一值,可用于移除错误或查找其包含的元素。 |
将查询响应和错误消息容器传递给此方法:如果查询响应指示查询错误,则在指定页面元素中显示错误消息。如果查询响应为 null,该方法将抛出 JavaScript 错误。将查询处理程序中收到的 QueryResponse 传递给此消息,以显示错误。它还会根据类型设置错误的显示样式(错误或警告,类似于
|
removeError(id) |
布尔值:如果移除了错误,则返回 true,否则返回 false。 |
从页面中移除由 ID 指定的错误。
|
removeAll(container) |
无 |
从指定容器中移除所有错误块。如果指定的容器不存在,则会抛出错误。
|
getContainer(errorId) |
处理包含指定错误的 DOM 元素的句柄;如果找不到,则为 null。 |
用于检索包含 errorID 指定的错误的容器元素的句柄。
|
事件
大多数可视化图表都会触发事件,以表明发生了一些事情。作为图表的用户,您可能经常希望监听这些事件。如果您编写您自己的可视化图表,可能还需要自行触发此类事件。
通过以下方法,开发者可以监听事件、移除现有事件处理脚本或在可视化图表中触发事件。
- google.visualization.events.addListener() 和 google.visualization.events.addOneTimeListener() 监听事件。
- google.visualization.events.removeListener() 移除现有监听器
- google.visualization.events.removeAllListeners() 可移除特定图表的所有监听器
- google.visualization.events.trigger() 会触发事件。
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); }
标准可视化方法和属性
每个可视化图表都应公开以下一组必需的和可选的方法和属性。不过请注意,我们并未强制实施类型检查,因此您应该阅读每个可视化图表的文档。
- 构造函数
- draw()
- getAction() [可选]
- getSelection() [可选]
- removeAction() [可选]
- setAction() [可选]
- setSelection() [可选]
注意:这些方法位于可视化图表的命名空间中,而不是位于 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])
- 数据
-
一个
DataTable
或DataView
,用于存储用于绘制图表的数据。没有从图表中提取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:一个由所选对象组成的数组,其中的每个对象都描述用于创建可视化图表的底层数据元素(DataView
或 DataTable
)。每个对象都具有 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
方法还可以定义另外两个属性:visible
和 enabled
。这些属性应是返回 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
-
一个由对象组成的数组,其中每个对象都有一个数字行和/或列属性。
row
和column
是数据表中所选内容的行号或列数(从零开始)。如需选择整列,请将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 可视化,此方法将为您加载该库;您必须明确加载第三方可视化。示例:Table 、PieChart 、example.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 初始化程序对象,该对象可用作对基础数据的过滤条件(由 dataTable 或 dataSourceUrl 参数定义)。
您可以传入字符串或 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()
这是可以附加到许多可视化图表的工具栏元素的构造函数。通过此工具栏,用户可以将可视化图表数据导出为不同的格式,或者提供嵌入式的可视化图表版本,以便在不同位置使用。如需了解详情和查看代码示例,请参阅工具栏页面。