Eventi di attivazione

La visualizzazione può attivare eventi che una pagina host può registrare e ricevere. Gli eventi possono essere attivati dalle azioni dell'utente, ad esempio un utente fa clic su un grafico, o possono essere interni, ad esempio l'attivazione di un evento ogni 10 secondi. Puoi registrare un metodo JavaScript da chiamare ogni volta che vengono attivati determinati eventi, possibilmente con dati specifici dell'evento.

Ogni visualizzazione definisce i propri eventi e la relativa documentazione deve descrivere quando viene attivato ciascun evento, il relativo significato e le informazioni che invia al gestore di eventi (ad esempio, consulta la visualizzazione del grafico dell'organizzazione). Questa pagina descrive in che modo un creatore di visualizzazioni può attivare eventi. Per informazioni su come i client possono registrarsi per ricevere eventi, consulta la pagina Gestione degli eventi.

Esiste un solo evento in cui deve essere attivata qualsiasi visualizzazione selezionabile: l'evento select. Tuttavia, il comportamento e il significato di questo evento sono definiti da ogni visualizzazione.

Se una visualizzazione non è pronta per l'interazione subito dopo che il metodo draw ha restituito il controllo all'utente, dovrebbe attivarsi: l'evento pronto. Il comportamento e il significato esatti di questo evento sono definiti nella sezione Evento pronto.

È importante notare che gli eventi dell'API di visualizzazione sono separati e distinti da quelli DOM standard.

Contenuti

  1. Attivare un evento
  2. Seleziona l'evento
  3. Evento Ready
  4. Ulteriori informazioni

Attivare un evento

Per attivare un evento dalla visualizzazione, chiama la funzione google.visualization.events.trigger(). La funzione prevede i seguenti parametri:

  1. Visualizzazione sorgente (in genere si tratta del valore this).
  2. Nome dell'evento (stringa).
  3. Dettagli evento (oggetto). Una mappa facoltativa (nome/valore) dei dettagli di eventi specifici.

L'esempio seguente mostra in che modo una visualizzazione genera l'evento select: 

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

Le pagine di hosting possono registrarsi per ricevere i tuoi eventi chiamando il numero google.visualization.events.addListener() o google.visualization.events.addOneTimeListener(). Assicurati di documentare accuratamente tutti gli eventi che attivi.

L'evento di selezione

L'evento "select" è un evento standard generato da molte visualizzazioni in risposta al clic del mouse dell'utente. Se scegli di attivare un evento in risposta ai clic del mouse, devi implementare l'evento "select" nel modo standard descritto di seguito:

  1. Attiva un evento con il nome "select" quando l'utente seleziona alcuni dati nella visualizzazione. L'evento non invia argomenti alle funzioni di ascolto.
  2. Esponi il metodo getSelection() come descritto nella sezione dei documenti collegati. Questo metodo dovrebbe restituire gli indici degli elementi dati selezionati dall'utente.
  3. Esponi un metodo setSelection() come descritto nella sezione di riferimento. Per informazioni su come gestire gli eventi, consulta anche la pagina relativa alla gestione degli eventi.

Evento Ready

Qualsiasi visualizzazione dovrebbe attivare un evento "pronto" che funziona in modo standard per comunicare allo sviluppatore quando la visualizzazione è pronta per essere elaborata chiamati metodi. Tuttavia, non c'è un requisito assoluto che la visualizzazione si comporti in questo modo; consulta la documentazione per la visualizzazione.

In generale, le visualizzazioni che espongono l'evento "ready" sono progettate 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).
  • La visualizzazione deve attivare l'evento pronto quando è pronta per l'interazione. Se il disegno della visualizzazione è 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, corri il rischio che questi metodi non funzionino correttamente.

La convenzione prevede che le visualizzazioni che non attivano un evento "pronto" siano pronte per l'interazione subito dopo la fine del metodo draw e restituito il controllo all'utente.

Ulteriori informazioni