Xử lý sự kiện

Trang này mô tả cách theo dõi và xử lý các sự kiện do biểu đồ kích hoạt.

Nội dung

Tổng quan

Biểu đồ của Google có thể kích hoạt sự kiện mà bạn có thể nghe. Hành động của người dùng có thể kích hoạt sự kiện, 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 để được 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 và tài liệu về biểu đồ đó phải mô tả thời điểm kích hoạt mỗi sự kiện, ý nghĩa của sự kiệ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ừ một biểu đồ và cách xử lý các sự kiện đó.

Có một sự kiện mà bất kỳ biểu đồ có thể chọn nào cũng 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 tách 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 hãy gọi google.visualization.events.addListener() hoặc addOneTimeListener() kèm theo tên của biểu đồ hiển thị sự kiện, tên chuỗi của sự kiện cần theo dõi và tên 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 tuỳ 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 đợi sự kiện đó được kích hoạt trước khi cố gắng gửi các phương thức hoặc nhận sự kiện từ biểu đồ. Các 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 hiển thị 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');
}

Lưu ý rằng thao tác này sẽ chỉ đăng ký theo dõi 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ư minh hoạ dưới đâ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 truyền thông tin vào hàm của trình 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 toàn cục. Nếu sự kiện đó hiển thị thông tin như thế nào và cách sự kiện đó hiển thị, bạn phải mô tả trong tài liệu về biểu đồ đó. Dưới đây là cách truy xuất cả hai loại thông tin này:

Thông tin sự kiện được chuyển đến trình xử lý của bạn

Nếu biểu đồ truyền dữ liệu dưới dạng tham số đến hàm xử lý, bạn sẽ truy xuất dữ liệu đó như minh hoạ 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 chuyển vào trình xử lý của bạn sẽ có một thuộc tính cần được ghi lại cho biểu đồ. Để xem 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 trên trang của biểu đồ Bảng.

Thông tin sự kiện được chuyển đến một đối tượng chung

Thay vào đó, một số sự kiện sẽ thay đổi thuộc tính của một đối tượng toàn cục 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ì. Bạn có thể xem thêm thông tin về 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 chọn

Như đã đề cập trước đó, mọi biểu đồ có thể chọn được sẽ kích hoạt một sự kiện "select" (chọn) 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 bắt buộc biểu đồ phải hoạt động theo cách này. Hãy xem tài liệu về 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ế theo quy cách sau:

• Sự kiện chọn không truyền bất kỳ thuộc tính hoặc đối tượng nào đến trình xử lý (trình xử lý hàm của bạn không nên chuyển bất kỳ tham số nào đến sự kiện đó).
• Biểu đồ sẽ hiển thị phương thức getSelection(). Phương thức này trả về một mảng 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ó 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 đồ, chứ không phải các phần tử HTML trong biểu đồ.) Để lấy dữ liệu của mục đã chọn, bạn phải gọi DataTable.getValue() hoặc getFormattedValue().
  Nếu cả row và column đều được chỉ định, thì phần tử được chọn sẽ là một ô. Nếu bạn chỉ chỉ định row, thì phần tử được chọn sẽ là một hàng. Nếu bạn chỉ chỉ định column, thì phần tử được chọn sẽ là một cột.
• Biểu đồ phải 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 một cách trực quan lựa chọn mới là gì. Việc triển khai setSelection() không nên kích hoạt sự kiện "chọn".
  Nếu cả row và column đều được chỉ định, thì phần tử được chọn sẽ là một ô. Nếu bạn chỉ chỉ định row, thì phần tử được chọn sẽ là một hàng. Nếu bạn chỉ chỉ định column, thì phần tử được chọn sẽ là một cột.

Một số điều cần lưu ý:

• Biểu đồ có thể bỏ qua một phần của lựa chọn. Ví dụ: một bảng chỉ có thể hiển thị những 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ề mỗi biểu đồ xác định các sự kiện và phương thức mà biểu đồ hỗ trợ.
• Chế độ nhiều lựa chọn được xử lý theo cách khác nhau trong các biểu đồ khác nhau (một số biểu đồ thậm chí còn không cho phép tính năng này).
• Để đọ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à đặt đối tượng DataTable ở chế độ toàn cục.

Ví dụ sau đây bật lên một hộp cảnh báo chứa các phần tử bảng đã chọn khi một phần tử của biểu đồ bảng được chọn:

Lưu ý rằng biểu đồ bảng chỉ kích hoạt các sự kiện chọn hàng; tuy nhiên, mã này mang tính chung và có thể dùng cho các sự kiện chọn hàng, cột và ô.

Sau đây là mã trình 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 sẵn sàng

Hầu hết biểu đồ được kết xuất không đồng bộ; tất cả biểu đồ của Google đều gửi một sự kiện sẵn sàng sau khi bạn gọi draw() trên các biểu đồ đó, cho biết rằng biểu đồ đã được kết xuất và sẵn sàng trả về 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 trên sự kiện đó sau khi gọi draw().

Nhìn chung, các biểu đồ hiển thị sự kiện "sẵn sàng" được thiết kế theo quy cách sau:

• Sự kiện sẵn sàng không truyền bất kỳ thuộc tính nào đến trình xử lý (trình xử lý hàm của bạn không nên kỳ vọng sẽ truyền bất kỳ tham số nào đến trình xử lý).
• Biểu đồ sẽ kích hoạt sự kiện sẵn sàng sau khi biểu đồ đã sẵn sàng để tương tác. Nếu việc vẽ biểu đồ không đồng bộ, điều quan trọng là sự kiện được kích hoạt khi các 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 nắm bắt được sự kiện đó.
• Nếu gọi các phương thức tương tác trước khi kích hoạt sự kiện sẵn sàng, thì các phương thức này sẽ có nguy cơ không hoạt động đúng cách.

Quy ước là các biểu đồ không kích hoạt sự kiện "sẵn sàng" sẽ sẵn sàng tương tác ngay sau khi phương thức draw kết thúc và trả lại quyền kiểm soát cho người dùng. Nếu biểu đồ thực hiện 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 hoạ dưới đây:

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

Cú pháp 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

Biểu đồ sẽ gửi một sự kiện lỗi khi gặp một số loại lỗi nào đó để cho phép bạn xử lý lỗi một cách linh hoạt. Trình xử lý sự kiện nhận được nội dung mô tả về lỗi, cũng như thuộc tính sự kiện tuỳ chỉnh cho từng biểu đồ. Bạn nên đăng ký sự kiện này ngay sau khi tạo thực thể cho biểu đồ để phát hiện mọi lỗi có thể xảy ra ở các bước sau đó.

Bạn có thể dùng các hàm trợ giúp goog.visualization.errors để giúp người dùng thấy mọi lỗi một cách dễ 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ã nhận dạng 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 hiển thị được biểu đồ đó.
• thông báo [Bắt buộc] – Một chuỗi thông báo ngắn mô tả lỗi.
• detailedMessage [Không bắt buộc] – Giải thích chi tiết về lỗi.
• options [Không bắt buộc] – Đố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ề cách xử lý sự kiện

Ví dụ sau minh hoạ cả getSelection() và setSelection(). Thao tác 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ộ hoá 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());
});

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