Auslösung von Ereignissen

Ihre Visualisierung kann Ereignisse auslösen, die eine Hostseite für den Empfang registrieren kann. Ereignisse können durch Nutzeraktionen ausgelöst werden, z. B. wenn ein Nutzer auf ein Diagramm klickt, oder auch intern, z. B. das Auslösen eines Ereignisses alle 10 Sekunden. Sie können eine JavaScript-Methode registrieren, die immer dann aufgerufen wird, wenn bestimmte Ereignisse ausgelöst werden, möglicherweise mit spezifischen Daten für dieses Ereignis.

Jede Visualisierung definiert ihre eigenen Ereignisse. In der Dokumentation für diese Visualisierung sollte beschrieben werden, wann jedes Ereignis ausgelöst wird, was es bedeutet und welche Informationen an den Event-Handler gesendet werden (siehe Orgchart-Visualisierung). Auf dieser Seite wird beschrieben, wie Ereignisse vom Ersteller von Visualisierungen ausgelöst werden können. Informationen dazu, wie sich Clients für den Empfang von Ereignissen registrieren können, finden Sie auf der Seite Ereignisse verarbeiten.

Es gibt ein Ereignis, das jede auswählbare Visualisierung auslösen sollte: das select-Ereignis. Verhalten und Bedeutung dieses Ereignisses werden jedoch von jeder Visualisierung definiert.

Wenn eine Visualisierung nicht sofort für eine Interaktion bereit ist, nachdem die Methode draw die Steuerung an den Nutzer zurückgegeben hat, sollte die Visualisierung ausgelöst werden: das Ereignis „Ready“. Das genaue Verhalten und die Bedeutung dieses Ereignisses wird im Abschnitt „Ready“-Ereignis definiert.

Beachten Sie, dass die Visualization API-Ereignisse von den standardmäßigen DOM-Ereignissen getrennt sind.

Inhalt

  1. Ereignis auslösen
  2. Das ausgewählte Ereignis
  3. Die Vorbereitungen
  4. Weitere Informationen

Ereignis auslösen

Wenn Sie ein Ereignis aus Ihrer Visualisierung auslösen möchten, rufen Sie die Funktion google.visualization.events.trigger() auf. Die Funktion erwartet die folgenden Parameter:

  1. Quellvisualisierung (in der Regel der Wert this).
  2. Ereignisname (String).
  3. Ereignisdetails (Objekt) Eine optionale Zuordnung (Name/Wert) bestimmter Ereignisdetails.

Das folgende Beispiel zeigt, wie eine Visualisierung das select-Ereignis auslöst: 

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

Hostingseiten können sich für den Empfang Ihrer Veranstaltungen registrieren, indem Sie google.visualization.events.addListener() oder google.visualization.events.addOneTimeListener() aufrufen. Dokumentieren Sie alle ausgelösten Ereignisse gründlich.

Das ausgewählte Ereignis

Das „select“-Ereignis ist ein Standardereignis, das von vielen Visualisierungen als Reaktion auf einen Mausklick ausgelöst wird. Wenn du ein Ereignis als Reaktion auf Mausklicks auslösen möchtest, musst du das „select“-Ereignis wie hier beschrieben implementieren:

  1. Ein Ereignis mit dem Namen „select“ auslösen, wenn der Nutzer Daten in der Visualisierung auswählt. Das Ereignis sendet keine Argumente an die Überwachungsfunktionen.
  2. Machen Sie die Methode getSelection() wie im Abschnitt zu verknüpften Dokumenten beschrieben verfügbar. Diese Methode sollte die Indexe der Datenelemente zurückgeben, die der Nutzer ausgewählt hat.
  3. Machen Sie die Methode setSelection() wie in der Referenz beschrieben verfügbar. Informationen zum Verarbeiten von Ereignissen finden Sie auf der Seite Ereignisse verarbeiten.

Das „Bereit“-Ereignis

Jede Visualisierung sollte ein „ready“-Ereignis auslösen, das standardmäßig funktioniert und den Entwickler darüber informiert, wann die Visualisierung zur Verarbeitung bereit ist. Diese werden als Methoden bezeichnet. (Es gibt jedoch keine absolute Anforderung, dass sich eine Visualisierung so verhalten. Sehen Sie in der Dokumentation Ihrer Visualisierung nach.)

Im Allgemeinen werden Visualisierungen, die das Ereignis „ready“ anzeigen, mit den folgenden Spezifikationen entworfen:

  • Das Bereitschaftsereignis übergibt keine Eigenschaften an den Handler. Der Funktions-Handler sollte keine Parameter erwarten, die an den Handler übergeben werden.
  • Die Visualisierung sollte das Ereignis „Bereit“ auslösen, wenn die Visualisierung für eine Interaktion bereit ist. Wenn die Visualisierung asynchron dargestellt wird, muss das Ereignis ausgelöst werden, wenn Interaktionsmethoden tatsächlich aufgerufen werden können, und nicht nur, wenn die Methode draw endet.
  • Diesem Ereignis sollte ein Listener hinzugefügt werden, bevor die Methode draw aufgerufen wird. Andernfalls könnte das Ereignis vor der Einrichtung des Listeners ausgelöst werden und wird von Ihnen nicht abgefangen.
  • Wenn Sie Interaktionsmethoden aufrufen, bevor das Ereignis „ready“ ausgelöst wird, gehen Sie ein Risiko ein, dass diese Methoden nicht ordnungsgemäß funktionieren.

Die Konvention besagt, dass Visualisierungen, die kein „ready“-Ereignis auslösen, sofort nach dem Ende der draw-Methode für eine Interaktion bereit sind und die Steuerung an den Nutzer zurückgeben.

Weitere Informationen