本页面介绍了如何监听和处理图表触发的事件。
内容
概览
Google 图表可以触发您可以监听的事件。事件可由用户操作触发,例如在用户点击图表时。您可以注册每次触发特定事件时可能调用的 JavaScript 方法,并且可以使用该事件特有的数据。
每个图表都会定义自己的事件,且该图表的文档应说明每个事件何时触发、这意味着什么,以及如何取回与事件相关的任何信息。本页介绍了如何注册以从图表接收事件,以及如何处理事件。
任何可选图表都应触发一个事件:select 事件。不过,每个事件都会定义该事件的行为和含义。
请务必注意,图表事件与标准 DOM 事件是相互独立的,并且有所不同。
注册和处理事件
如需注册事件处理脚本,您可以使用公开事件的图表的名称、要监听的事件的字符串名称以及触发该事件时要调用的函数的名称来调用 google.visualization.events.addListener()
或 addOneTimeListener()
。您的函数应接受触发的单个参数。此事件可包含有关该事件的自定义信息,如图表文档中所述。
重要提示:如果您的图表公开了 ready event,您应始终等到相应事件被触发,然后再尝试向图表发送方法或接收事件。这些图表在抛出就绪事件之前可能就已经起作用,但无法保证这种行为。
以下代码段会在用户每次点击表行时显示提醒框:
// Create a table chart on your page. var table = new google.visualization.Table(document.getElementById('table_div')); table.draw(data, options); // Every time the table fires the "select" event, it should call your // selectHandler() function. google.visualization.events.addListener(table, 'select', selectHandler); function selectHandler(e) { alert('A table row was selected'); }
请注意,这将仅注册监听此特定表对象的事件;您只能注册接收来自特定对象的事件。
您还可以传入函数定义,如下所示:
// Pass in a function definition. google.visualization.events.addListener(orgchart, 'select', function() { table.setSelection(orgchart.getSelection()); });
检索事件信息
事件通常通过以下两种方式公开信息:将信息作为参数传递到处理程序函数;或将信息添加到全局对象。请参阅该图表的文档,了解事件是否公开以及事件如何公开。以下是检索这两种信息的方法:
传递给处理程序的事件信息
如果图表将数据作为参数传递给处理函数,您将检索该值,如下所示:
// google.visualization.table exposes a 'page' event. google.visualization.events.addListener(table, 'page', myPageEventHandler); ... function myPageEventHandler(e) { alert('The user is navigating to page ' + e['page']); }
传递给处理程序的参数将具有应为图表记录的属性。如需查看以这种方式公开事件信息的图表示例,请参阅表格图表的页面事件。
传递给全局对象的事件信息
某些事件会更改全局对象的属性,然后您可以请求该属性。一个常见的示例是“select”事件,系统会在用户选择图表的一部分时触发。在这种情况下,代码必须对图表调用 getSelection() 才能了解当前选择的内容。如需了解详情,请参阅下方的选择事件。
// orgChart is my global orgchart chart variable. google.visualization.events.addListener(orgChart, 'select', selectHandler); ... // Notice that e is not used or needed. function selectHandler(e) { alert('The user selected' + orgChart.getSelection().length + ' items.');
select 事件
如前所述,任何可供选择的图表都应触发“select”事件,而标准事件允许您检索图表中选定项的值。(不过,图表没有绝对的要求;请参阅图表文档。)
通常,公开“select”事件的图表是遵循以下规范设计的:
- select 事件不会将任何属性或对象传递给处理程序(您的函数处理程序不应预期向其传递任何参数)。
- 该图表应该公开
getSelection()
方法,该方法会返回一组描述所选数据元素的对象。这些对象具有row
和column
属性。row
和column
是DataTable
中选定项的行和列索引。(选择事件描述图表中的基础数据,而不是图表中的 HTML 元素。)如需获取所选数据,您必须调用DataTable.getValue()
或getFormattedValue()
。
如果同时指定了row
和column
,则所选元素是一个单元格。 如果仅指定了row
,则所选元素将是一行。如果仅指定了column
,所选元素将是一个列。 - 该图表应公开
setSelection(selection)
方法,以更改底层表中的选择,并在图表中选择相应的数据。selection 参数,它是类似于getSelection()
数组的数组,其中每个元素都是一个属性为row
和column
的对象。row
属性定义DataTable
中所选行的索引,column
属性定义DataTable
中所选列的索引。调用此方法时,图表应直观地指出新选择的内容。setSelection()
的实现不应触发“select”事件。
如果同时指定了row
和column
,则所选元素是一个单元格。 如果仅指定了row
,则所选元素将是一行。如果仅指定了column
,所选元素将是一个列。
一些注意事项:
- 图表可能会忽略部分选择。(例如,可能仅显示所选行的表可能会忽略其
setSelection
实现中的单元格或列元素。) - 某些图表可能不会触发“选择”事件,而有些图表可能仅支持整个行选择或整个列选择。每个图表的文档都定义了它支持的事件和方法。
- 多选题在不同图表的处理方式不同(有些甚至不允许)。
- 为了读取所选数据,您需要在处理程序中调用
DataTable.getValue()
;最简单的启用方法是使DataTable
对象是全局的。
以下示例会在用户选择表格图表的某个元素后,弹出包含所选表格元素的提醒框:
请注意,表图表仅触发行选择事件;但是,代码是通用的,可用于行、列和单元格选择事件。
以下是该示例的处理程序代码:
// Create our table. var table = new google.visualization.Table(document.getElementById('table_div')); table.draw(data, options); // Add our selection handler. google.visualization.events.addListener(table, 'select', selectHandler); // The selection handler. // Loop through all items in the selection and concatenate // a single message from all of them. function selectHandler() { var selection = table.getSelection(); var message = ''; for (var i = 0; i < selection.length; i++) { var item = selection[i]; if (item.row != null && item.column != null) { var str = data.getFormattedValue(item.row, item.column); message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n'; } else if (item.row != null) { var str = data.getFormattedValue(item.row, 0); message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n'; } else if (item.column != null) { var str = data.getFormattedValue(0, item.column); message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n'; } } if (message == '') { message = 'nothing'; } alert('You selected ' + message); }
ready 事件
大多数图表都是异步渲染的;所有 Google 图表都会在您对它们调用 draw()
后抛出就绪事件,表示图表已渲染,可以返回属性或处理其他方法调用。在调用 draw()
之后,应始终监听就绪事件,然后再尝试对其调用方法。
通常,公开“ready”事件的图表是遵循以下规范设计的:
- ready event 不会将任何属性传递给处理程序(您的函数处理程序不应预期会向其传递任何参数)。
- 图表应该在准备好用于互动后触发 prepare 事件。
如果图表是异步绘制的,请务必确保在实际可以调用互动方法时触发事件,而不仅仅是在
draw
方法结束时触发。 - 您应先向此事件添加监听器,然后再调用
draw()
方法,否则事件可能会在设置监听器之前触发,因而您不会捕获到该事件。 - 如果在触发 ready 事件之前调用互动方法,您可能会面临这些方法无法正常工作的风险。
惯例是,未触发“ready”事件的图表在 draw
方法结束并立即将控制权返还给用户后,就可以立即进行交互。如果图表触发就绪事件,则应等待系统抛出该事件,然后再对其调用方法,如下所示:
google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);
Ready Event 处理程序语法
function myReadyHandler(){...}
系统不会向 Ready 事件处理脚本传递任何参数。
error 事件
图表在遇到某种错误时应抛出错误事件,以便您对其进行适当处理。系统会向事件处理脚本传递错误说明,以及每个图表专用的自定义事件属性。您应在实例化图表后立即订阅此事件,以捕获后续步骤中可能发生的任何错误。
您可以使用 goog.visualization.errors
辅助函数来帮助您向用户显示适当的错误。
错误事件处理脚本语法
function myErrorHandler(err){...}
应向错误成员处理程序传递具有以下成员的对象:
- id [必需] - 包含图表的 DOM 元素的 ID,如果无法呈现,则会显示错误消息,而不是图表。
- message [必需] - 描述错误的简短消息字符串。
- detailedMessage [可选] - 错误的详细说明。
- options [可选] - 一个对象,包含适合此错误和图表类型的自定义参数。
事件处理示例
以下示例演示了 getSelection() 和 setSelection()。该示例同步了两个使用相同数据表的图表。 点击任一图表即可同步其他图表中的选择。
// Create our two charts. var table = new google.visualization.Table(document.getElementById('table_div')); table.draw(data, {}); var orgchart = new google.visualization.OrgChart(document.getElementById('org_div')); orgchart.draw(data, {}); // When the table is selected, update the orgchart. google.visualization.events.addListener(table, 'select', function() { orgchart.setSelection(table.getSelection()); }); // When the orgchart is selected, update the table chart. google.visualization.events.addListener(orgchart, 'select', function() { table.setSelection(orgchart.getSelection()); });