Obsługa zdarzeń

Na tej stronie dowiesz się, jak nasłuchiwać i obsługiwać zdarzenia wywoływane przez wykres.

Spis treści

1. Overview
2. Rejestracja na wydarzenie i jego obsługa
3. Pobieram informacje o wydarzeniach
4. Zdarzenie select
5. Zdarzenie ready
6. Zdarzenie error
7. Przykład obsługi zdarzeń

Omówienie

Wykresy Google mogą uruchamiać zdarzenia, których możesz słuchać. Zdarzenia mogą być wywoływane przez działania użytkowników, np. kliknięcie wykresu. Możesz zarejestrować metodę JavaScript, która będzie wywoływana po wywołaniu określonych zdarzeń, np. z danymi związanymi z tym zdarzeniem.

Każdy wykres definiuje własne zdarzenia, a dokumentacja tego wykresu powinna zawierać opis tego, kiedy jest wywoływane każde zdarzenie, co to oznacza i jak można odzyskać wszystkie powiązane ze zdarzeniem informacje. Na tej stronie dowiesz się, jak zarejestrować się w celu otrzymywania zdarzeń z wykresu oraz jak je obsługiwać.

Każdy wykres do wyboru ma uruchamiać jedno zdarzenie: zdarzenie wyboru. Jednak zachowanie i znaczenie tego zdarzenia są określane na podstawie każdego wykresu.

Pamiętaj, że zdarzenia na wykresie są niezależne od standardowych zdarzeń DOM.

Rejestrowanie zdarzenia i obsługa zdarzenia

Aby zarejestrować moduły obsługi zdarzeń, wywołaj google.visualization.events.addListener() lub addOneTimeListener(), podając nazwę wykresu ujawniającego zdarzenie, nazwę ciągu znaków zdarzenia, które ma być nasłuchiwane, oraz nazwę funkcji wywoływanej po wywołaniu tego zdarzenia. Funkcja powinna akceptować pojedynczy parametr będący wywołanym zdarzeniem. To zdarzenie może zawierać niestandardowe informacje o zdarzeniu zgodnie z opisem w dokumentacji wykresów.

Ważne: jeśli wykres ujawnia gotowe zdarzenie, zawsze poczekaj na jego wywołanie, zanim spróbujesz wysłać metody lub odebrać zdarzenia z wykresu. Te wykresy mogą działać, zanim wywołają gotowe zdarzenie, ale nie jest to gwarantowane.

Ten fragment kodu wyświetla pole alertu za każdym razem, gdy użytkownik kliknie wiersz tabeli:

// 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');
}

Pamiętaj, że spowoduje to tylko zarejestrowanie nasłuchiwania zdarzeń dotyczących tego konkretnego obiektu tabeli. Rejestrować się można jedynie w celu odbierania zdarzeń z konkretnego obiektu.

Możesz też przekazać definicję funkcji w następujący sposób:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Pobieranie informacji o wydarzeniach

Zdarzenia ujawniają informacje na 2 sposoby: przekazując je do funkcji obsługi jako parametr lub dodając informacje do obiektu globalnego. To, czy i w jaki sposób zdarzenie ujawnia informacje, powinno być opisane w dokumentacji tego wykresu. Aby to zrobić:

Informacje o zdarzeniach przekazywane do modułu obsługi

Jeśli wykres przekazuje dane jako parametr do funkcji obsługi, można je pobrać w następujący sposób:

// 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']);
}

Parametr przekazywany do modułu obsługi będzie miał właściwość, która powinna zostać udokumentowana na potrzeby wykresu. Przykład wykresu, który w ten sposób udostępnia informacje o zdarzeniach, znajdziesz w zdarzeniu na stronie wykresu Tabela.

Informacje o zdarzeniach przekazywane do obiektu globalnego

Niektóre zdarzenia zamiast tego zmieniają właściwość obiektu globalnego, o którą można potem poprosić. Typowym przykładem jest zdarzenie „select”, które jest wywoływane, gdy użytkownik wybierze fragment wykresu. W tym przypadku kod musi wywołać na wykresie metodę getSelection(), aby dowiedzieć się, jaki jest obecny wybór. Więcej informacji znajdziesz poniżej.

// 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.');
  

Zdarzenie select

Jak już wspomnieliśmy, każdy wykres, który można wybrać, powinien uruchamiać zdarzenie „select”, które działa w standardowy sposób, umożliwiając pobieranie wartości wybranego elementu na wykresie. Nie ma jednak absolutnie wymagań, aby wykres działał w ten sposób. Sprawdź dokumentację wykresu.

Ogólnie wykresy, które udostępniają zdarzenie „select”, są zaprojektowane zgodnie z tymi specyfikacjami:

• Zdarzenie wyboru nie przekazuje do modułu obsługi żadnych właściwości ani obiektów (moduł obsługi funkcji nie powinien oczekiwać przekazywania do niego żadnych parametrów).
• Wykres powinien przedstawiać metodę getSelection(), która zwraca tablicę obiektów opisujących wybrane elementy danych. Te obiekty mają właściwości row i column. row i column to indeksy wierszy i kolumn wybranego elementu w DataTable. (Zdarzenia wyboru opisują dane na wykresie, a nie elementy HTML na wykresie). Aby pobrać dane wybranego elementu, musisz wywołać metodę DataTable.getValue() lub getFormattedValue().
  Jeśli określono zarówno row, jak i column, wybrany element jest komórką. Jeśli określono tylko row, wybrany element jest wierszem. Jeśli określono tylko column, wybrany element jest kolumną.
• Wykres powinien przedstawiać metodę setSelection(selection) służącą do zmiany wyboru w tabeli bazowej i wyboru odpowiednich danych na wykresie. Parametr selection to tablica podobna do tablicy getSelection(), w której każdy element jest obiektem o właściwościach row i column. Właściwość row określa indeks wybranego wiersza w tabeli DataTable, a usługa column określa indeks wybranej kolumny w elemencie DataTable. Gdy ta metoda jest wywoływana, wykres powinien wizualnie pokazywać nowy wybór. Implementacja funkcji setSelection() nie powinna wywoływać zdarzenia „select”.
  Jeśli określono zarówno row, jak i column, wybrany element jest komórką. Jeśli określono tylko row, wybrany element jest wierszem. Jeśli określono tylko column, wybrany element jest kolumną.

Uwagi:

• Wykres może zignorować część zaznaczenia. Na przykład tabela, która może wyświetlać tylko wybrane wiersze, może ignorować elementy komórek lub kolumn w implementacji setSelection.
• Niektóre wykresy mogą nie aktywować zdarzenia „select”, a inne mogą obsługiwać tylko zaznaczenie całego wiersza lub całej kolumny. Dokumentacja każdego wykresu określa obsługiwane przez niego zdarzenia i metody.
• Wybór wielokrotny jest obsługiwany inaczej na różnych wykresach (niektóre na to nawet nie zezwalają).
• Aby odczytać wybrane dane, musisz wywołać funkcję DataTable.getValue() w module obsługi. Najprostszym sposobem na włączenie tej funkcji jest ustawienie obiektu DataTable jako globalnego.

Poniższy przykład wyświetla okno alertu z wybranymi elementami tabeli po wybraniu elementu wykresu tabelarycznego:

Pamiętaj, że wykres tabelaryczny uruchamia tylko zdarzenia wyboru wiersza, jednak kod jest ogólny i może być używany w przypadku zdarzeń wyboru wiersza, kolumny i komórki.

Oto kod modułu obsługi tego przykładu:

// 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);
}

Zdarzenie ready

Większość wykresów jest renderowana asynchronicznie. Wszystkie wykresy Google zgłaszają gotowe zdarzenie po wywołaniu na nich funkcji draw(), co oznacza, że wykres został wyrenderowany i jest gotowy do zwracania właściwości lub obsługi kolejnych wywołań metod. Zawsze przed próbą wywołania metod dla tego zdarzenia po wywołaniu funkcji draw() należy zawsze nasłuchiwać zdarzenia gotowości.

Ogólnie wykresy, które udostępniają zdarzenie „ready”, mają zwykle takie parametry:

• Gotowe zdarzenie nie przekazuje żadnych właściwości do modułu obsługi (moduł obsługi funkcji nie powinien oczekiwać, że zostaną do niego przekazane żadne parametry).
• Wykres powinien uruchomić zdarzenie gotowości, gdy wykres jest gotowy do interakcji. Jeśli wykres jest asynchroniczny, ważne jest, aby zdarzenie było wywoływane wtedy, gdy możliwe było wywołanie metod interakcji, a nie tylko po zakończeniu metody draw.
• Dodanie odbiornika do tego zdarzenia powinno się zakończyć przed wywołaniem metody draw(), ponieważ w przeciwnym razie zdarzenie może być wywoływane, zanim odbiornik zostanie skonfigurowany, i nie uda Ci się go przechwycić.
• Wywołując metody interakcji przed wywołaniem zdarzenia „Gotowe”, ryzykujesz, że nie będą one działać prawidłowo.

Zgodnie z konwencją wykresy, które nie wywołują zdarzenia „ready”, są gotowe do interakcji natychmiast po zakończeniu metody draw i zwracają użytkownikowi kontrolę. Jeśli wykres wywołuje zdarzenie gotowe, poczekaj, aż zostanie ono wysłane, zanim wywołasz do niego metody, jak pokazano tutaj:

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

Składnia gotowego modułu obsługi zdarzeń

function myReadyHandler(){...}

Gotowy moduł obsługi zdarzeń nie przekazuje żadnych parametrów.

Zdarzenie błąd

Gdy na wykresach wystąpią jakieś błędy, powinny wywoływać zdarzenie błędu, aby umożliwić Ci właściwe reagowanie na nie. Do modułu obsługi zdarzeń przekazywany jest opis błędu, a także właściwości zdarzeń niestandardowych charakterystyczne dla każdego wykresu. Zasubskrybuj to zdarzenie zaraz po utworzeniu wystąpienia wykresu, aby przechwytywać wszystkie błędy, które mogą wystąpić w późniejszych krokach.

Funkcje pomocnicze goog.visualization.errors umożliwiają płynne wyświetlanie użytkownikowi błędów.

Składnia modułu obsługi zdarzeń błędu

function myErrorHandler(err){...}

Moduł obsługi zdarzeń błędu powinien być przekazywany do obiektu z tymi elementami:

• id [wymagany] – identyfikator elementu DOM zawierającego wykres lub komunikat o błędzie wyświetlany zamiast wykresu, jeśli nie można go wyrenderować.
• message [wymagany] – krótki ciąg tekstowy opisujący błąd.
• detailedMessage [opcjonalny] – szczegółowe objaśnienie błędu.
• options [opcjonalny] – obiekt zawierający parametry niestandardowe odpowiednie dla tego błędu i typu wykresu.

Przykład obsługi zdarzeń

Poniższy przykład ilustruje działanie metody getSelection() i setSelection(). Synchronizuje on wybór między 2 wykresami, które używają tej samej tabeli danych. Kliknij wykres, aby zsynchronizować zaznaczenie na drugim wykresie.

// 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());
});

Kliknij wykresy poniżej w wierszach tabeli lub na elementach wykresu, aby zobaczyć, jak działa zaznaczenie: