触发事件

可视化图表可以触发托管网页可以注册接收的事件。 事件可以由用户操作触发（例如用户点击图表），也可以是内部事件（例如每 10 秒触发一个事件）。您可以注册一个 JavaScript 方法，以便在触发特定事件（可能使用特定于该事件的数据）时调用该方法。

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

任何可选择的可视化图表都应触发一个事件：选择事件。不过，此事件的行为和含义由每个可视化图表定义。

如果在 draw 方法将控制权交还给用户后，某可视化图表尚未准备好进行互动，则应触发该可视化图表： ready 事件。 就绪事件部分定义了此事件的确切行为和含义。

请务必注意，Visualization API 事件是相互独立的，与标准 DOM 事件不同。

目录

  1. 触发事件
  2. 选择事件
  3. 就绪事件
  4. 更多信息

触发事件

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

  1. 来源可视化（通常是 this 值）。
  2. 事件名称（字符串）。
  3. 事件详细信息（对象）。特定事件详细信息的可选映射（名称/值）。

下面的示例展示了可视化图表如何引发 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;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

托管网页可以通过调用 google.visualization.events.addListener() 或 google.visualization.events.addOneTimeListener() 进行注册以接收您的事件。请务必全面记录您触发的所有事件。

选择事件

“选择”事件是许多可视化图表为响应用户鼠标点击而抛出的标准事件。如果您选择触发事件来响应鼠标点击，则应以下述标准方式实现“select”事件：

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

就绪事件

任何可视化图表都应触发一个以标准方式工作的“ready”事件，以告知开发者该可视化图表何时可以处理（称为方法）。（不过，没有绝对要求可视化图表会以这种方式运作；请查看有关可视化图表的文档。）

一般来说，公开“ready”事件的可视化图表采用以下规范：

  • ready 事件不会向该处理程序传递任何属性（您的函数处理程序不应期望向其传递任何参数）。
  • 可视化图表应该 在准备好进行互动后触发 ready 事件。 如果可视化图表的绘制是异步进行的，则务必要在可以实际调用互动方法时（而不仅仅是在 draw 方法结束时）触发事件。
  • 应该在调用 draw 方法之前向此事件添加监听器，否则可能会在设置监听器之前触发该事件，您无法捕获到它。
  • 如果在 ready 事件触发之前调用互动方法，就会面临这些方法无法正常运行的风险。

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

更多信息