處理事件

本頁面說明如何監聽及處理圖表啟動的事件。

目錄

簡介

Google 圖表可以觸發您能監聽的事件。事件可由使用者動作觸發,例如使用者點擊圖表。您可以登錄 JavaScript 方法,讓系統在每次發生特定事件時呼叫該方法 (可能搭配該事件專屬的資料)。

每個圖表都會定義自己的事件,且該圖表的說明文件應該說明每個事件的觸發時機、意義,以及如何取得與事件相關的任何資訊。本頁面說明如何註冊接收圖表中的事件,以及如何處理這些事件。

任何可選取圖表都應觸發一個事件:選取事件。不過,此事件的行為和意義均由一張圖表定義。

請注意,圖表事件與標準 DOM 事件是獨立且不同的。

註冊及處理事件

如要註冊事件處理常式,您必須呼叫 google.visualization.events.addListener()addOneTimeListener(),以公開事件的圖表名稱、要監聽的事件字串名稱,以及該事件啟動時要呼叫的函式名稱。您的函式應接受已觸發的事件的單一參數。此事件可以包含事件的自訂資訊,如圖表說明文件中所述。

重要事項:如果圖表顯示已就緒的事件,請一律等到該事件觸發後,再嘗試透過圖表傳送方法或接收事件。這些圖表或許可以在擲回就緒前執行,但並不保證這種行為。

以下程式碼片段會在使用者點選表格列時顯示快訊方塊:

// 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.');
  

select 事件

如前文所述,任何能夠選取的圖表應該都會以標準方式啟動「選取」事件,讓您擷取圖表中所選項目的值。(不過圖表並沒有絕對的規定,請參閱說明文件,請查看圖表)。

一般來說,公開「選取」事件的圖表設計如下:

  • 選取事件不會傳送任何屬性或物件給處理常式 (您的函式處理常式不應收到任何參數)。
  • 圖表顯示 getSelection() 方法,該方法會傳回描述所選資料元素的物件陣列。這些物件具有 rowcolumn 屬性。rowcolumnDataTable 中選定項目的列與欄索引。(選取事件會描述圖表的基礎資料,而非圖表中的 HTML 元素)。如要取得所選取項目的資料,您必須呼叫 DataTable.getValue()getFormattedValue()
    如果同時指定 rowcolumn,則所選元素為儲存格。如果僅指定 row,則所選元素為一列。如果僅指定 column,則所選元素為資料欄。
  • 圖表顯示方法 setSelection(selection),以變更基礎資料表中的選取項目,並選取圖表中對應的資料。selection 參數是一個與 getSelection() 陣列類似的陣列,其中每個元素都是 rowcolumn 屬性的物件。 row 屬性會定義 DataTable 中所選資料列的索引,column 屬性會定義 DataTable 中所選資料欄的索引。呼叫此方法時,圖表應以視覺化方式呈現新選取項目為何。setSelection() 的實作不應觸發「select」(選取) 事件。
    如果同時指定 rowcolumn,則所選元素為儲存格。如果僅指定 row,則所選元素為一列。如果僅指定 column,則所選元素為資料欄。

注意事項:

  • 圖表可能會忽略部分選取項目。例如,只顯示所選列的資料表在 setSelection 實作中,可能會忽略儲存格或欄元素)。
  • 部分圖表可能不會觸發「選取」事件,部分圖表可能僅支援整個資料列選取或整個資料欄選取作業。每張圖表的說明文件皆定義了支援的事件和方法。
  • 可在多個圖表中以不同方式處理多個選擇 (有些甚至不允許)。
  • 如要讀取所選資料,您必須在處理常式中呼叫 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);
}

就緒事件

大部分圖表都是以非同步方式呈現,在呼叫 draw() 之後,所有 Google 圖表都會傳回就緒事件,表示系統算繪圖表,且已可傳回屬性或處理進一步方法呼叫。呼叫 draw() 之後,您應該先監聽就緒事件,然後再嘗試對其呼叫方法。

一般來說,公開「就緒」事件的圖表設計如下:

  • 就緒事件不會將任何屬性傳遞給處理常式 (您的函式處理常式不應傳送任何參數給處理常式)。
  • 圖表「必須」在圖表準備好互動後觸發。如果圖表是非同步的,那麼只有在實際呼叫互動方法時才會觸發事件,而不是只有 draw 方法結束。
  • 請先呼叫事件監聽器,再呼叫 draw() 方法。
  • 如果在就緒事件觸發之前呼叫互動方法,則這些方法可能無法正常運作。

慣例是,在 draw 方法結束之後,未觸發「就緒」事件的圖表可以立即互動並傳回控制項給使用者。如果您的圖表「是否」觸發了就緒的事件,您應該先等待系統擲回該事件,再呼叫該方法上的方法,如下所示:

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

Ready 事件處理常式語法

function myReadyHandler(){...}

就緒事件處理常式未傳遞任何參數。

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

請點選表格列或圖表元素的圖表,查看實際操作選項: