Trang này mô tả cách nghe và xử lý các sự kiện do một biểu đồ kích hoạt.
Nội dung
Tổng quan
Biểu đồ của Google có thể kích hoạt các sự kiện mà bạn có thể nghe. Các hành động của người dùng có thể được kích hoạt bởi các hành động của người dùng, chẳng hạn như khi người dùng nhấp vào một biểu đồ. Bạn có thể đăng ký một phương thức JavaScript để gọi bất cứ khi nào một số sự kiện nhất định được kích hoạt, có thể bằng dữ liệu dành riêng cho sự kiện đó.
Mỗi biểu đồ xác định các sự kiện riêng của nó và tài liệu cho biểu đồ đó phải mô tả thời điểm kích hoạt mỗi sự kiện, ý nghĩa của nó và cách lấy lại bất kỳ thông tin nào liên quan đến sự kiện đó. Trang này mô tả cách đăng ký nhận các sự kiện từ biểu đồ và cách xử lý các sự kiện đó.
Có một sự kiện mà biểu đồ có thể chọn sẽ kích hoạt: sự kiện chọn. Tuy nhiên, hành vi và ý nghĩa của sự kiện này được xác định theo từng biểu đồ.
Điều quan trọng cần lưu ý là các sự kiện trong biểu đồ phải riêng biệt và khác biệt với các sự kiện DOM chuẩn.
Đăng ký và xử lý sự kiện
Để đăng ký trình xử lý sự kiện, bạn
gọi google.visualization.events.addListener()
hoặc addOneTimeListener()
kèm theo tên của biểu đồ cho biết sự kiện, tên chuỗi của
sự kiện để nghe và tên của hàm cần gọi khi
sự kiện đó được kích hoạt. Hàm của bạn phải chấp nhận một thông số
duy nhất là sự kiện đã được kích hoạt. Sự kiện này có thể có thông tin
tùy chỉnh về sự kiện, như mô tả trong tài liệu về
biểu đồ.
Lưu ý quan trọng: Nếu biểu đồ của bạn cho thấy một sự kiện sẵn sàng, bạn phải luôn kích hoạt sự kiện đó trước khi cố gắng gửi các phương thức hoặc nhận các sự kiện từ biểu đồ. Những biểu đồ này có thể hoạt động trước khi gửi một sự kiện sẵn sàng, nhưng hành vi đó không được đảm bảo.
Đoạn mã sau đây cho thấy một hộp cảnh báo mỗi khi người dùng nhấp vào một hàng trong bảng:
// 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'); }
Xin lưu ý rằng thao tác này sẽ chỉ đăng ký nghe các sự kiện cho đối tượng bảng cụ thể này; bạn chỉ có thể đăng ký nhận các sự kiện từ một đối tượng cụ thể.
Bạn cũng có thể truyền vào một định nghĩa hàm, như được hiển thị ở đây:
// Pass in a function definition. google.visualization.events.addListener(orgchart, 'select', function() { table.setSelection(orgchart.getSelection()); });
Truy xuất thông tin sự kiện
Các sự kiện thường hiển thị thông tin theo hai cách: bằng cách chuyển thông tin vào hàm xử lý dưới dạng tham số; hoặc bằng cách thêm thông tin vào một đối tượng chung. Nếu và cách thức sự kiện cung cấp thông tin phải được mô tả trong tài liệu cho biểu đồ đó. Sau đây là cách truy xuất cả hai loại thông tin:
Thông tin sự kiện được chuyển đến trình xử lý của bạn
Nếu biểu đồ chuyển dữ liệu dưới dạng tham số vào hàm xử lý, bạn sẽ truy xuất dữ liệu đó như minh họa dưới đây:
// 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']); }
Tham số được truyền đến trình xử lý của bạn sẽ có một thuộc tính cần phải được ghi lại cho biểu đồ đó. Để biết ví dụ về biểu đồ hiển thị thông tin sự kiện theo cách này, hãy xem sự kiện trang của biểu đồ Bảng.
Thông tin sự kiện được chuyển đến một đối tượng toàn cầu
Thay vào đó, một số sự kiện thay đổi thuộc tính của một đối tượng toàn cầu mà sau đó bạn có thể yêu cầu. Một ví dụ phổ biến là sự kiện "select" (chọn), được kích hoạt khi người dùng chọn một phần của biểu đồ. Trong trường hợp này, mã phải gọi getSelection() trên biểu đồ để tìm hiểu lựa chọn hiện tại là gì. Thông tin thêm sẽ được cung cấp trong sự kiện chọn bên dưới.
// 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.');
Sự kiện select
Như đã đề cập trước đó, mọi biểu đồ có thể được chọn sẽ kích hoạt sự kiện "select" (hoạt động theo cách chuẩn) để cho phép bạn truy xuất các giá trị của mục đã chọn trong biểu đồ. (Tuy nhiên, không có yêu cầu tuyệt đối nào về việc một biểu đồ hoạt động theo cách này. Hãy xem tài liệu cho biểu đồ của bạn).
Nhìn chung, các biểu đồ hiển thị sự kiện "chọn" được thiết kế với các thông số kỹ thuật sau:
- Sự kiện chọn không chuyển bất kỳ thuộc tính hoặc đối tượng nào cho trình xử lý (trình xử lý hàm của bạn không được mong đợi bất kỳ thông số nào được chuyển tới trình xử lý đó).
- Biểu đồ sẽ hiển thị phương thức
getSelection()
. Phương thức này trả về một loạt các đối tượng mô tả các phần tử dữ liệu đã chọn. Các đối tượng này có các thuộc tínhrow
vàcolumn
.row
vàcolumn
là các chỉ mục hàng và cột của mục đã chọn trongDataTable
. (Sự kiện lựa chọn mô tả dữ liệu cơ bản trong biểu đồ, không phải phần tử HTML trong biểu đồ.) Để nhận dữ liệu của mục đã chọn, bạn sẽ phải gọiDataTable.getValue()
hoặcgetFormattedValue()
.
Nếu bạn chỉ định cảrow
vàcolumn
, thì phần tử đã chọn là một ô. Nếu chỉ chỉ địnhrow
, phần tử đã chọn sẽ là một hàng. Nếu chỉ cócolumn
được chỉ định, thì phần tử được chọn sẽ là một cột. - Biểu đồ sẽ hiển thị phương thức
setSelection(selection)
để thay đổi lựa chọn trong bảng cơ bản và chọn dữ liệu tương ứng trong biểu đồ. Tham số selection là một mảng tương tự như mảnggetSelection()
, trong đó mỗi phần tử là một đối tượng có các thuộc tínhrow
vàcolumn
. Thuộc tínhrow
xác định chỉ mục của hàng đã chọn trongDataTable
, còn thuộc tínhcolumn
xác định chỉ mục của cột đã chọn trongDataTable
. Khi phương thức này được gọi, biểu đồ sẽ cho biết trực tiếp lựa chọn mới. Việc triển khaisetSelection()
không được kích hoạt sự kiện "chọn".
Nếu bạn chỉ định cảrow
vàcolumn
, thì phần tử đã chọn là một ô. Nếu chỉ chỉ địnhrow
, phần tử đã chọn sẽ là một hàng. Nếu chỉ cócolumn
được chỉ định, thì phần tử được chọn sẽ là một cột.
Một số lưu ý:
- Biểu đồ có thể bỏ qua một phần lựa chọn. Ví dụ: một bảng chỉ có thể hiển thị các hàng đã chọn có thể bỏ qua các phần tử ô hoặc cột trong quá trình triển khai
setSelection
.) - Một số biểu đồ có thể không kích hoạt sự kiện "chọn" và một số biểu đồ có thể chỉ hỗ trợ toàn bộ lựa chọn hàng hoặc toàn bộ lựa chọn cột. Tài liệu về từng biểu đồ xác định các sự kiện và phương thức mà biểu đồ hỗ trợ.
- Cách xử lý nhiều lựa chọn được xử lý theo nhiều cách trong các biểu đồ khác nhau (một số biểu đồ thậm chí còn không cho phép).
- Để đọc được dữ liệu đã chọn, bạn cần gọi
DataTable.getValue()
trong trình xử lý của mình. Cách đơn giản nhất để bật tính năng đó là đưa đối tượngDataTable
ra toàn cục.
Ví dụ sau đây bật lên một hộp thông báo có các phần tử bảng đã chọn, khi một phần tử của biểu đồ bảng được chọn:
Xin lưu ý rằng biểu đồ bảng chỉ kích hoạt các sự kiện lựa chọn hàng; tuy nhiên, mã này là mã chung và có thể dùng cho các sự kiện chọn hàng, cột và ô.
Dưới đây là mã xử lý cho ví dụ đó:
// 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); }
Sự kiện ready
Hầu hết các biểu đồ đều hiển thị không đồng bộ; tất cả biểu đồ của Google sẽ gửi một sự kiện sẵn sàng sau khi bạn gọi draw()
trên các biểu đồ này, cho biết rằng biểu đồ đã được hiển thị và sẵn sàng trả về các thuộc tính hoặc xử lý các lệnh gọi phương thức khác. Bạn phải luôn theo dõi sự kiện sẵn sàng trước khi cố gắng gọi các phương thức cho sự kiện đó sau khi gọi draw()
.
Nhìn chung, các biểu đồ hiển thị sự kiện "ready" được thiết kế với các thông số kỹ thuật sau:
- Sự kiện sẵn sàng không chuyển bất kỳ thuộc tính nào cho trình xử lý (trình xử lý hàm của bạn không được mong đợi bất kỳ thông số nào được chuyển vào đó).
- Biểu đồ sẽ kích hoạt sự kiện sẵn sàng sau khi biểu đồ sẵn sàng cho tương tác.
Nếu bản vẽ biểu đồ không đồng bộ, quan trọng là sự kiện đó được kích hoạt khi phương thức tương tác thực sự có thể được gọi, chứ không chỉ khi phương thức
draw
kết thúc. - Bạn nên thêm trình nghe vào sự kiện này trước khi gọi phương thức
draw()
, vì nếu không sự kiện có thể được kích hoạt trước khi trình nghe được thiết lập và bạn sẽ không phát hiện được sự kiện đó. - Khi gọi các phương thức tương tác trước khi sự kiện sẵn sàng được kích hoạt, bạn có nguy cơ gặp phải các phương thức không hoạt động đúng cách.
Theo quy ước, các biểu đồ không kích hoạt sự kiện "ready" sẽ sẵn sàng tương tác ngay sau khi phương thức draw
kết thúc và trả về quyền kiểm soát cho người dùng. Nếu biểu đồ kích hoạt một sự kiện sẵn sàng, bạn nên đợi sự kiện đó được gửi trước khi gọi các phương thức trên sự kiện đó, như minh họa dưới đây:
google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);
Cú pháp của trình xử lý sự kiện sẵn sàng
function myReadyHandler(){...}
Trình xử lý sự kiện sẵn sàng không được chuyển bất kỳ thông số nào.
Sự kiện lỗi
Các biểu đồ sẽ gửi một sự kiện lỗi khi gặp sự cố nào đó, để bạn có thể xử lý linh hoạt sự kiện đó. Trình xử lý sự kiện được chuyển nội dung mô tả về lỗi, cũng như các thuộc tính sự kiện tuỳ chỉnh dành riêng cho từng biểu đồ. Bạn nên đăng ký sự kiện này ngay sau khi tạo bản sao cho biểu đồ để giữ lại mọi lỗi có thể xảy ra trong các bước sau.
Bạn có thể sử dụng các chức năng trợ giúp của goog.visualization.errors
để dễ dàng hiển thị lỗi cho người dùng.
Cú pháp trình xử lý sự kiện lỗi
function myErrorHandler(err){...}
Trình xử lý sự kiện lỗi phải được truyền một đối tượng có các thành phần sau:
- id [Bắt buộc] – Mã của phần tử DOM chứa biểu đồ, hoặc một thông báo lỗi xuất hiện thay vì biểu đồ nếu không thể hiển thị biểu đồ này.
- message [Bắt buộc] – Một chuỗi thông báo ngắn mô tả lỗi.
- DETAILSMessage [Không bắt buộc] – Thông tin giải thích chi tiết về lỗi.
- option [Không bắt buộc]– Một đối tượng chứa các thông số tuỳ chỉnh phù hợp với lỗi và loại biểu đồ này.
Ví dụ về xử lý sự kiện
Ví dụ sau minh hoạ cả getSelection() và setSelection(). Ví dụ này đồng bộ hoá lựa chọn giữa hai biểu đồ sử dụng cùng một bảng dữ liệu. Nhấp vào một trong hai biểu đồ để đồng bộ hóa lựa chọn trong biểu đồ khác.
// 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()); });