此页面由 Cloud Translation API 翻译。

处理事件

本页介绍了如何监听和处理图表触发的事件。

概览

Google 图表可以触发您可以监听的事件。事件可以由用户操作触发，例如用户点击图表。您可以注册一个 JavaScript 方法，以便在触发某些事件时调用（可能使用特定于该事件的数据）。

每个图表都会定义自己的事件，并且该图表的文档应描述每个事件的触发时间、事件含义以及如何返回与事件相关的任何信息。本页介绍了如何注册以从图表接收事件，以及如何处理这些事件。

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

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

注册和处理事件

如需注册事件处理脚本，请调用 google.visualization.events.addListener() 或 addOneTimeListener()，并提供显示事件的图表的名称、要监听的事件的字符串名称，以及触发该事件时要调用的函数的名称。您的函数应接受一个参数，即被触发的事件。此事件可包含有关该事件的自定义信息，如图表文档中所述。

重要提示：如果您的图表公开了 ready 事件，您应始终等待该事件触发，然后再尝试从图表发送方法或接收事件。这些图表在抛出 ready 事件之前可能仍然适用，但不能保证这种行为。

每次用户点击表格中的行时，以下代码段都会显示一个提醒框：

// 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() 才能了解当前选择是什么。下面详细介绍了 select 事件。

// 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 实现中的单元格或列元素。）
一些图表可能不会触发“select”事件，而一些图表可能仅支持选择整个行或选择整列。每个图表的文档均定义了其支持的事件和方法。
多选在不同的图表中的处理方式有所不同（有些图表甚至不允许这样做）。
为了读取所选数据，您需要在处理程序中调用 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 活动

大多数图表都是异步呈现的；在您针对图表调用 draw() 后，所有 Google 图表都会抛出 ready 事件，表示图表已呈现，并且已准备好返回属性或处理进一步的方法调用。在调用 draw() 后，您应始终先监听 ready 事件，然后再尝试对其调用方法。

一般来说，公开“ready”事件的图表符合以下规范：

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

按照惯例，未触发“ready”事件的图表会在 draw 方法结束后立即进行互动，并将控制权交还给用户。如果您的图表确实触发了 ready 事件，则应先等待该事件抛出，然后再对其调用方法，如下所示：

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Ready Event Handler 语法

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());
});

点击下方的表格行或图表元素，查看所选内容的实际效果：