您的可视化图表可以触发托管网页可注册接收的事件。事件可由用户操作(例如,用户点击图表)触发,也可以由内部触发:例如,每 10 秒触发一次事件。您可以注册 JavaScript 方法,以便在每次触发特定事件时调用,该事件可能会使用相应事件特有的数据。
每个可视化图表都会定义自己的事件,并且有关该可视化图表的文档应描述每个事件何时触发、含义以及发送给事件处理脚本的信息(例如,请参阅 orgchart 可视化)。本页面介绍了可视化图表创建者如何触发事件。如需了解客户端如何注册以接收事件,请参阅处理事件页面。
有一事件会触发任何可选择的可视化图表:select 事件。 不过,此事件的行为和含义均由各个可视化图表定义。
如果可视化内容在 draw
方法向用户返回控制权后无法立即互动,则应触发该可视化事件:准备就绪事件。
Event 部分中定义了该事件的确切行为和含义。
请务必注意,可视化 API 事件与标准 DOM 事件相互独立且截然不同。
内容
触发事件
如需从可视化图表中触发事件,请调用 google.visualization.events.trigger()
函数。该函数需要以下参数:
- 来源可视化图表(通常是
this
值)。 - 事件名称(字符串)。
- 事件详情(对象)。包含具体活动详情的可选地图(名称/值)。
以下示例展示了可视化图表如何抛出选择事件:
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; // Fire a select event. google.visualization.events.trigger(this, 'select', {}); };
托管页面可以通过调用 google.visualization.events.addListener()
或 google.visualization.events.addOneTimeListener()
进行注册,以接收您的事件。请务必全面记录您触发的所有事件。
选择事件
“select”事件是由许多可视化功能在用户响应鼠标点击时抛出的标准事件。如果您选择触发事件来响应鼠标点击,则应按下述标准方式实现“select”事件:
- 当用户在可视化图表中选择一些数据时,触发名为“select”的事件。该事件不会向监听函数发送任何参数。
- 公开
getSelection()
方法(如链接的文档部分所述)。此方法应返回用户选择的 data 元素的索引。
- 公开参考部分中所述的
setSelection()
方法。另请参阅处理事件页面,了解如何处理事件。
事件就绪
任何可视化图表都应触发以“标准”方式触发的“ready”事件,让开发者知道可视化图表何时可以处理所调用的方法。(不过,可视化图表的行为没有绝对要求;如需查看可视化图表,请参阅相关文档)。
通常,公开“ready”事件的可视化对象遵循以下规范:
- ready event 不会将任何属性传递给处理程序(您的函数处理程序不应预期会向其传递任何参数)。
- 在可视化图表做好互动准备后,可视化图表应该触发就绪事件。如果可视化绘制是异步的,请务必调用实际可调用交互方法的事件,而不是仅在
draw
方法结束时触发事件。 - 您应先向此事件添加监听器,然后再调用
draw
方法,否则事件可能会在设置监听器之前触发,因而您不会捕获到该事件。 - 如果在系统调用 event 事件之前调用互动方法,将会面临这些方法无法正常工作的风险。
按照惯例,在 draw
方法结束并将控制权返还给用户后,未触发“ready”事件的可视化图像可立即进行交互。