Obsługa zdarzeń

Na tej stronie opisujemy, jak nasłuchiwać zdarzeń uruchamianych przez wykres i nimi zarządzać.

Treści

Omówienie

Wykresy Google mogą uruchamiać zdarzenia, których możesz śledzić. Zdarzenia mogą być wywoływane przez działania użytkownika, np. kliknięcie wykresu. Możesz zarejestrować metodę JavaScript, która będzie wywoływana przy każdym wywołaniu pewnych zdarzeń, które mogą zawierać dane dotyczące tego zdarzenia.

Każdy wykres definiuje własne zdarzenia, a jego dokumentacja powinna zawierać informacje o tym, kiedy jest uruchamiane każde zdarzenie, co oznacza i jak zwracać wszystkie informacje powiązane ze zdarzeniem. Z tego artykułu dowiesz się, jak zarejestrować się, aby otrzymywać zdarzenia z wykresu, i jak się z nimi rozwiązywać.

Jest jedno zdarzenie, które powinno być uruchamiane przez dowolny wykres, który można wybrać: zdarzenie wyboru. Jednak każde zachowanie i znaczenie tego zdarzenia jest określane przez każdy wykres.

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

Rejestracja na wydarzenie i obsługa wydarzenia

Aby zarejestrować moduły obsługi zdarzeń, wywołujesz google.visualization.events.addListener() lub addOneTimeListener() z nazwą wykresu ujawnionego zdarzenia, nazwą ciągu znaków nasłuchiwanego i nazwą funkcji, która ma być wywoływana po wywołaniu zdarzenia. Funkcja powinna akceptować jeden parametr, który wywołał zdarzenie. To zdarzenie może zawierać niestandardowe informacje o zdarzeniu zgodnie z opisem w dokumentacji wykresu.

Ważne: jeśli wykres przedstawia gotowe zdarzenie, zawsze próbuj wysyłać metody lub odbierać zdarzenia z wykresu, zanim wywołasz to zdarzenie. Te wykresy mogą działać, zanim wszystko będzie gotowe, ale nie jest to gwarantowane.

Ten fragment kodu pokazuje 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 rejestrowanie tylko zdarzeń nasłuchujących tego konkretnego obiektu tabeli. Możesz zarejestrować się tylko do odbierania zdarzeń z określonego obiektu.

Możesz też podać 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 zdarzeniu

Zdarzenia udostępniają informacje na 2 sposoby: przesyłając je do funkcji obsługi jako parametr lub dodając informacje do obiektu globalnego. Jeśli zdarzenie i w jaki sposób ujawnią one dane, należy to zrobić w dokumentacji danego wykresu. Aby pobrać informacje obu typów:

Informacje o zdarzeniu przekazywane do Twojego modułu obsługi

Jeśli wykres przekazuje dane jako parametr do funkcji obsługi, pobierzesz go tak, jak pokazano tutaj:

// 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 przekazany do Twojego modułu obsługi będzie miał właściwość, która powinna być udokumentowana na wykresie. Przykładowy wykres, który w ten sposób pokazuje informacje o zdarzeniu, znajdziesz na wykresie na stronie Tabela.

Informacje o zdarzeniu przekazywane do obiektu globalnego

Niektóre zdarzenia zmieniają właściwość obiektu globalnego, którą możesz następnie zażądać. Typowym przykładem jest zdarzenie „select”, które jest uruchamiane, gdy użytkownik wybierze część wykresu. W tym przypadku kod musi wywołać metodę getSelection() na wykresie, aby dowiedzieć się, co to jest bieżący wybór. Więcej informacji o tym zdarzeniu 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 wspomnieliśmy wcześniej, każdy wykres, który można wybrać, powinien wywoływać zdarzenie „select”, które działa w standardowy sposób i pobiera wartości zaznaczonego elementu. (Nie ma jednak absolutnie żadnego wymogu takiego działania wykresu – zapoznaj się z jego dokumentacją).

Ogólnie wykresy, które ujawniają zdarzenie „select”, są zgodne z tymi specyfikacjami:

• Wybrane zdarzenie nie przekazuje do usługi żadnych właściwości ani obiektów (Twój moduł obsługi funkcji nie powinien oczekiwać, że do niego zostaną przekazane parametry).
• Wykres powinny ujawnić 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 wskazują podstawowe 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 wartość row, jak i column, wybrany element to komórka. Jeśli określono tylko element row, wybrany element to wiersz. Jeśli określono tylko element column, wybrany element to kolumna.
• Wykres powinny udostępniać metodę setSelection(selection), by zmienić wybór w tabeli bazowej i wybrać odpowiednie dane na wykresie. Parametr select jest tablicą podobną do tablicy getSelection(), gdzie każdy element jest obiektem o właściwościach row i column. Właściwość row określa indeks wybranego wiersza w elemencie DataTable, a właściwości column określa indeks wybranej kolumny w elemencie DataTable. Po wywołaniu tej metody wykres powinien wizualnie reprezentować nowy wybór. Implementacja setSelection() nie powinna wywoływać zdarzenia „select”.
  Jeśli określono zarówno wartość row, jak i column, wybrany element to komórka. Jeśli określono tylko element row, wybrany element to wiersz. Jeśli określono tylko element column, wybrany element to kolumna.

Zastrzeżenia:

• Wykres może ignorować część zaznaczenia. Na przykład tabela, w której mogą się wyświetlać tylko wybrane wiersze, może ignorować elementy komórek lub kolumn w ich implementacji setSelection).
• Niektóre wykresy mogą nie wywoływać zdarzenia „select”, a niektóre – tylko cały wiersz lub całą kolumnę. Dokumentacja każdego wykresu określa obsługiwane zdarzenia i metody.
• Wybieranie jednokrotnego wyboru na różnych wykresach wygląda inaczej (niektóre na to nie pozwalają).
• Aby odczytać wybrane dane, musisz wywołać metodę DataTable.getValue() w module obsługi klienta. Najprostszym sposobem, aby to zrobić, jest ustawienie obiektu DataTable na poziomie globalnym.

Ten przykład pokazuje wyskakujące okienko alertu z wybranymi elementami tabeli, gdy wybrany jest element wykresu:

Pamiętaj, że wykres tabeli uruchamia tylko zdarzenia wyboru wierszy. Kod jest jednak ogólny i można go używać w przypadku zdarzeń wyboru wierszy, kolumn i komórek.

Oto kod modułu obsługi 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 gotowe

Większość wykresów Google jest renderowanych asynchronicznie. Po wywołaniu przez nie wywołań draw() wszystkie zdarzenia Google przesyłają zdarzenie, co oznacza, że jest on renderowany i gotowy do zwrócenia właściwości lub obsługi kolejnych wywołań metod. Przed wywołaniem metody draw() należy zawsze nasłuchiwać gotowego zdarzenia.

Ogólnie wykresy, które ujawniają zdarzenie „ready”, są zgodne z tymi specyfikacjami:

• Gotowy zdarzenie nie przekazuje do modułu żadnych właściwości (funkcja Twojej funkcji nie powinna oczekiwać od niego żadnych parametrów).
• Wykres powinien powinien się uruchamiać, gdy wykres będzie gotowy do interakcji. Jeśli rysowanie wykresu jest asynchroniczne, ważne jest, by zdarzenie było wywoływane, gdy można wywołać metody interakcji, a nie tylko po zakończeniu metody draw.
• Musisz dodać odbiornik do tego zdarzenia, zanim wywołasz metodę draw(). W przeciwnym razie zdarzenie może zostać uruchomione przed skonfigurowaniem detektora i nie będzie go można wykryć.
• Wywoływanie metod interakcji przed uruchomieniem gotowego zdarzenia może spowodować, że nie będą one działać prawidłowo.

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

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

Składnia modułów obsługi zdarzeń

function myReadyHandler(){...}

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

Zdarzenie error

Wykresy powinny generować zdarzenia błędu, gdy natrafią na jakiś błąd, aby można go było bez problemu rozwiązać. Moduł obsługi zdarzeń przekazuje opis błędu, a także właściwości zdarzenia niestandardowego związane z każdym wykresem. Zasubskrybuj to zdarzenie zaraz po wywołaniu wykresu, aby ograniczyć wszelkie błędy, które mogą wystąpić w kolejnych krokach.

Możesz skorzystać z funkcji pomocniczych goog.visualization.errors, które pomogą Ci wyświetlać błędy bezbłędnie.

Składnia modułów obsługi zdarzeń

function myErrorHandler(err){...}

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

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

Przykład obsługi zdarzeń

Poniższy przykład pokazuje funkcje getSelection() i setSelection(). Synchronizuje wybór między 2 wykresami, które korzystają z tej samej tabeli danych. Kliknij dowolny 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, aby zobaczyć, jak działają wybrane elementy: