Processar eventos

Nesta página, descrevemos como detectar e processar eventos acionados por um gráfico.

Índice

  1. Visão geral
  2. Registrar e tratar de um evento
  3. Recuperar informações do evento
  4. Evento select
  5. O evento ready
  6. O evento error
  7. Exemplo de manipulação de eventos

Visão geral

Os gráficos do Google podem disparar eventos que você pode detectar. Os eventos podem ser acionados por ações do usuário, como o clique em um gráfico. É possível registrar um método JavaScript para ser chamado sempre que determinados eventos forem disparados, possivelmente com dados específicos desse evento.

Cada gráfico define os próprios eventos, e a documentação precisa descrever quando cada evento é disparado, o que ele significa e como recuperar informações associadas ao evento. Nesta página, descrevemos como se registrar para receber eventos de um gráfico e como lidar com eles.

Há um evento que qualquer gráfico selecionável precisa disparar: o evento select. No entanto, o comportamento e o significado desse evento são definidos por cada gráfico.

É importante observar que os eventos do gráfico são separados e distintos dos eventos padrão do DOM.

Como se inscrever e processar um evento

Para registrar seus manipuladores de eventos, chame google.visualization.events.addListener() ou addOneTimeListener() com o nome do gráfico que expõe o evento, o nome da string do evento que vai ser detectado e o nome da função a ser chamada quando o evento for disparado. A função precisa aceitar um único parâmetro que seja o evento acionado. Ele pode ter informações personalizadas sobre o evento, conforme descrito na documentação do gráfico.

Importante: se o gráfico expor um evento pronto, você sempre precisa esperar que ele seja disparado antes de tentar enviar métodos ou receber eventos do gráfico. Esses gráficos podem funcionar antes de lançar um evento pronto, mas esse comportamento não é garantido.

O snippet de código a seguir mostra uma caixa de alerta sempre que o usuário clica em uma linha da tabela:

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

Observe que isso só é registrado para detectar eventos desse objeto de tabela específico. Só é possível se registrar para receber eventos de um objeto específico.

Também é possível transmitir uma definição de função, como mostrado aqui:

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

Recuperar informações do evento

Geralmente, os eventos expõem informações de duas maneiras: pela transmissão de informações para a função de gerenciador como um parâmetro ou pela adição de informações a um objeto global. Se e como o evento expõe informações, devem ser descritos na documentação desse gráfico. Veja como recuperar os dois tipos de informação:

Informações de eventos transmitidas ao seu manipulador

Se o gráfico transmitir dados como um parâmetro para sua função de gerenciamento, você os recuperará conforme mostrado aqui:

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

O parâmetro transmitido ao gerenciador terá uma propriedade que precisa ser documentada para o gráfico. Veja um exemplo de gráfico com informações de eventos desta maneira na página Tabela.

Informações de eventos transmitidas para um objeto global

Em vez disso, alguns eventos alteram uma propriedade de um objeto global, que pode ser solicitada. Um exemplo comum disso é o evento "select", que é acionado quando um usuário seleciona uma parte de um gráfico. Nesse caso, o código precisa chamar getSelection() no gráfico para saber qual é a seleção atual. Mais informações são fornecidas sobre o evento selecionado abaixo.

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

Evento select

Como mencionado anteriormente, qualquer gráfico que pode ser selecionado precisa disparar um evento "select" que funciona de maneira padrão para permitir que você recupere os valores do item selecionado no gráfico. No entanto, não há um requisito absoluto para que um gráfico se comporte dessa maneira. Verifique a documentação dele.

Em geral, os gráficos que expõem o evento "select" são projetados com as seguintes especificações:

  • O evento de seleção não transmite propriedades ou objetos ao gerenciador. Seu gerenciador de funções não pode esperar que nenhum parâmetro seja transmitido para ele.
  • O gráfico precisa expor o método getSelection(), que retorna uma matriz de objetos que descrevem os elementos de dados selecionados. Esses objetos têm as propriedades row e column. row e column são os índices de linha e coluna do item selecionado em DataTable. Os eventos de seleção descrevem os dados subjacentes do gráfico, não os elementos HTML. Para receber os dados do item selecionado, chame DataTable.getValue() ou getFormattedValue().
    Se row e column forem especificados, o elemento selecionado será uma célula. Se apenas row for especificado, o elemento selecionado será uma linha. Se apenas column for especificado, o elemento selecionado será uma coluna.
  • O gráfico precisa expor o método setSelection(selection) para mudar a seleção na tabela subjacente e selecionar os dados correspondentes. O parâmetro selection é semelhante a uma matriz getSelection(), em que cada elemento é um objeto com as propriedades row e column. A propriedade row define o índice da linha selecionada em DataTable, e a propriedade column define o índice da coluna selecionada em DataTable. Quando esse método é chamado, o gráfico indica visualmente qual é a nova seleção. A implementação de setSelection() não pode acionar um evento "select".
    Se row e column forem especificados, o elemento selecionado será uma célula. Se apenas row for especificado, o elemento selecionado será uma linha. Se apenas column for especificado, o elemento selecionado será uma coluna.

Algumas ressalvas:

  • O gráfico pode ignorar parte da seleção. Por exemplo, uma tabela que pode mostrar apenas linhas selecionadas pode ignorar elementos de célula ou coluna na implementação de setSelection.
  • Alguns gráficos podem não acionar um evento "select" e outros gráficos são compatíveis apenas com seleção de linha inteira ou seleção de coluna inteira. A documentação de cada gráfico define os eventos e métodos compatíveis.
  • A seleção múltipla é processada de forma diferente em gráficos diferentes (alguns não permitem).
  • Para ler os dados selecionados, você precisará chamar DataTable.getValue() no gerenciador. A maneira mais simples de fazer isso é tornar o objeto DataTable global.

O exemplo a seguir exibe uma caixa de alerta com os elementos da tabela selecionados quando um elemento de um gráfico de tabela é selecionado:

O gráfico de tabelas dispara somente eventos de seleção de linha. No entanto, o código é genérico e pode ser usado para eventos de seleção de linha, coluna e célula.

Veja o código do gerenciador desse exemplo:

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

O evento ready

A maioria dos gráficos é renderizada de forma assíncrona. Todos os gráficos do Google geram um evento pronto depois que você chama draw() neles, indicando que o gráfico é renderizado e está pronto para retornar propriedades ou processar outras chamadas de método. Você sempre precisa detectar o evento pronto antes de tentar chamar métodos nele depois de chamar draw().

Em geral, os gráficos que expõem o evento "pronto" são projetados com as seguintes especificações:

  • O evento "ready" não transmite nenhuma propriedade ao gerenciador. Seu gerenciador de funções não pode esperar nenhum parâmetro ser transmitido a ele.
  • O gráfico precisa disparar o evento pronto depois que ele estiver pronto para interação. Se o desenho do gráfico for assíncrono, é importante que o evento seja acionado quando os métodos de interação puderem ser realmente 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(), porque, caso contrário, o evento será acionado antes da configuração do listener e você não o capturará.
  • Ao chamar métodos de interação antes que o evento pronto seja acionado, você corre o risco de que esses métodos não funcionem corretamente.

A convenção é que os gráficos que não disparam um evento "pronto" ficam prontos para interação imediatamente após o término do método draw e retornam o controle ao usuário. Se o gráfico disparar um evento pronto, aguarde até que ele seja gerado antes de chamar métodos nele, como mostrado abaixo:

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

Sintaxe do manipulador de eventos de "Pronto"

function myReadyHandler(){...}

O manipulador de eventos pronto não recebeu nenhum parâmetro.

O evento error

Os gráficos precisam gerar um evento de erro quando encontram algum tipo de erro para permitir que você o processe sem problemas. O manipulador de eventos recebe uma descrição do erro, bem como propriedades de evento personalizadas específicas para cada gráfico. Você deve se inscrever nesse evento logo depois de instanciar o gráfico para capturar os erros que podem ocorrer nas etapas posteriores.

Use as funções auxiliares goog.visualization.errors para exibir erros ao usuário.

Sintaxe do manipulador de eventos de erro

function myErrorHandler(err){...}

O manipulador de eventos de erro deve receber um objeto com os seguintes membros:

  • id [obrigatório]: o ID do elemento DOM que contém o gráfico ou uma mensagem de erro exibida em vez do gráfico se ele não puder ser renderizado.
  • message [Obrigatório]: uma string de mensagem curta que descreve o erro.
  • detailMessage [opcional]: uma explicação detalhada do erro.
  • options [opcional]: um objeto que contém parâmetros personalizados apropriados para este erro e tipo de gráfico.

Exemplo de manipulação de eventos

O exemplo a seguir demonstra getSelection() e setSelection(). Ele sincroniza a seleção entre dois gráficos que usam a mesma tabela de dados. Clique em um deles para sincronizar a seleção no outro.

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

Clique nos gráficos abaixo nas linhas da tabela ou nos elementos do gráfico para ver a seleção em ação: