触发事件

您的可视化图表可以触发托管网页可注册接收的事件。事件可由用户操作(例如,用户点击图表)触发,也可以由内部触发:例如,每 10 秒触发一次事件。您可以注册 JavaScript 方法,以便在每次触发特定事件时调用,该事件可能会使用相应事件特有的数据。

每个可视化图表都会定义自己的事件,并且有关该可视化图表的文档应描述每个事件何时触发、含义以及发送给事件处理脚本的信息(例如,请参阅 orgchart 可视化)。本页面介绍了可视化图表创建者如何触发事件。如需了解客户端如何注册以接收事件,请参阅处理事件页面。

有一事件会触发任何可选择的可视化图表:select 事件。 不过,此事件的行为和含义均由各个可视化图表定义。

如果可视化内容在 draw 方法向用户返回控制权后无法立即互动,则应触发该可视化事件:准备就绪事件。 Event 部分中定义了该事件的确切行为和含义。

请务必注意,可视化 API 事件与标准 DOM 事件相互独立且截然不同。

内容

触发事件

如需从可视化图表中触发事件,请调用 google.visualization.events.trigger() 函数。该函数需要以下参数:

  1. 来源可视化图表(通常是 this 值)。
  2. 事件名称(字符串)。
  3. 事件详情(对象)。包含具体活动详情的可选地图(名称/值)。

以下示例展示了可视化图表如何抛出选择事件:

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”事件:

  1. 当用户在可视化图表中选择一些数据时,触发名为“select”的事件。该事件不会向监听函数发送任何参数。
  2. 公开 getSelection() 方法(如链接的文档部分所述)。此方法应返回用户选择的 data 元素的索引。
  3. 公开参考部分中所述的 setSelection() 方法。另请参阅处理事件页面,了解如何处理事件。

事件就绪

任何可视化图表都应触发以“标准”方式触发的“ready”事件,让开发者知道可视化图表何时可以处理所调用的方法。(不过,可视化图表的行为没有绝对要求;如需查看可视化图表,请参阅相关文档)。

通常,公开“ready”事件的可视化对象遵循以下规范:

  • ready event 不会将任何属性传递给处理程序(您的函数处理程序不应预期会向其传递任何参数)。
  • 在可视化图表做好互动准备后,可视化图表应该触发就绪事件。如果可视化绘制是异步的,请务必调用实际可调用交互方法的事件,而不是仅在 draw 方法结束时触发事件。
  • 您应先向此事件添加监听器,然后再调用 draw 方法,否则事件可能会在设置监听器之前触发,因而您不会捕获到该事件。
  • 如果在系统调用 event 事件之前调用互动方法,将会面临这些方法无法正常工作的风险。

按照惯例,在 draw 方法结束并将控制权返还给用户后,未触发“ready”事件的可视化图像可立即进行交互。

详细信息