Ereignisse verarbeiten

Auf dieser Seite wird beschrieben, wie Sie auf Ereignisse warten und verarbeiten, die von einem Diagramm ausgelöst werden.

Inhalt

1. Overview
2. Registrieren und Verarbeiten eines Ereignisses
3. Ereignisinformationen abrufen
4. Das select-Ereignis
5. Das ready-Event
6. Das Ereignis error
7. Beispiel für die Verarbeitung von Ereignissen

Übersicht

Google-Diagramme können Ereignisse auslösen, die Sie beobachten können. Ereignisse können durch Nutzeraktionen ausgelöst werden, z. B. wenn ein Nutzer auf ein Diagramm klickt. 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.

Jedes Diagramm definiert seine eigenen Ereignisse. In der Dokumentation für dieses Diagramm sollte beschrieben werden, wann jedes Ereignis ausgelöst wird, was es bedeutet und wie Sie alle mit dem Ereignis verknüpften Informationen abrufen können. Auf dieser Seite wird beschrieben, wie Sie sich registrieren, um Ereignisse aus einem Diagramm zu empfangen, und wie Sie diese verarbeiten.

Es gibt ein Ereignis, das in jedem auswählbaren Diagramm ausgelöst werden sollte: das select-Ereignis. Verhalten und Bedeutung dieses Ereignisses werden jedoch durch das jeweilige Diagramm definiert.

Wichtig: Die Diagrammereignisse sind unabhängig von den standardmäßigen DOM-Ereignissen.

Ereignis registrieren und verarbeiten

Zum Registrieren der Event-Handler rufen Sie google.visualization.events.addListener() oder addOneTimeListener() mit dem Namen des Diagramms auf, das das Ereignis bereitstellt, dem Stringnamen des Ereignisses, auf das gewartet werden soll, und dem Namen der Funktion, die beim Auslösen des Ereignisses aufgerufen werden soll. Die Funktion sollte einen einzelnen Parameter akzeptieren, der das ausgelöste Ereignis ist. Dieses Ereignis kann benutzerdefinierte Informationen enthalten, wie in der Diagrammdokumentation beschrieben.

Wichtig:Wenn in Ihrem Diagramm ein ready-Ereignis angezeigt wird, sollten Sie immer warten, bis dieses Ereignis ausgelöst wird, bevor Sie versuchen, Methoden zu senden oder Ereignisse aus dem Diagramm zu empfangen. Diese Diagramme funktionieren möglicherweise, bevor sie ein Bereitschaftsereignis ausgeben. Dieses Verhalten ist jedoch nicht garantiert.

Mit dem folgenden Code-Snippet wird jedes Mal ein Benachrichtigungsfeld angezeigt, wenn der Nutzer auf eine Tabellenzeile klickt:

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

Dadurch wird nur registriert, um auf Ereignisse für dieses bestimmte Tabellenobjekt zu warten. Eine Registrierung ist nur für den Empfang von Ereignissen von einem bestimmten Objekt möglich.

Sie können auch eine Funktionsdefinition übergeben, wie hier gezeigt:

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

Termininformationen abrufen

Ereignisse stellen Informationen im Allgemeinen auf zwei Arten bereit: durch Übergabe von Informationen an die Handler-Funktion als Parameter oder durch Hinzufügen von Informationen zu einem globalen Objekt. Ob und wie das Ereignis Informationen auslöst, finden Sie in der Dokumentation zum jeweiligen Diagramm. So rufen Sie beide Arten von Informationen ab:

An den Handler übergebene Ereignisinformationen

Wenn das Diagramm Daten als Parameter an die Verarbeitungsfunktion übergibt, würden Sie sie so abrufen:

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

Der an den Handler übergebene Parameter hat eine Eigenschaft, die für das Diagramm dokumentiert werden sollte. Ein Beispiel für ein Diagramm, in dem Ereignisinformationen auf diese Weise dargestellt werden, finden Sie im Seitenereignis des Diagramms Tabelle.

