啟動事件

您的視覺呈現可以觸發代管頁面可註冊接收的事件。事件可以透過使用者動作觸發。舉例來說，使用者點選圖表時也可以設為內部觸發事件，例如每 10 秒觸發一個事件。您可以註冊要在每次觸發特定事件時呼叫的 JavaScript 方法，方法可能是使用該事件的專屬資料。

每個視覺呈現都會定義自己的事件，而該視覺化呈現的說明文件也應說明每個事件的觸發時間、相關意義，以及事件處理常式會傳送哪些資訊 (例如「圖表視覺化」)。本頁將說明視覺化內容建立者如何觸發事件。如要瞭解用戶端如何註冊以接收事件，請參閱「處理事件」頁面。

任何可選取的圖表都應觸發一個事件：選取事件。不過，這個事件的行為和意義是由各種視覺呈現定義。

在 draw 方法傳回控制項給使用者後，如果視覺呈現無法立即與使用者互動，表示該視覺化作業應觸發：就緒事件。如要瞭解此事件的確切行為和意義，請參閱「準備事件」一節。

請注意，Visualization API 事件與標準 DOM 事件各自獨立，也不同。

目錄

  1. 觸發事件
  2. 選擇事件
  3. 「準備事件」
  4. 更多資訊

觸發事件

如要從圖表觸發事件，請呼叫 google.visualization.events.trigger() 函式。這個函式預期的參數如下：

  1. 來源視覺呈現 (通常是 this 值)。
  2. 事件名稱 (字串)。
  3. 事件詳細資料 (物件)。可選用事件詳細資料的對應 (名稱/值)。

以下範例顯示圖表如何擲回選取事件：

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

代管頁面可以呼叫 google.visualization.events.addListener() 或 google.visualization.events.addOneTimeListener() 來註冊以接收事件。請務必完整記錄您觸發的所有事件。

選取事件

「選取」事件是許多圖表針對使用者點擊滑鼠點擊而擲回的標準事件。如果您選擇根據滑鼠點擊觸發事件，則應按照此處所述的標準方式導入「選取」事件：

  1. 當使用者在圖表中選取了某些資料時，會觸發名為「select」的事件。此事件不會傳送任何引數至監聽函式。
  2. 按照連結文件一節中的說明公開 getSelection() 方法。這個方法應會傳回使用者所選 data 元素的索引。
  3. 按照參考資料一節的說明公開 setSelection() 方法。您也可以參閱「處理事件」頁面，瞭解如何處理事件。

「就緒」事件

任何圖表都應觸發「就緒」的事件，運作方式符合標準，讓開發人員知道視覺化內容已準備好處理稱為「方法」的方法。(不過，視覺化資料並沒有絕對「要求」，請查閱說明文件以取得視覺化結果)。

一般來說，顯示「已就緒」事件的圖表設計時會採用以下規格：

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

慣例是，如果圖表未觸發「已就緒」事件，就可在 draw 方法結束後立即進行互動，並傳回控制項給使用者。

更多資訊