Ereignisse bearbeiten

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

Inhalt

1. Übersicht
2. Veranstaltung registrieren und verarbeiten
3. Informationen zu Ereignissen abrufen
4. Das select-Ereignis
5. Das Ereignis ready
6. Das Ereignis error
7. Beispiel: Ereignisbehandlung

Ü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 so registrieren, dass sie bei jedem Auslösen bestimmter Ereignisse aufgerufen wird, möglicherweise mit spezifischen Daten für dieses Ereignis.

Jedes Diagramm definiert seine eigenen Ereignisse und 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 für den Empfang von Ereignissen aus einem Diagramm registrieren und diese verarbeiten.

Es gibt ein Ereignis, das von jedem auswählbaren Diagramm ausgelöst werden soll: das ausgewählte Ereignis. Das Verhalten und die Bedeutung dieses Ereignisses sind jedoch in jedem Diagramm definiert.

Es ist wichtig zu beachten, dass die Diagrammereignisse von den Standard-DOM-Ereignissen strikt getrennt und eigenständig sind.

Ereignis registrieren und verarbeiten

Rufen Sie zum Registrieren Ihrer Event-Handler google.visualization.events.addListener() oder addOneTimeListener() auf. Geben Sie dabei den Namen des Diagramms, das das Ereignis verfügbar macht, den Stringnamen des zu überwachenden Ereignisses und den Namen der Funktion an, die beim Auslösen dieses Ereignisses aufgerufen werden soll. Die Funktion sollte einen einzelnen Parameter akzeptieren, der das ausgelöste Ereignis ist. Dieses Ereignis kann benutzerdefinierte Informationen zum Ereignis enthalten, wie in der Diagrammdokumentation beschrieben.

Wichtig: Wenn Ihr Diagramm ein bereites Ereignis enthält, sollten Sie immer darauf warten, dass dieses Ereignis ausgelöst wird, bevor Sie versuchen, Methoden zu senden oder Ereignisse aus dem Diagramm zu empfangen. Diese Diagramme funktionieren möglicherweise, bevor ein bereites Ereignis ausgelöst wird. Dieses Verhalten ist jedoch nicht garantiert.

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

Beachten Sie, dass dies nur zum Überwachen von Ereignissen für dieses bestimmte Tabellenobjekt registriert wird. Sie können sich nur registrieren, um Ereignisse von einem bestimmten Objekt zu erhalten.

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 das Übergeben von Informationen an die Handler-Funktion als Parameter oder durch Hinzufügen von Informationen zu einem globalen Objekt. Ob und wie Informationen zum Ereignis offengelegt werden, sollte in der Dokumentation für dieses Diagramm beschrieben werden. So rufen Sie beide Arten von Informationen ab:

An den Handler übergebene Ereignisinformationen

Wenn das Diagramm Daten als Parameter an Ihre 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 Ihren Handler übergebene Parameter hat eine Eigenschaft, die für das Diagramm dokumentiert werden sollte. Ein Beispiel für ein Diagramm, das Ereignisinformationen auf diese Weise verfügbar macht, finden Sie auf der Seite des Tabellenereignisses.

An ein globales Objekt übergebene Ereignisinformationen

Bei einigen Ereignissen wird stattdessen die Eigenschaft eines globalen Objekts geändert, die Sie dann anfordern können. Ein gängiges Beispiel hierfür ist das „select“-Ereignis, das ausgelöst wird, wenn ein Nutzer einen Teil eines Diagramms auswählt. In diesem Fall muss der Code „getSelection()“ für das Diagramm aufrufen, um die aktuelle Auswahl zu ermitteln. Weitere Informationen zum Auswahlereignis 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 Ereignis select

Wie bereits erwähnt, sollten in jedem Diagramm, das ausgewählt werden kann, ein „select“-Ereignis (Standard) ausgelöst werden, mit dem Sie die Werte des ausgewählten Elements im Diagramm abrufen können. Es gibt jedoch keine absolute Anforderung, dass sich ein Diagramm auf diese Weise verhält. Lesen Sie dazu die Dokumentation für Ihr Diagramm.

Diagramme, in denen das „select“-Ereignis verfügbar gemacht wird, haben im Allgemeinen die folgenden Spezifikationen:

• Das ausgewählte Ereignis übergibt keine Properties oder Objekte an den Handler. Der Funktions-Handler sollte nicht erwarten, dass Parameter an ihn übergeben werden.
• Im Diagramm sollte die Methode getSelection() verfügbar sein, mit der ein Array von Objekten zurückgegeben wird, 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 im DataTable. (Auswahlereignisse beschreiben die zugrunde liegenden Daten im Diagramm, keine HTML-Elemente im Diagramm.) Zum Abrufen der Daten des ausgewählten Elements 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.
• Das Diagramm sollte die Methode setSelection(selection) verfügbar machen, um die Auswahl in der zugrunde liegenden Tabelle zu ändern und die entsprechenden Daten im Diagramm auszuwählen. Der select-Parameter, der ein Array ähnlich dem getSelection()-Array ist, wobei jedes Element ein Objekt mit den Attributen row und column ist. Das Attribut row definiert den Index der ausgewählten Zeile im DataTable. Das Attribut column definiert den Index der ausgewählten Spalte im DataTable. Wenn diese Methode aufgerufen wird, sollte das Diagramm die neue Auswahl visuell darstellen. Die Implementierung von setSelection() sollte nicht ein „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.

