Uruchamianie zdarzeń

Wizualizacja może uruchamiać zdarzenia, które może zarejestrować strona hostująca. Zdarzenia mogą być uruchamiane przez działania użytkownika, np. kliknięcie wykresu czy działanie wewnętrzne, np. wywoływanie zdarzenia co 10 sekund. 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żda wizualizacja definiuje własne zdarzenia, a jej dokumentacja powinna zawierać informacje o tym, kiedy poszczególne zdarzenia są uruchamiane, co to oznacza i jakie informacje są wysyłane do modułu obsługi zdarzeń (np. wizualizacja na wykresie organizacyjnym). Z tego artykułu dowiesz się, jak twórca wizualizacji może uruchamiać zdarzenia. Informacje o tym, jak klienci mogą rejestrować się na otrzymywanie zdarzeń, znajdziesz na stronie Obsługa zdarzeń.

Jest jedno zdarzenie, które powinno być uruchamiane w ramach dowolnej wizualizacji, którą można wybrać: zdarzenie wyboru. Działanie i znaczenie tego zdarzenia są jednak definiowane przez każdą wizualizację.

Jeśli wizualizacja nie jest gotowa do interakcji natychmiast po tym, jak metoda draw zwróci kontrolę użytkownikowi, wizualizacja powinna się uruchomić: zdarzenie gotowe. Dokładny opis działania i znaczenia wydarzenia znajdziesz w sekcji The Event Event (Zdarzenie gotowe).

Pamiętaj, że zdarzenia API wizualizacji to nie to samo co standardowe zdarzenia DOM.

Spis treści

  1. Uruchamianie zdarzenia
  2. Wybierz wydarzenie
  3. Przygotowania do wydarzenia
  4. Więcej informacji

Uruchamianie zdarzenia

Aby uruchomić zdarzenie na podstawie wizualizacji, użyj funkcji google.visualization.events.trigger(). Funkcja oczekuje następujących parametrów:

  1. Wizualizacja źródła (zazwyczaj jest to wartość this).
  2. Nazwa zdarzenia (ciąg znaków).
  3. Szczegóły zdarzenia (obiekt). Opcjonalna mapa (nazwa/wartość) szczegółów zdarzenia.

Poniższy przykład pokazuje, jak wizualizacja wywołuje wybrane zdarzenie: 

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

Możesz hostować strony gospodarza, aby otrzymywać informacje o wydarzeniach pod numerem google.visualization.events.addListener() lub google.visualization.events.addOneTimeListener(). Pamiętaj, by dokumentować dokładnie wszystkie uruchamiane zdarzenia.

Wybierz wydarzenie

Zdarzenie „select” to standardowe zdarzenie wywoływane przez wiele wizualizacji w odpowiedzi na kliknięcie przez użytkownika myszą. Jeśli chcesz wywoływać zdarzenie w odpowiedzi na kliknięcie myszą, musisz zaimplementować zdarzenie „select” w standardowy sposób:

  1. Uruchom zdarzenie o nazwie „select”, gdy użytkownik wybierze dane w wizualizacji. Zdarzenie nie wysyła żadnych funkcji do funkcji słuchania.
  2. Udostępnij metodę getSelection() w sposób opisany w połączonej sekcji dokumentu. Ta metoda powinna zwracać indeksy elementów data wybranych przez użytkownika.
  3. Udostępnij metodę setSelection() zgodnie z opisem w sekcji. Aby dowiedzieć się, jak obsługiwać zdarzenia, wejdź na stronę obsługi zdarzeń.

Wydarzenie przygotowane

Każda wizualizacja powinna wywoływać zdarzenie „ready”, które działa w standardowy sposób, aby poinformować dewelopera, kiedy wizualizacja jest gotowa do przetworzenia tzw. metod. Nie ma jednak absolutnie żadnych wymagań, aby wizualizacja działała w ten sposób. Zapoznaj się z dokumentacją wizualizacji.

Wizualizacje, które udostępniają 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).
  • Wizualizacja powinna uruchomić zdarzenie gotowości, gdy wizualizacja będzie gotowa do interakcji. Jeśli wizualizacja jest asynchroniczny, ważne jest, aby 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 oznacza ryzyko, że te metody nie będą działać prawidłowo.

Konwencja polega na tym, że wizualizacje, które nie uruchamiają zdarzenia „gotowego”, są gotowe do interakcji bezpośrednio po zakończeniu metody draw i zwracają użytkownikowi kontrolę.

Więcej informacji