Google Charts -- 对图表创建事件

任昊阳

2023-12-01

本文介绍如何监听图表的处理事件。

内容

概述

Google charts 可以创建你需要监听的事件。事件可以由用户的动作触发，例如当用户点击一个图表时。你可以注册一个Javascript方法当某些动作被触发时来调用，可以有数据来强调事件。

每个图表都定义了自己的事件，对图表的声明需要描述要调用的时间，也就是说，如何得到与时间关联的信息。这篇文章描述如何从图表注册获取事件，以及如何处理事件。

有一个事件是任何可选择的图表都要调用的：选择事件。但是，这个事件的行为和意义由每个图表定义。

很重要的一点是，图表的事件是和标准DOM事件独立的。

注册和处理一个事件

注册你的事件处理器，你需要调用google.visualization.events.addListener() 或者 addOneTimeListener() 带有图表名，要监听的事件的字符串名，以及当事件要引用时调用的函数的名字。你的函数需要传递一个单一变量：event变量。这个event变量可以有在图表声明中描述的关于事件的传统信息。

重要：如果你的图表有一个 ready event, 你应该一直等待那个事件被调用，直到你要从那个图表传递方法或者接收动作。这些图表应该在它们抛出一个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']);
}

传递给全局变量的事件信息

有的事件只是改变全局变量的一个属性，这个你可以获取。一个简单的例子就是“选择”事件，当用户选择图表的某一部分时被调用。这种情况下，代码里需要调用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.');

选择事件

总的来说，图表的“选择”动作有如下的要求：

选择动作不会传递任何属性或者对象给处理器（你的处理函数不应该得到任何传递给它的变量）。
图表应该应用方法 getSelection(), 返回一组对象，难怪三个月选择的数据元素。这些对象有属性 row 和column. row 和 column 是DataTable里被选择的行和列元素。(选择时间描述了图表里的潜在数据，而不是图表的HTML元素。) 为了得到选择的项的数据，你需要调用DataTable.getValue() 或者getFormattedValue().
如果 row 和 column 都被声明, 选择的元素是一个单元。如果只有row 被声明，选中的对象是一行。如果只有t column 被声明，选中的对象是一列。
图表应该调用方法setSelection(selection) 来改变隐藏图表的选择和图表相应数据的选择。选中的元素是一个类似getSelection() 数组的数组，每一个元素都是一个有 row 和 column属性的对象。 row 属性定义了 DataTable 中的指定行， column 属性定义 DataTable中指定列。当方法被调用时，图表应该指出是哪个新的选择。 setSelection() 不应该触发一个“选择”动作。

下面的例子是当选中一个表格的元素，弹出提示框：

Note that the table chart only fires row selection events; however, the code is generic, and can be used for row, column, and cell selection events.

这里是处理函数的例子：


// 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()之后调用方法之前一直监听就绪事件。

总的来说，就绪事件要有如下特性：

就绪事件不传递任何属性给处理器（你的函数处理器不应该得到任何传递给它的参数）。
图表应该在图表做好交互准备后绑定就绪事件。如果画图表是异步的，很重要的一点是，在交互方法真正被调用时绑定事件，而不只是在draw方法结束时。
增加事件的监听应该在调用draw（）方法之前完成，因为如果不这样的话事件可能在监听之前建立这样你无法捕捉。

如果你的图表绑定了一个就绪事件，你应该在调用方法之前等待：


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

就绪事件语法

function myReadyHandler(){...}

就绪事件不传递任何参数。

错误事件

图表应该在遇到错误时抛出错误事件。事件处理器会传递错误的定义，以及每个图表的传统事件属性。

你可以使用 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());
});

点击下面的图表或者图表元素查看选择的动作：