Hinweise:

• Im Diagramm wird möglicherweise ein Teil der Auswahl ignoriert. In einer Tabelle, die nur ausgewählte Zeilen enthalten kann, werden Zellen- oder Spaltenelemente in der setSelection-Implementierung beispielsweise ignoriert.
• Bei einigen Diagrammen wird möglicherweise kein „select“-Ereignis ausgelöst und bei einigen Diagrammen wird nur die gesamte Zeilenauswahl oder die gesamte Spaltenauswahl unterstützt. In der Dokumentation der einzelnen Diagramme werden die unterstützten Ereignisse und Methoden definiert.
• Die Mehrfachauswahl wird in verschiedenen Diagrammen unterschiedlich behandelt (manche lassen dies nicht zu).
• Zum Lesen der ausgewählten Daten müssen Sie DataTable.getValue() in Ihrem Handler aufrufen. Am einfachsten aktivieren Sie das Objekt DataTable global.

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

Beachten Sie, dass das Tabellendiagramm nur Zeilenauswahlereignisse auslöst. 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);
}

Das ready-Ereignis

Die meisten Diagramme werden asynchron gerendert. Alle Google-Diagramme geben ein „ready“-Ereignis aus, nachdem sie draw() aufgerufen haben. Das bedeutet, dass das Diagramm gerendert wurde und Eigenschaften oder weitere Methodenaufrufe zurückgeben kann. Sie sollten immer auf das Ereignis „ready“ warten, bevor Sie Methoden dafür aufrufen, nachdem Sie draw() aufgerufen haben.

Für Diagramme, in denen das Ereignis „Bereit“ angezeigt wird, gelten im Allgemeinen die folgenden Spezifikationen:

• Das Bereitschaftsereignis gibt keine Attribute an den Handler weiter (der Funktions-Handler sollte nicht erwarten, dass Parameter an ihn übergeben werden).
• Das Diagramm sollte das Ereignis „Bereit“ auslösen, nachdem es für die Interaktion bereit ist. Wenn das Zeichnen des Diagramms asynchron ist, ist es wichtig, dass das Ereignis ausgelöst wird, wenn Interaktionsmethoden tatsächlich aufgerufen werden können, und nicht nur, wenn die Methode draw endet.
• Fügen Sie diesem Ereignis einen Listener hinzu, bevor Sie die Methode draw() aufrufen. Andernfalls wird das Ereignis möglicherweise ausgelöst, bevor der Listener eingerichtet ist und Sie ihn nicht abfangen.
• Wenn Sie Interaktionsmethoden aufrufen, bevor das Ereignis „Bereit“ ausgelöst wird, besteht das Risiko, dass diese Methoden nicht richtig funktionieren.

Gemäß der Konvention sind Diagramme, die kein „ready“-Ereignis auslösen, unmittelbar nach dem Ende der Methode draw zur Interaktion bereit und geben die Kontrolle an den Nutzer zurück. Wenn Ihr Diagramm einbereites Ereignis auslöst, sollten Sie warten, bis es ausgelöst wird, bevor Sie Methoden dafür aufrufen:

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

Syntax von Ready Event-Handlern

function myReadyHandler(){...}

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

Das Ereignis error

Diagramme sollten ein Fehlerereignis auslösen, wenn ein Fehler auftritt, damit Sie ihn problemlos bearbeiten können. An den Event-Handler werden eine Beschreibung des Fehlers sowie benutzerdefinierte Ereigniseigenschaften für jedes Diagramm übergeben. Sie sollten dieses Ereignis direkt nach der Instanziierung des Diagramms abonnieren, damit etwaige Fehler, die in späteren Schritten auftreten können, erfasst werden.

Mit den Hilfsfunktionen von goog.visualization.errors können Sie Fehler für den Nutzer reibungslos anzeigen.

Syntax des Fehlerereignis-Handlers

function myErrorHandler(err){...}

An den Fehlerereignis-Handler sollte ein Objekt mit den folgenden Mitgliedern übergeben werden:

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

Beispiel für die Verarbeitung von Ereignissen

Im folgenden Beispiel werden sowohl „getSelection()“ als auch „setSelection()“ veranschaulicht. Die Auswahl wird zwischen zwei Diagrammen synchronisiert, die dieselbe Datentabelle verwenden. Klicken Sie auf ein Diagramm, 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 auf die folgenden Diagramme in Tabellenzeilen oder Diagrammelementen, um die Auswahl in Aktion zu sehen: