Google Charts -- 對圖表建立事件

本文介紹如何監聽圖表的處理事件。

内容

概述

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

   不應該觸發一個“選擇”動作。

下面的例子是當選中一個表格的元素，彈出提示框：

<iframe class="framebox inherit-locale " src="https://developers.google.com/chart/interactive/docs/events_2d3ea45d3700fd6e4290b02dcfa3a3ba.frame?hl=zh-cn" style="box-sizing: inherit; border-width: 0px; border-style: initial; width: 856px; height: 250px;"></iframe>

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

點選下面的圖表或者圖表元素檢視選擇的動作：