處理事件

本頁說明如何監聽及處理圖表觸發的事件。

目錄

總覽

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() 方法，並傳回描述所選資料元素的物件陣列。這些物件的屬性具有 row 和 column 屬性。row 和 column 是 DataTable 中所選項目的列和欄索引。(選取事件會說明圖表中的基礎資料，而非圖表中的 HTML 元素)。如要取得所選項目的資料，您必須呼叫 DataTable.getValue() 或 getFormattedValue()。
  如果您同時指定 row 和 column，所選元素為儲存格。 如果僅指定 row，則所選元素為資料列。 如果僅指定 column，則所選元素為欄。
• 圖表應 公開 setSelection(selection) 方法，藉此變更基礎資料表中的選取項目，並在圖表中選取對應的資料。與 getSelection() 陣列類似的陣列 selection 參數，其中每個元素都是具有 row 和 column 屬性的物件。row 屬性會定義 DataTable 中所選資料列的索引，column 屬性則定義 DataTable 中所選資料欄的索引。呼叫此方法時，圖表應以視覺化方式呈現新的選取項目。setSelection() 實作方式不應觸發「select」事件。
  如果您同時指定 row 和 column，所選元素為儲存格。 如果僅指定 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);
}

已準備好的事件

大多數圖表都是以非同步方式顯示；所有 Google 圖表都會在您呼叫 draw() 之後擲回就緒事件 (代表圖表已轉譯)，並準備好傳回屬性或處理後續方法呼叫。呼叫 draw() 後，請一律先監聽就緒事件，再嘗試對其呼叫方法。

一般而言，顯示「已就緒」事件的圖表設計如下：

• 就緒事件不會傳遞任何屬性至處理常式 (您的函式處理常式不應預期任何參數傳遞至處理常式)。
• 在圖表可供互動後，圖表應 觸發就緒事件。 如果圖表的繪製為非同步，請務必在實際呼叫互動方法時觸發事件，而不是只在 draw 方法結束時觸發。
• 請在呼叫 draw() 方法之前，先將事件監聽器新增至此事件，否則可能會在設定事件監聽器之前觸發事件，而您也不會擷取到該事件。
• 如果您在就緒的事件發生前呼叫互動方法，可能會發生這些方法無法正常運作的問題。

慣例是，未觸發「已就緒」事件的圖表可在 draw 方法結束後立即進行互動，並傳回控制權給使用者。如果圖表「確實」會觸發就緒事件，您應該先等待事件擲回，再對其呼叫方法，如下所示：

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

就緒事件處理常式語法

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

在表格列或圖表元素上按一下下方圖表，即可查看所選項目的實際運作情形：