An ein globales Objekt übergebene Ereignisinformationen

Einige Ereignisse ändern stattdessen eine Eigenschaft eines globalen Objekts, das Sie dann anfordern können. Ein gängiges Beispiel dafür ist das Ereignis „select“, das ausgelöst wird, wenn ein Nutzer einen Teil eines Diagramms auswählt. In diesem Fall muss der Code getSelection() im Diagramm aufrufen, um die aktuelle Auswahl zu ermitteln. Weitere Informationen zum select-Ereignis finden Sie unten.

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

Das select-Ereignis

Wie bereits erwähnt sollte jedes Diagramm, das ausgewählt werden kann, ein „select“-Ereignis auslösen, das standardmäßig funktioniert, damit Sie die Werte des ausgewählten Elements im Diagramm abrufen können. Es gibt jedoch keine absolute Anforderung, dass sich ein Diagramm so verhält. Sehen Sie in der Dokumentation zu Ihrem Diagramm nach.

Im Allgemeinen werden Diagramme, in denen das Ereignis „select“ angezeigt wird, mit den folgenden Spezifikationen entworfen:

• Das select-Ereignis übergibt keine Eigenschaften oder Objekte an den Handler. Der Funktions-Handler sollte keine Parameter erwarten, die an den Handler übergeben werden.
• Das Diagramm sollte die Methode getSelection() bereitstellen, die ein Array von Objekten zurückgibt, die die ausgewählten Datenelemente beschreiben. Diese Objekte haben die Attribute row und column. row und column sind die Zeilen- und Spaltenindexe des ausgewählten Elements in der DataTable. Auswahlereignisse beschreiben die zugrunde liegenden Daten in der Grafik, keine HTML-Elemente im Diagramm. Um die Daten des ausgewählten Elements abzurufen, müssen Sie DataTable.getValue() oder getFormattedValue() aufrufen.
  Wenn sowohl row als auch column angegeben sind, ist das ausgewählte Element eine Zelle. Wenn nur row angegeben ist, ist das ausgewählte Element eine Zeile. Wenn nur column angegeben ist, ist das ausgewählte Element eine Spalte.
• Im Diagramm sollte die Methode setSelection(selection) verfügbar sein, um die Auswahl in der zugrunde liegenden Tabelle zu ändern und die entsprechenden Daten im Diagramm auszuwählen. Den selection-Parameter, der ein Array ist, das dem getSelection()-Array ähnelt, wobei jedes Element ein Objekt mit den Eigenschaften row und column ist Das Attribut row definiert den Index der ausgewählten Zeile in DataTable und das Attribut column den Index der ausgewählten Spalte in DataTable. Wenn diese Methode aufgerufen wird, sollte im Diagramm die neue Auswahl visuell dargestellt werden. Die Implementierung von setSelection() sollte kein „select“-Ereignis auslösen.
  Wenn sowohl row als auch column angegeben sind, ist das ausgewählte Element eine Zelle. Wenn nur row angegeben ist, ist das ausgewählte Element eine Zeile. Wenn nur column angegeben ist, ist das ausgewählte Element eine Spalte.

Einschränkungen:

• Das Diagramm ignoriert möglicherweise einen Teil der Auswahl. Beispielsweise kann eine Tabelle, in der nur ausgewählte Zeilen angezeigt werden können, Zellen- oder Spaltenelemente in ihrer setSelection-Implementierung ignorieren.
• Einige Diagramme lösen möglicherweise kein „select“-Ereignis aus und einige Diagramme unterstützen möglicherweise nur die Auswahl der gesamten Zeilen oder der gesamten Spalten. In der Dokumentation der einzelnen Diagramme sind die unterstützten Ereignisse und Methoden definiert.
• Die Mehrfachauswahl wird in verschiedenen Diagrammen unterschiedlich gehandhabt (manche lassen sie nicht einmal zu).
• Zum Lesen der ausgewählten Daten müssen Sie DataTable.getValue() in Ihrem Handler aufrufen. Die einfachste Möglichkeit, dies zu aktivieren, besteht darin, das DataTable-Objekt global zu konfigurieren.

Im folgenden Beispiel wird eine Benachrichtigung mit den ausgewählten Tabellenelementen angezeigt, wenn ein Element eines Tabellendiagramms ausgewählt wird:

Das Tabellendiagramm löst nur Zeilenauswahlereignisse aus. Der Code ist jedoch generisch und kann für Zeilen-, Spalten- und Zellenauswahlereignisse verwendet werden.

Hier ist der Handler-Code für dieses Beispiel:

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

Die fertige Veranstaltung

Die meisten Diagramme werden asynchron gerendert. Alle Google-Diagramme geben nach dem Aufruf von draw() ein „ready“-Ereignis aus. Dies zeigt an, dass das Diagramm gerendert wurde und bereit ist, Eigenschaften zurückzugeben oder weitere Methodenaufrufe zu verarbeiten. Sie sollten immer auf das Bereitschaftsereignis warten, bevor Sie nach dem Aufruf von draw() versuchen, Methoden dafür aufzurufen.

Im Allgemeinen werden Diagramme, 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.
• Das Diagramm sollte das Ereignis „Bereit“ auslösen, sobald das Diagramm für eine Interaktion bereit ist. Wenn das Diagramm asynchron gezeichnet 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, besteht das Risiko, dass diese Methoden nicht ordnungsgemäß funktionieren.

Gemäß der Konvention sind Diagramme, die kein „ready“-Ereignis auslösen, sofort für eine Interaktion bereit, nachdem die draw-Methode beendet wurde und die Steuerung an den Nutzer zurückgegeben wird. Wenn durch Ihr Diagramm ein Bereitschaftsereignis ausgelöst wird, sollten Sie warten, bis es ausgelöst wird, bevor Sie Methoden dafür aufrufen, wie hier gezeigt:

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

Ready Event-Handler-Syntax

function myReadyHandler(){...}

An den Bereitschafts-Event-Handler werden keine Parameter übergeben.

Das Ereignis error

Diagramme sollten ein Fehlerereignis ausgeben, wenn ein Fehler auftritt, damit Sie diesen ordnungsgemäß verarbeiten können. Dem Ereignis-Handler werden eine Fehlerbeschreibung sowie benutzerdefinierte Ereigniseigenschaften für jedes Diagramm übergeben. Sie sollten dieses Ereignis direkt nach der Instanziierung des Diagramms abonnieren, um alle Fehler zu erfassen, die in späteren Schritten auftreten können.

Mit den Hilfsfunktionen von goog.visualization.errors können Sie dem Nutzer Fehler anzeigen lassen.

Syntax des Fehler-Event-Handlers

function myErrorHandler(err){...}

An den Fehler-Event-Handler sollte ein -Objekt mit den folgenden Membern übergeben werden:

• id [erforderlich]: ID des DOM-Elements, das das Diagramm enthält, oder eine Fehlermeldung, die anstelle des Diagramms angezeigt wird, wenn es nicht gerendert werden kann.
• message [erforderlich]: ein kurzer Nachrichtenstring, der den Fehler beschreibt.
• detailedMessage [optional]: eine detaillierte Erklärung des Fehlers.
• options [optional]: Ein Objekt mit benutzerdefinierten Parametern, die für diesen Fehler und Diagrammtyp geeignet sind.

Beispiel für die Ereignisverarbeitung

Im folgenden Beispiel werden getSelection() und setSelection() veranschaulicht. Dabei wird die Auswahl zwischen zwei Diagrammen synchronisiert, die dieselbe Datentabelle verwenden. Klicken Sie auf eines der Diagramme, um die Auswahl im anderen Diagramm zu synchronisieren.

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

Klicken Sie in den folgenden Diagrammen auf Tabellenzeilen oder Diagrammelemente, um die Auswahl in Aktion zu sehen: