Processar eventos

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

Conteúdo

  1. Visão geral
  2. Como se inscrever e processar um evento
  3. Como recuperar informações de eventos
  4. O 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 clicar em um gráfico. Você pode 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 desse gráfico deve descrever quando cada evento é disparado, o que ele significa e como recuperar todas as informações associadas ao evento. Nesta página, descrevemos como se registrar para receber eventos de um gráfico e como processá-los.

Há um evento que qualquer gráfico selecionável deve 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 diferentes dos eventos DOM padrão.

Como se inscrever e processar um evento

Para registrar os 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 a ser detectado e o nome da função a ser chamada quando esse evento é disparado. A função precisa aceitar um único parâmetro que seja o evento disparado. Esse evento pode ter informações personalizadas sobre o evento, conforme descrito na documentação do gráfico.

Importante:se o gráfico expõe um evento pronto, aguarde sempre que esse evento seja disparado antes de tentar enviar métodos ou receber eventos do gráfico. Esses gráficos podem funcionar antes de gerar 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');
}

Isso só será 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, conforme mostrado aqui:

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

Como recuperar informações de eventos

Os eventos geralmente expõem informações de duas maneiras: transmitindo informações para a função do gerenciador como um parâmetro ou adicionando informações a um objeto global. Se e como o evento expõe informações, deve ser descrito na documentação desse gráfico. Veja como recuperar os dois tipos de informações:

Informações de eventos transmitidas para o gerenciador

Se o gráfico transmitir dados como um parâmetro para a função de tratamento, será preciso recuperá-los 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 passado para o gerenciador terá uma propriedade que precisará ser documentada para o gráfico. Para conferir um exemplo de gráfico que expõe informações de evento dessa maneira, consulte o evento de página do gráfico da Tabela.

Informações do evento transmitidas para um objeto global

Em vez disso, alguns eventos alteram uma propriedade de um objeto global, que você pode solicitar. Um exemplo comum disso é o evento "select", que é disparado 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. Veja mais informações sobre o evento de seleção 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.');

O evento select

Como mencionado anteriormente, qualquer gráfico que possa ser selecionado precisa disparar um evento "select" que funcione 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" têm estas especificações:

  • O evento select não transmite propriedades ou objetos ao gerenciador (seu gerenciador de funções não deve esperar que nenhum parâmetro seja passado a 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 no gráfico, e não os elementos HTML no gráfico. 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 alterar a seleção na tabela subjacente e selecionar os dados correspondentes nela. O parâmetro selection, que é uma matriz semelhante à 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 precisa indicar 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 mostra 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 podem oferecer suporte apenas à seleção de linhas inteiras ou a toda a coluna. A documentação de cada gráfico define os eventos e métodos compatíveis.
  • A multisseleção é tratada de maneira diferente em gráficos diferentes (alguns nem permitem).
  • Para ler os dados selecionados, você precisa chamar DataTable.getValue() no seu gerenciador. A maneira mais simples de ativar isso é tornar o objeto DataTable global.

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

O gráfico de tabela só dispara 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 para esse 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 maneira assíncrona. Todos os gráficos do Google geram um evento pronto depois que você chama draw() neles, indicando que o gráfico foi renderizado e está pronto para retornar propriedades ou processar outras chamadas de método. Sempre detecte o evento "ready" antes de tentar chamar métodos nele depois de chamar draw().

Em geral, os gráficos 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).
  • O gráfico precisa disparar o evento pronto para interação. Se o desenho do gráfico 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 pronto seja disparado, 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 "ready" estejam prontos para interação imediatamente após o término do método draw e o retorno do controle ao usuário. Se o gráfico disparar um evento pronto, aguarde até que ele seja lançado antes de chamar métodos nele, conforme mostrado aqui:

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

Sintaxe do manipulador de eventos pronto

function myReadyHandler(){...}

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

O evento error

Os gráficos precisam gerar um evento de erro quando encontram algum tipo de erro para que você possa lidar com isso sem problemas. O manipulador de eventos recebe uma descrição do erro, bem como propriedades de eventos personalizados específicas de cada gráfico. Inscreva-se nesse evento logo após instanciar o gráfico para detectar erros que possam ocorrer nas etapas posteriores.

Use as funções auxiliares goog.visualization.errors para mostrar os erros corretamente 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 no lugar do gráfico se ele não puder ser renderizado.
  • message [obrigatório]: uma string de mensagem curta que descreve o erro.
  • detailedMessage [opcional]: uma explicação detalhada do erro.
  • options [opcional]: um objeto que contém parâmetros personalizados apropriados para esse 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 dos gráficos para sincronizar a seleção no outro gráfico.

// 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: