Gestione degli eventi

Questa pagina descrive come ascoltare e gestire gli eventi attivati da un grafico.

Sommario

Panoramica

I grafici di Google possono attivare gli 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 per quell'evento.

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

Esiste un solo evento che può essere attivato da qualsiasi grafico selezionabile: l'evento selezionato. Tuttavia, il comportamento e il significato di questo evento sono definiti da ciascun 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, chiama google.visualization.events.addListener() o addOneTimeListener() con il nome del grafico che espone l'evento, il nome della stringa dell'evento da ascoltare e il nome della funzione da chiamare quando viene attivato. La funzione deve accettare un singolo parametro, ovvero l'evento attivato. Questo evento può avere informazioni personalizzate sull'evento, come descritto nella documentazione del grafico.

Importante: se il grafico espone un evento pronto, devi sempre attendere che venga attivato prima di provare a inviare metodi o ricevere eventi dal grafico. Questi grafici potrebbero funzionare prima che vengano avviati 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 consente di registrare gli eventi solo per questo evento specifico della tabella; puoi ricevere solo gli eventi da un oggetto specifico.

Puoi anche inserire una definizione di funzione, come mostrato di seguito:

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

Recupero delle informazioni sugli eventi

Generalmente gli eventi espongono le informazioni in due modi: passando informazioni nella funzione gestore come parametro oppure aggiungendo informazioni a un oggetto globale. Se e in che modo l'evento espone informazioni devono essere descritti nella documentazione di quel grafico. Ecco come recuperare i due tipi di informazioni:

Informazioni sugli eventi trasmesse al gestore

Se il grafico trasmette i dati come parametro alla funzione di gestione, puoi recuperarlo 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 trasmesso al tuo gestore avrà una proprietà che deve essere documentata per il grafico. Per un esempio di grafico che espone le informazioni sugli eventi in questo modo, consulta l'evento sulle pagine del grafico Tabella.

Informazioni sull'evento passate a un oggetto globale

Alcuni eventi modificano invece una proprietà di un oggetto globale, che puoi successivamente 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() nel grafico per sapere qual è la selezione corrente. Di seguito vengono fornite ulteriori informazioni sull'evento di selezione.

// 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, qualsiasi grafico che può essere selezionato deve attivare un evento "select" che funzioni in modo standard per consentirti di recuperare i valori dell'elemento selezionato nel grafico. Tuttavia, non esiste un requisito assoluto che un grafico funzioni in questo modo; consulta la documentazione per il grafico.

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

  • L'evento di selezione non trasmette proprietà o oggetti al gestore (il gestore di funzioni non deve trasmettere alcun parametro al gestore).
  • Il grafico deve esporre il metodo getSelection(), che restituisce un array di oggetti che descrivono gli elementi 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 nel grafico, non gli elementi HTML nel grafico. Per ottenere i dati dell'elemento selezionato, devi chiamare DataTable.getValue() o getFormattedValue().
    Se sono specificati sia row che column, l'elemento selezionato è una cella. Se è specificato solo row, l'elemento selezionato è una riga. Se è 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 che è un array simile all'array getSelection(), in cui ogni elemento è un oggetto con le 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 questo metodo viene chiamato, il grafico deve indicare visivamente la nuova selezione. L'implementazione di setSelection() non deve attivare un evento "select".
    Se sono specificati sia row che column, l'elemento selezionato è una cella. Se è specificato solo row, l'elemento selezionato è una riga. Se è specificato solo column, l'elemento selezionato è una colonna.

Alcuni precisazioni:

  • 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 nell'implementazione setSelection.
  • Alcuni grafici potrebbero non attivare un evento "seleziona" e altri potrebbero supportare solo la selezione di una sola riga o dell'intera colonna. La documentazione di ogni grafico definisce gli eventi e i metodi supportati.
  • La selezione multipla viene gestita in modo diverso in grafici diversi (alcuni non lo consentono nemmeno).
  • Per leggere i dati selezionati, devi chiamare DataTable.getValue() nel tuo gestore; il modo più semplice per abilitarlo è rendere l'oggetto DataTable globale.

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

Tieni presente che il grafico a tabella attiva solo gli eventi di selezione di 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 che vengono chiamati al numero draw(), a indicare che il grafico viene visualizzato e pronto per restituire proprietà o gestire ulteriori chiamate di metodo. Devi sempre ascoltare l'evento pronto prima di provare a richiamare metodi su questo oggetto dopo aver chiamato draw().

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

  • L'evento pronto non trasmette alcuna proprietà al gestore (il gestore di funzioni non deve trasmettere alcun parametro al gestore).
  • Il grafico deve attivare l'evento Pronto dopo che il grafico è 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 e non solo quando il metodo draw termina.
  • L'aggiunta di un listener a questo evento deve essere effettuata prima di chiamare il metodo draw(), altrimenti l'evento potrebbe essere attivato prima della configurazione del listener e non verrà rilevato.
  • Se chiami i metodi di interazione prima dell'attivazione dell'evento pronto, rischi che questi metodi non funzionino correttamente.

La convenzione è che i grafici che non attivano un evento "pronto" sono pronti per l'interazione immediatamente dopo la fine del metodo draw e restituiscono il controllo all'utente. Se il grafico attiva un evento pronto, devi attendere che venga generato prima di richiamare i metodi su questo evento, come mostrato di seguito:

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

Sintassi del gestore di eventi pronto

function myReadyHandler(){...}

Il gestore di eventi pronto non viene passato ad alcun parametro.

L'evento error

I grafici dovrebbero generare un evento di errore quando si verificano errori di questo tipo per consentirti di gestirlo agevolmente. Il gestore di eventi trasmette una descrizione dell'errore, oltre alle proprietà degli eventi personalizzate specifiche di ogni 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 di goog.visualization.errors per mostrare eventuali errori agli utenti.

Sintassi del gestore di eventi di errore

function myErrorHandler(err){...}

Il gestore di eventi di errore deve trasmettere un oggetto con i seguenti membri:

  • id [Obbligatorio]: l'ID dell'elemento DOM contenente il grafico oppure un messaggio di errore visualizzato al posto del grafico se non può essere visualizzato.
  • messaggio [Obbligatorio] - Una breve stringa di messaggi che descrive l'errore.
  • detailedMessage [Facoltativo] - Una spiegazione dettagliata dell'errore.
  • opzioni [facoltativo]: un oggetto contenente parametri personalizzati appropriati per questo errore e 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 due 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 di seguito nelle righe della tabella o negli elementi del grafico per visualizzare la selezione in azione: