Eventi di attivazione

La visualizzazione può attivare eventi che una pagina host può registrare a ricevere. Gli eventi possono essere attivati dalle azioni dell'utente, ad esempio un utente fa clic su un grafico, oppure 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 per quell'evento.

Ogni visualizzazione definisce i propri eventi e la relativa documentazione dovrebbe descrivere quando viene attivato ogni evento, il suo significato e le informazioni che invia al gestore degli eventi (ad esempio, consulta la visualizzazione dell'organigramma). Questa pagina descrive in che modo un creatore della visualizzazione può attivare gli eventi. Per informazioni su come i clienti possono registrarsi per ricevere eventi, consulta la pagina Gestione degli eventi.

C'è un evento che deve essere attivato da qualsiasi visualizzazione selezionabile: l'evento selezionato. 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 restituisce il controllo all'utente, la visualizzazione deve attivarsi: l'evento è pronto. Il comportamento e il significato esatti di questo evento sono definiti nella sezione The Ready Event (L'evento pronto).

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

Contenuti

  1. Attivare un evento
  2. Seleziona l'evento
  3. L'evento Tutto pronto
  4. Scopri di più

Attivare un evento

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

  1. Visualizzazione di origine (generalmente è il valore this).
  2. Nome evento (stringa).
  3. Dettagli dell'evento (oggetto). Una mappa facoltativa (nome/valore) dei dettagli di eventi specifici.

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

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 google.visualization.events.addListener() o google.visualization.events.addOneTimeListener(). Assicurati di documentare accuratamente tutti gli eventi che hai attivato.

Seleziona evento

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

  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 del documento collegato. Questo metodo dovrebbe restituire gli indici degli elementi data selezionati dall'utente.
  3. Esponi un metodo setSelection() come descritto nella sezione riferimento. Per informazioni su come gestire gli eventi, consulta anche la pagina relativa agli eventi di gestione.

L'evento pronto

Qualsiasi visualizzazione dovrebbe attivare un evento "pronto" che funzioni in modo standard per informare lo sviluppatore quando la visualizzazione è pronta per l'elaborazione, chiamata metodo. Tuttavia, non esiste requisito assoluto che una visualizzazione comporti questo comportamento; consulta la documentazione per la visualizzazione.

In generale, le visualizzazioni che espongono l'evento "Ready" sono progettate con le seguenti specifiche:

  • L'evento pronto non trasmette alcuna proprietà al gestore (il gestore di funzioni non deve trasmettere alcun parametro al gestore).
  • La visualizzazione deve attivare l'evento pronto dopo che la visualizzazione è 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 e non solo quando termina il metodo draw.
  • 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 di non funzionare correttamente.

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

Scopri di più