Eventos de disparo

Sua visualização pode disparar eventos que uma página host pode registrar para receber. Os eventos podem ser acionados por ações do usuário (por exemplo, um usuário clica em um gráfico) ou podem ser internos (por exemplo, disparar um evento a cada 10 segundos). Você pode registrar um método JavaScript para ser chamado sempre que determinados eventos forem disparados, possivelmente com dados específicos desse evento.

Cada visualização define os próprios eventos, e a documentação dessa visualização deve descrever quando cada evento é disparado, o que ele significa e quais informações ele envia ao manipulador de eventos (por exemplo, consulte a visualização do organograma). Nesta página, descrevemos como um criador de visualizações pode disparar eventos. Para saber como os clientes podem se registrar para receber eventos, consulte a página Como processar eventos.

Há um evento que qualquer visualização selecionável deve disparar: o evento select. No entanto, cada visualização define o comportamento e o significado desse evento.

Se uma visualização não estiver pronta para interação imediatamente após o método draw retornar o controle ao usuário, ela precisará ser disparada: o evento "pronta". O comportamento e significado exatos desse evento são definidos na seção Evento pronto.

Os eventos da API de visualização são separados e diferentes dos eventos DOM padrão.

Conteúdo

  1. Como disparar um evento
  2. O evento "Selecionar"
  3. O evento "Pronto"
  4. Mais informações

Como disparar um evento

Para disparar um evento da sua visualização, chame a função google.visualization.events.trigger(). A função espera receber os parâmetros abaixo:

  1. Visualização de origem (normalmente o valor this).
  2. Nome do evento (string).
  3. Detalhes do evento (objeto). Um mapa opcional (nome/valor) de detalhes específicos do evento.

O exemplo a seguir mostra como uma visualização gera o 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', {});
};

As páginas do Hosting podem se registrar para receber seus eventos chamando google.visualization.events.addListener() ou google.visualization.events.addOneTimeListener(). Documente minuciosamente todos os eventos que você disparar.

O evento "Selecionar"

O evento "select" é um evento padrão gerado por muitas visualizações em resposta a um clique do mouse do usuário. Se você optar por disparar um evento em resposta a cliques do mouse, implemente o evento "select" da maneira padrão descrita aqui:

  1. Disparar um evento com o nome 'select' quando o usuário selecionar alguns dados na visualização. O evento não envia argumentos para as funções de detecção.
  2. Exponha o método getSelection() conforme descrito na seção do documento vinculado. Esse método retorna os índices de elementos de data selecionados pelo usuário.
  3. Exponha um método setSelection() conforme descrito na seção de referência. Consulte também a página Como gerenciar eventos para saber como fazer isso.

O evento "Pronto"

Qualquer visualização precisa disparar um evento "ready" que funcione de maneira padrão para informar ao desenvolvedor quando a visualização está pronta para ser processada com os métodos chamados. No entanto, não há requisito absoluto que uma visualização se comporte dessa maneira. Verifique a documentação da sua visualização.

Em geral, as visualizações que expõem o evento "ready" têm estas especificações:

  • O evento "ready" não transmite propriedades ao gerenciador (seu gerenciador de funções não deve esperar que nenhum parâmetro seja transmitido a ele).
  • A visualização precisa disparar o evento pronto depois que estiver pronta para interação. Se o desenho da visualização for assíncrono, é importante que o evento seja disparado quando os métodos de interação puderem ser chamados, e não apenas quando o método draw terminar.
  • É necessário adicionar um listener a esse evento antes de chamar o método draw. Caso contrário, o evento poderá ser disparado antes da configuração do listener e você não o detectará.
  • Ao chamar métodos de interação antes que o evento "ready" seja disparado, você corre o risco de que esses métodos não funcionem corretamente.

A convenção é que as visualizações que não disparam um evento "ready" estejam prontas para interação imediatamente após o término do método draw e o retorno do controle ao usuário.

Mais informações