Trang này được dịch bởi Cloud Translation API.

Xử lý sự kiện

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
Đăng ký và xử lý sự kiện
Truy xuất thông tin sự kiện
Sự kiện select
Sự kiện sẵn sàng
Sự kiện lỗi
Ví dụ về cách xử lý sự kiện

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ính row và column. row và column là các chỉ mục hàng và cột của mục đã chọn trong DataTable. (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ọi DataTable.getValue() hoặc getFormattedValue().
Nếu bạn chỉ định cả row và column, thì phần tử đã chọn là một ô. Nếu chỉ chỉ định row, 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ảng getSelection(), trong đó mỗi phần tử là một đối tượng có các thuộc tính row và column. Thuộc tính row xác định chỉ mục của hàng đã chọn trong DataTable, còn thuộc tính column xác định chỉ mục của cột đã chọn trong DataTable. 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 khai setSelection() 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ỉ định row, 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ượng DataTable 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());
});

Nhấp vào các biểu đồ bên dưới trên hàng trong bảng hoặc trên các thành phần của biểu đồ để xem lựa chọn trong thực tế: