本頁面說明如何監聽及處理圖表啟動的事件。
目錄
簡介
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)
,以變更基礎資料表中的選取項目,並選取圖表中對應的資料。selection 參數是一個與getSelection()
陣列類似的陣列,其中每個元素都是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); }
就緒事件
大部分圖表都是以非同步方式呈現,在呼叫 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()); });