Gestione degli eventi

Questa pagina descrive come rimanere in ascolto e gestire gli eventi attivati da un grafico.

Contenuti

  1. Panoramica
  2. Registrazione e gestione di un evento
  3. Recupero delle informazioni sull'evento
  4. L'evento select
  5. L'evento ready
  6. L'evento error
  7. Esempio di gestione degli eventi

Panoramica

I grafici di Google possono attivare eventi che puoi ascoltare. Gli eventi possono essere attivati dalle azioni dell'utente, ad esempio quando un utente fa clic su un grafico. Puoi registrare un metodo JavaScript da chiamare ogni volta che vengono attivati determinati eventi, possibilmente con dati specifici di quell'evento.

Ogni grafico definisce i propri eventi e la relativa documentazione deve descrivere quando viene attivato ciascun evento, il relativo significato e come recuperare le informazioni associate all'evento. In questa pagina viene descritto come registrarsi per ricevere eventi da un grafico e come gestirli.

Esiste un evento che deve essere attivato da qualsiasi grafico selezionabile: l'evento select. Tuttavia, il comportamento e il significato di questo evento sono definiti da ogni grafico.

È importante notare che gli eventi del grafico sono separati e distinti dagli eventi DOM standard.

Registrazione e gestione di un evento

Per registrare i gestori di eventi, chiami google.visualization.events.addListener() o addOneTimeListener() con il nome del grafico che espone l'evento, il nome stringa dell'evento da ascoltare e il nome della funzione da chiamare quando viene attivato questo evento. La funzione deve accettare un singolo parametro corrispondente all'evento che è stato attivato. Questo evento può avere informazioni personalizzate sull'evento, come descritto nella documentazione dei grafici.

Importante: se il grafico espone un evento pronto, devi sempre attendere che l'evento venga attivato prima di provare a inviare metodi o ricevere eventi dal grafico. Questi grafici potrebbero funzionare prima di generare un evento pronto, ma questo comportamento non è garantito.

Il seguente snippet di codice mostra una casella di avviso ogni volta che l'utente fa clic su una riga della tabella:

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

Tieni presente che questa operazione verrà registrata solo per ascoltare gli eventi per questo oggetto tabella specifico; puoi registrarti solo per ricevere eventi da un oggetto specifico.

Puoi anche passare la definizione di una funzione, come mostrato di seguito:

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

Recupero delle informazioni sull'evento

In genere, gli eventi espongono le informazioni in due modi: passando le informazioni alla funzione gestore come parametro o aggiungendo informazioni a un oggetto globale. Se e come l'evento espone le informazioni, devi descrivere nella documentazione relativa a quel grafico. Ecco come recuperare entrambi i tipi di informazioni:

Informazioni sugli eventi trasmesse al gestore

Se il grafico trasmette i dati come parametro alla funzione di gestione, devi recuperarli come mostrato qui:

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

Il parametro passato al gestore avrà una proprietà che deve essere documentata per il grafico. Per un esempio di grafico che mostra le informazioni sugli eventi in questo modo, vedi l'evento di pagina del grafico Tabella.

Informazioni sugli eventi passate a un oggetto globale

Alcuni eventi modificano invece la proprietà di un oggetto globale, che puoi richiedere. Un esempio comune è l'evento "select", che viene attivato quando un utente seleziona una parte di un grafico. In questo caso, il codice deve chiamare getSelection() sul grafico per scoprire quale sia la selezione corrente. Ulteriori informazioni sull'evento di selezione di seguito.

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

L'evento select

Come accennato in precedenza, tutti i grafici selezionabili dovrebbero attivare un evento "select" che funziona in modo standard per consentirti di recuperare i valori dell'elemento selezionato nel grafico. Tuttavia, non esiste un requisito assoluto secondo cui un grafico si comporti in questo modo; consulta la documentazione del grafico.

In generale, i grafici che espongono l'evento "select" sono progettati con le seguenti specifiche:

  • L'evento select non passa proprietà o oggetti al gestore (il gestore di funzioni non deve aspettarsi che gli vengano passati parametri).
  • Il grafico deve esporre il metodo getSelection(), che restituisce un array di oggetti che descrivono gli elementi di dati selezionati. Questi oggetti hanno le proprietà row e column. row e column sono gli indici di riga e colonna dell'elemento selezionato in DataTable. Gli eventi di selezione descrivono i dati sottostanti del grafico, non gli elementi HTML nel grafico. Per visualizzare i dati dell'elemento selezionato, devi chiamare DataTable.getValue() o getFormattedValue().
    Se sono specificati sia row sia column, l'elemento selezionato è una cella. Se viene specificato solo row, l'elemento selezionato è una riga. Se viene specificato solo column, l'elemento selezionato è una colonna.
  • Il grafico deve esporre il metodo setSelection(selection) per modificare la selezione nella tabella sottostante e selezionare i dati corrispondenti nel grafico. Il parametro selection è un array simile all'array getSelection(), in cui ogni elemento è un oggetto con proprietà row e column. La proprietà row definisce l'indice della riga selezionata in DataTable, mentre la proprietà column definisce l'indice della colonna selezionata in DataTable. Quando viene chiamato questo metodo, il grafico deve indicare visivamente la nuova selezione. L'implementazione di setSelection() non deve attivare un evento 'select'.
    Se sono specificati sia row sia column, l'elemento selezionato è una cella. Se viene specificato solo row, l'elemento selezionato è una riga. Se viene specificato solo column, l'elemento selezionato è una colonna.

Alcune avvertenze:

  • Il grafico potrebbe ignorare parte della selezione. Ad esempio, una tabella che può mostrare solo righe selezionate potrebbe ignorare gli elementi di cella o colonna nella relativa implementazione di setSelection.
  • Alcuni grafici potrebbero non attivare un evento "select", mentre altri potrebbero supportare solo la selezione dell'intera riga o dell'intera colonna. La documentazione di ogni grafico definisce gli eventi e i metodi che supporta.
  • La selezione multipla viene gestita in modo diverso nei vari grafici (alcuni non lo consentono nemmeno).
  • Per leggere i dati selezionati, devi chiamare DataTable.getValue() nel tuo gestore. Il modo più semplice per abilitarlo è rendere globale l'oggetto DataTable.

L'esempio seguente mostra una casella di avviso con gli elementi della tabella selezionati quando è selezionato un elemento di un grafico a tabella:

Tieni presente che il grafico a tabella attiva solo eventi di selezione delle righe. Tuttavia, il codice è generico e può essere utilizzato per eventi di selezione di righe, colonne e celle.

Ecco il codice gestore per l'esempio:

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

L'evento ready

La maggior parte dei grafici viene visualizzata in modo asincrono. Tutti i grafici di Google generano un evento pronto dopo la chiamata a draw(), a indicare che il grafico è stato visualizzato ed è pronto a restituire proprietà o gestire ulteriori chiamate di metodo. Devi sempre rimanere in ascolto dell'evento pronto prima di provare a richiamare i metodi su questo evento dopo aver chiamato draw().

In generale, i grafici che espongono l'evento "ready" sono progettati con le seguenti specifiche:

  • L'evento ready non passa alcuna proprietà al gestore (il gestore della funzione non deve aspettarsi che gli vengano passati parametri).
  • Il grafico dovrebbe attivare l'evento pronto quando è pronto per l'interazione. Se il disegno del grafico è asincrono, è importante che l'evento venga attivato quando i metodi di interazione possono essere effettivamente chiamati, non solo quando termina il metodo draw.
  • Devi aggiungere un listener a questo evento prima di chiamare il metodo draw(), perché altrimenti l'evento potrebbe essere attivato prima della configurazione del listener e non verrà rilevato.
  • Se chiami i metodi di interazione prima che venga attivato l'evento pronto, rischi che questi metodi non funzionino correttamente.

La convenzione prevede che i grafici che non attivano un evento "pronto" siano pronti per l'interazione subito dopo la fine del metodo draw e restituito il controllo all'utente. Se il grafico attiva un evento pronto, devi attendere che venga generato prima di chiamare metodi, come mostrato qui:

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

Sintassi del gestore dell'evento pronto

function myReadyHandler(){...}

Al gestore di eventi pronto non viene trasmesso alcun parametro.

L'evento error

Per consentirti di gestirlo senza problemi, i grafici dovrebbero generare un evento di errore quando riscontrano un tipo di errore. Al gestore di eventi vengono trasmesse una descrizione dell'errore e le proprietà dell'evento personalizzato specifiche di ciascun grafico. Devi iscriverti a questo evento subito dopo aver creato un'istanza del grafico per bloccare eventuali errori che potrebbero verificarsi nei passaggi successivi.

Puoi utilizzare le funzioni helper goog.visualization.errors per mostrare all'utente eventuali errori.

Sintassi del gestore degli eventi di errore

function myErrorHandler(err){...}

Al gestore di eventi di errore deve essere passato un oggetto con i seguenti membri:

  • id [obbligatorio]: l'ID dell'elemento DOM contenente il grafico o un messaggio di errore mostrato al posto del grafico se non può essere visualizzato.
  • message [obbligatorio] - Una breve stringa del messaggio che descrive l'errore.
  • detailedMessage [Facoltativo] - Una spiegazione dettagliata dell'errore.
  • options [facoltativo]- Un oggetto contenente parametri personalizzati appropriati per questo errore e per questo tipo di grafico.

Esempio di gestione degli eventi

L'esempio seguente mostra sia getSelection() che setSelection(). Sincronizza la selezione tra due grafici che utilizzano la stessa tabella di dati. Fai clic su uno dei grafici per sincronizzare la selezione nell'altro.

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

Fai clic sui grafici seguenti nelle righe della tabella o sugli elementi del grafico per vedere la selezione in azione: