Referência da API de visualização do Google

Nesta página, listamos os objetos expostos pela API Google Visualization e os métodos padrão expostos por todas as visualizações.

Observação:o namespace da API de visualização do Google é google.visualization.*

Classe DataTable

Representa uma tabela de valores bidimensional e mutável. Para fazer uma cópia somente leitura de um DataTable (opcionalmente filtrado para mostrar valores, linhas ou colunas específicos), crie um DataView.

Cada coluna recebe um tipo de dados e várias propriedades opcionais, incluindo ID, rótulo e string de padrão.

Além disso, é possível atribuir propriedades personalizadas (pares de nome/valor) a qualquer célula, linha, coluna ou à tabela inteira. Algumas visualizações aceitam propriedades personalizadas específicas. Por exemplo, a visualização de tabela aceita uma propriedade de célula chamada "style", que permite atribuir uma string de estilo CSS in-line à célula da tabela renderizada. Uma visualização precisa descrever na documentação todas as propriedades personalizadas compatíveis.

Consulte também: QueryResponse.getDataTable

Construtor

Sintaxe

DataTable(opt_data, opt_version)

opt_data

[Opcional] Dados usados para inicializar a tabela. Pode ser o JSON retornado chamando DataTable.toJSON() em uma tabela preenchida ou um objeto JavaScript que contém dados usados para inicializar a tabela. A estrutura do objeto literal JavaScript é descrita aqui. Se esse parâmetro não for fornecido, uma nova tabela de dados vazia será retornada.

opt_version

[Opcional] Um valor numérico que especifica a versão do protocolo de transferência usado. Usado apenas por implementadores de fontes de dados de ferramentas de gráficos. A versão atual é 0.6.

Detalhes

O objeto DataTable é usado para armazenar os dados transmitidos em uma visualização. Uma DataTable é uma tabela bidimensional básica. Todos os dados em cada coluna precisam ter o mesmo tipo de dados. Cada coluna tem um descritor que inclui o tipo de dados, um rótulo para essa coluna (que pode ser exibido por uma visualização) e um ID, que pode ser usado para se referir a uma coluna específica (como alternativa ao uso de índices de coluna). O objeto DataTable também é compatível com um mapa de propriedades arbitrárias atribuídas a um valor específico, uma linha, uma coluna ou todo o DataTable. As visualizações podem usá-las para auxiliar recursos adicionais. Por exemplo, a visualização de tabela usa propriedades personalizadas para permitir que você atribua nomes ou estilos de classe arbitrários a células individuais.

Cada célula da tabela tem um valor. As células podem ter um valor nulo ou do tipo especificado pela coluna. Opcionalmente, as células podem ter uma versão "formatada" dos dados. Trata-se de uma versão em string dos dados, formatada para exibição por uma visualização. Uma visualização pode usar (mas não é obrigatório) a versão formatada para exibição, mas sempre usará os próprios dados para classificações ou cálculos feitos (como determinar em que parte de um gráfico colocar um ponto). Um exemplo pode ser atribuir os valores "baixo", "médio" e "alto" como valores formatados a valores numéricos de célula de 1, 2 e 3.

Para adicionar linhas de dados depois de chamar o construtor, você pode chamar addRow() para uma única linha ou addRows() para várias linhas. Também é possível adicionar colunas chamando os métodos addColumn(). Também existem métodos de remoção para linhas e colunas, mas, em vez de remover linhas ou colunas, crie uma DataView que seja uma visualização seletiva da DataTable.

Se você alterar valores em um DataTable depois de ele ser transmitido para o método draw() de uma visualização, as mudanças não mudarão imediatamente o gráfico. Chame draw() novamente para refletir as mudanças.

Observação: o Google Charts não executa nenhuma validação em tabelas de dados. Nesse caso, a renderização dos gráficos ficaria mais lenta. Se você fornecer um número em que sua coluna esteja esperando uma string, ou vice-versa, o Gráficos Google fará o seu melhor para interpretar o valor de uma forma que faça sentido, mas não sinalizará erros.

O exemplo a seguir demonstra como instanciar e preencher um DataTable com uma string literal, com os mesmos dados mostrados no exemplo de JavaScript acima:

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

O exemplo a seguir cria um novo DataTable vazio e o preenche manualmente com os mesmos dados acima:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

Métodos

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

Formato do parâmetro literal JavaScript data do construtor

Você pode inicializar um DataTable transmitindo um objeto literal de string JavaScript para o parâmetro data. Vamos chamar esse objeto de data. É possível codificar esse objeto manualmente, de acordo com a descrição abaixo, ou usar uma biblioteca auxiliar de Python se você souber e seu site puder usá-la. No entanto, se você quiser construir o objeto manualmente, esta seção descreverá a sintaxe.

Primeiro, vamos mostrar um exemplo de um objeto JavaScript simples que descreve uma tabela com três linhas e três colunas (tipos String, Number e Date):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

Agora vamos descrever a sintaxe:

O objeto data consiste em duas propriedades de nível superior obrigatórias, cols e rows, e uma propriedade p opcional que é um mapa de valores arbitrários.

Observação:todos os nomes de propriedades e constantes de string mostrados diferenciam maiúsculas de minúsculas. Além disso, as propriedades descritas como tendo um valor de string precisam ter o valor entre aspas. Por exemplo, se você quiser especificar a propriedade "type" como número, ela será expressa da seguinte maneira: type: 'number', mas o valor em si, como numérico, seria expresso assim: v: 42

Propriedade cols

cols é uma matriz de objetos que descrevem o ID e o tipo de cada coluna. Cada propriedade é um objeto com as seguintes propriedades (diferencia maiúsculas de minúsculas):

• type [Obrigatório] Tipo de dados dos dados na coluna. Oferece suporte aos seguintes valores de string (exemplos incluem a propriedade v: descrita posteriormente):
  • "boolean" - valor booleano do JavaScript ("true" ou "false"). Exemplo de valor: v:'true'
  • "number" - valor do número JavaScript. Exemplos de valores: v:7, v:3.14, v:-55
  • "string" - valor da string JavaScript. Exemplo de valor: v:'hello'
  • "date" - objeto de data JavaScript (mês zero), com a hora truncada. Exemplo de valor: v:new Date(2008, 0, 15)
  • "datetime" - objeto de data JavaScript incluindo a hora. Exemplo de valor: v:new Date(2008, 0, 15, 14, 30, 45)
  • "timeofday": matriz de três números e um quarto opcional, representando hora (0 indica meia-noite), minuto, segundo e milissegundo opcional. Exemplos de valores: v:[8, 15, 0], v: [6, 12, 1, 144]
• id [opcional] ID da string da coluna. Precisa ser exclusivo na tabela. Use caracteres alfanuméricos básicos para que a página não precise de escapes complicados para acessar a coluna em JavaScript. Tenha cuidado para não escolher uma palavra-chave JavaScript. Exemplo: id:'col_1'
• label [Opcional] Valor de string que algumas visualizações exibem para esta coluna. Exemplo: label:'Height'
• pattern [Opcional] Padrão de string que foi usado por uma fonte de dados para formatar valores de coluna numéricos, de data ou de hora. Isso é apenas para referência. Você provavelmente não precisará ler o padrão, e ele não precisa existir. O cliente da visualização do Google não usa esse valor (ele lê o valor formatado da célula). Se DataTable vier de uma fonte de dados em resposta a uma consulta com uma cláusula format, o padrão especificado nessa cláusula provavelmente será retornado nesse valor. Os padrões de padrão recomendados são a ICU DecimalFormat e SimpleDateFormat .
• p [Opcional] Um objeto que é um mapa de valores personalizados aplicados à célula. Esses valores podem ser de qualquer tipo JavaScript. Se a visualização for compatível com propriedades no nível da célula, elas serão descritas. Caso contrário, essa propriedade será ignorada. Exemplo:p:{style: 'border: 1px solid green;'}.

Exemplo do cols

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

Propriedade do rows

A propriedade rows contém uma matriz de objetos de linha.

Cada objeto de linha tem uma propriedade obrigatória chamada c, que é uma matriz de células nessa linha. Ele também tem uma propriedade p opcional que define um mapa de valores personalizados arbitrários a serem atribuídos à linha inteira. Se a visualização for compatível com propriedades no nível da linha, elas serão descritas. Caso contrário, essa propriedade será ignorada.

Objetos Células

Cada célula na tabela é descrita por um objeto com as seguintes propriedades:

• v [opcional] é o valor da célula. O tipo de dados precisa corresponder ao da coluna. Se a célula for nula, a propriedade v precisará ser nula, mas ainda poderá ter propriedades f e p.
• f [Opcional] Uma versão de string do valor v, formatada para exibição. Normalmente, os valores serão correspondentes, embora isso não seja necessário. Portanto, se você especificar Date(2008, 0, 1) para v, especifique "1o de janeiro de 2008" ou alguma string semelhante para essa propriedade. Esse valor não é comparado com o valor v. A visualização não vai usar esse valor para cálculo, apenas como um rótulo para exibição. Se omitido, uma versão de string de v será gerada automaticamente usando o formatador padrão. Os valores f podem ser modificados usando seu próprio formatador, definidos com setFormattedValue() ou setCell() ou recuperados com getFormattedValue().
• p [Opcional] Um objeto que é um mapa de valores personalizados aplicados à célula. Esses valores podem ser de qualquer tipo JavaScript. Se a visualização aceitar qualquer propriedade no nível da célula, ela vai descrevê-la. Essas propriedades podem ser recuperadas pelos métodos getProperty() e getProperties(). Exemplo: p:{style: 'border: 1px solid green;'}.

As células na matriz de linhas precisam estar na mesma ordem das descrições das colunas em cols. Para indicar uma célula nula, especifique null, deixe uma célula em branco em uma célula ou omita os membros à direita da matriz. Portanto, para indicar uma linha com nulo para as duas primeiras células, você pode especificar [ , , {cell_val}] ou [null, null, {cell_val}].

Aqui está um objeto de tabela de exemplo com três colunas, preenchidas com três linhas de dados:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

Propriedade p

A propriedade p no nível da tabela é um mapa de valores personalizados aplicado a toda a DataTable. Esses valores podem ser de qualquer tipo JavaScript. Se a visualização for compatível com quaisquer propriedades no nível da tabela de dados, elas serão descritas. Caso contrário, essa propriedade estará disponível para uso do aplicativo. Exemplo: p:{className: 'myDataTable'}.

Classe DataView

Uma visualização somente leitura de um DataTable subjacente. Um DataView permite a seleção de apenas um subconjunto de colunas e/ou linhas. Ele também permite reordenar colunas/linhas e duplicar colunas/linhas.

Uma visualização é uma janela em tempo real na DataTable subjacente, não um snapshot estático dos dados. No entanto, você ainda precisa ter cuidado ao alterar a estrutura da própria tabela, conforme descrito aqui:

• A adição ou remoção de colunas da tabela não é refletida na visualização e pode causar um comportamento inesperado nela. Será necessário criar uma nova DataView no DataTable para capturar essas mudanças.
• Adicionar ou remover linhas da tabela subjacente é seguro, e as alterações serão propagadas para a visualização imediatamente. No entanto, é necessário chamar draw() em qualquer visualização após essa alteração para que o novo conjunto de linhas seja renderizado. Se a visualização tiver filtrado linhas chamando um dos métodos setRows() or hideRows(), e você adicionar ou remover linhas da tabela subjacente, o comportamento será inesperado. Será necessário criar um novo DataView para refletir a nova tabela.
• Alterar os valores de célula nas células existentes é seguro, e as alterações são imediatamente propagadas para DataView. No entanto, é necessário chamar draw() em qualquer visualização após essa alteração para que os novos valores de célula sejam renderizados.

Também é possível criar uma DataView usando outra DataView. Sempre que uma tabela ou visualização subjacente é mencionada, ela se refere ao nível imediatamente abaixo desse nível. Em outras palavras, ele se refere ao objeto de dados usado para construir esse DataView.

DataView também aceita colunas calculadas, que têm o valor calculado rapidamente usando uma função que você fornece. Por exemplo, você pode incluir uma coluna que seja a soma de duas colunas anteriores ou uma coluna que calcule e mostre o trimestre de uma data de outra coluna. Consulte setColumns() para mais detalhes.

Quando você oculta ou mostra linhas ou colunas para modificar um DataView, a visualização não é afetada até que você chame draw() na visualização novamente.

Você pode combinar DataView.getFilteredRows() com DataView.setRows() para criar um DataView com um subconjunto interessante de dados, como mostrado aqui:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

Construtores

Há duas maneiras de criar uma nova instância de DataView:

Construtor 1

var myView = new google.visualization.DataView(data)

data

Uma DataTable ou DataView usada para inicializar a visualização. Por padrão, a visualização contém todas as colunas e linhas na tabela ou visualização de dados subjacente, na ordem original. Para ocultar ou mostrar linhas ou colunas nessa visualização, chame os métodos apropriados set...() ou hide...().

Confira também:

setColumns(), hideColumns(), setRows(), hideRows().

Construtor 2

Este construtor cria um novo DataView atribuindo um DataView serializado a um DataTable. Ele ajuda a recriar o DataView que você serializado usando DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

dados

O objeto DataTable usado para criar a DataView e em que você chamou DataView.toJSON(). Se essa tabela for diferente da original, você terá resultados imprevisíveis.

viewAsJson

A string JSON retornada por DataView.toJSON(). Esta é uma descrição de quais linhas mostrar ou ocultar na tabela de dados data.

Métodos

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

Classe ChartWrapper

Uma classe ChartWrapper é usada para unir o gráfico e processar todas as consultas de carregamento, desenho e fonte de dados do gráfico. A classe expõe métodos de conveniência para definir valores no gráfico e desenhá-lo. Essa classe simplifica a leitura de uma fonte de dados, porque não é necessário criar um gerenciador de callback de consulta. Também é possível usá-lo para salvar um gráfico facilmente para reutilização.

Outra vantagem de usar ChartWrapper é que você pode reduzir o número de carregamentos de biblioteca usando o carregamento dinâmico. Além disso, não é necessário carregar os pacotes explicitamente, já que o ChartWrapper processará a busca e o carregamento dos pacotes de gráficos para você. Confira mais detalhes nos exemplos abaixo.

No entanto, ChartWrapper atualmente propaga apenas um subconjunto de eventos gerados por gráficos: select, Ready e error. Outros eventos não são transmitidos pela instância do ChartWrapper. Para acessar outros eventos, chame getChart() e se inscreva nos eventos diretamente no identificador do gráfico, como mostrado aqui:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

Construtor

ChartWrapper(opt_spec)

opt_spec

[Opcional]: um objeto JSON que define o gráfico ou uma versão de string serializada desse objeto. O formato desse objeto é mostrado na documentação dodrawChart(). Se não for especificado, você precisará definir todas as propriedades apropriadas usando os métodos set... expostos por esse objeto.

Métodos

ChartWrapper expõe os seguintes métodos adicionais:

Eventos

O objeto ChartWrapper lança os seguintes eventos. É necessário chamar ChartWrapper.draw() antes que qualquer evento seja gerado.

Exemplo

Os dois snippets a seguir criam um gráfico de linhas equivalente. O primeiro exemplo usa a notação literal JSON para definir o gráfico. O segundo usa métodos ChartWrapper para definir esses valores.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

O mesmo gráfico, agora usando métodos setter:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

Classe do ChartEditor

A classe ChartEditor é usada para abrir uma caixa de diálogo in-page que permite que um usuário personalize uma visualização rapidamente.

Para usar o ChartEditor:

1. Carregue o pacote charteditor. Em google.charts.load(), carregue o pacote 'charteditor'. Você não precisa carregar os pacotes para o tipo de gráfico renderizado no editor. O editor de gráficos carregará qualquer pacote para você, conforme necessário.
2. Crie um objeto ChartWrapper que defina o gráfico para o usuário personalizar. Esse gráfico será exibido na caixa de diálogo, e o usuário usará o editor para reprojetar o gráfico, alterar os tipos de gráfico ou até mesmo alterar os dados de origem.
3. Crie uma nova instância do ChartEditor e registre-se para detectar o evento "ok". Esse evento é lançado quando o usuário clica no botão "OK" da caixa de diálogo. Quando recebido, chame ChartEditor.getChartWrapper() para recuperar o gráfico modificado pelo usuário.
4. Chame ChartEditor.openDialog(), transmitindo o ChartWrapper. A caixa de diálogo será aberta. Os botões da caixa de diálogo permitem que o usuário feche o editor. A instância ChartEditor fica disponível enquanto estiver no escopo. Ela não é destruída automaticamente depois que o usuário fecha a caixa de diálogo.
5. Para atualizar o gráfico no código, chame setChartWrapper().

Métodos

Opções

O editor de gráficos é compatível com as seguintes opções:

Eventos

O editor de gráficos gera os seguintes eventos:

Exemplo

O código de exemplo a seguir abre uma caixa de diálogo do editor de gráficos com um gráfico de linhas preenchido. Se o usuário clicar em "OK", o gráfico editado será salvo no <div> especificado na página.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

Métodos de manipulação de dados

O namespace google.visualization.data contém métodos estáticos para executar operações semelhantes a SQL em objetos DataTable, por exemplo, juntando-os ou agrupando por valor da coluna.

O namespace google.visualization.data expõe os seguintes métodos:

group()

Toma um objeto DataTable preenchido e executa uma operação GROUP BY semelhante a SQL, retornando uma tabela com linhas agrupadas pelos valores de coluna especificados. Isso não modifica a entrada DataTable.

A tabela retornada inclui uma linha para cada combinação de valores nas colunas-chave especificadas. Cada linha inclui as colunas de chave mais uma coluna com um valor de coluna agregado em todas as linhas que correspondem à combinação de chaves (por exemplo, uma soma ou contagem de todos os valores na coluna especificada).

O namespace google.visualization.data inclui vários valores de agregação úteis (por exemplo, sum e count), mas é possível definir seus próprios valores (por exemplo, standardDeviation ou secondHighest). As instruções sobre como definir seu próprio agregador são fornecidas após a descrição do método.

Sintaxe

google.visualization.data.group(data_table, keys, columns)

data_table

A entrada DataTable. Ele não será modificado chamando group().

keys

Uma matriz de números e/ou objetos que especifica as colunas que serão agrupadas. A tabela de resultados inclui todas as colunas nessa matriz, bem como todas as colunas em colunas. Se for um número, será um índice de colunas da entrada DataTable para agrupar. Se for um objeto, ele incluirá uma função que pode modificar a coluna especificada (por exemplo, adicionar 1 ao valor nessa coluna). O objeto precisa ter as seguintes propriedades:

• column: um número que é um índice de coluna de dt ao qual aplicar a transformação.
• modifier: uma função que aceita um valor (o valor da célula nessa coluna para cada linha) e retorna o valor modificado. Essa função é usada para modificar o valor da coluna para ajudar no agrupamento: por exemplo, chamando uma função qualQuarter que calcula um trimestre a partir de uma coluna de data, para que a API possa agrupar linhas por trimestre. O valor calculado é exibido nas colunas de chave na tabela retornada. Essa função pode ser declarada inline dentro desse objeto ou pode ser uma função que você define em outro lugar no código. Ela precisa estar dentro do escopo da chamada. A API oferece uma função modificadora simples. Confira estas instruções sobre como criar suas próprias funções mais úteis. Você precisa saber o tipo de dados que essa função pode aceitar e chamá-lo apenas em colunas desse tipo. Também é preciso saber o tipo de retorno dessa função e declará-lo na propriedade type descrita a seguir.
• type: o tipo retornado pela função modifier. Precisa ser um nome de tipo de string JavaScript, por exemplo: "número" ou "booleano".
• label: [opcional] um rótulo de string para atribuir essa coluna no DataTable retornado.
• id [opcional]: um ID de string para atribuir essa coluna no DataTable retornado.

Exemplos: [0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

colunas

[Opcional] Permite especificar quais colunas, além das colunas de chave, serão incluídas na tabela de saída. Como todas as linhas no grupo são compactadas em uma única linha de saída, é preciso determinar o valor a ser exibido para esse grupo. Por exemplo, é possível mostrar o valor da coluna da primeira linha do conjunto ou uma média de todas as linhas desse grupo. columns é uma matriz de objetos com as seguintes propriedades:

• coluna: um número que especifica o índice da coluna a ser exibida.
• aggregation: uma função que aceita uma matriz de todos os valores dessa coluna nesse grupo de linhas e retorna um único valor a ser exibido na linha de resultados. O valor de retorno precisa ser do tipo especificado pela propriedade type do objeto. Confira abaixo detalhes sobre como criar sua própria função de agregação. Você precisa saber quais tipos de dados esse método aceita e chamá-lo apenas em colunas do tipo apropriado. Ela oferece várias funções de agregação úteis. Consulte Funções de agregação fornecidas abaixo para ver uma lista ou Como criar uma função de agregação para saber como criar sua própria função de agregação.
• type: o tipo de retorno da função de agregação. Precisa ser um nome de tipo de string JavaScript, por exemplo: "número" ou "booleano".
• label: [opcional] um rótulo de string para aplicar a esta coluna na tabela retornada.
• id - [Opcional] Um ID de string a ser aplicado a essa coluna na tabela retornada.

Valor de retorno

Um DataTable com uma coluna para cada coluna listada em chaves e uma coluna para cada coluna listada em colunas. A tabela é classificada por linhas principais, da esquerda para a direita.

Exemplo

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

Funções modificadoras fornecidas

A API oferece as funções modificadoras abaixo que podem ser transmitidas para keys. modifier para personalizar o comportamento de agrupamento.

Funções de agregação fornecidas

A API oferece as funções de agregação abaixo, que podem ser transmitidas para as colunas. aggregation do parâmetro.

Como criar uma função modificadora

É possível criar uma função modificadora para executar uma transformação simples em valores de chave antes que a função group() agrupe as linhas. Essa função usa um único valor de célula, executa uma ação nele (por exemplo, adiciona 1 ao valor) e o retorna. Os tipos de entrada e retorno não precisam ser do mesmo tipo, mas o autor da chamada precisa conhecer os tipos de entrada e saída. Veja um exemplo de função que aceita uma data e retorna o trimestre:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

Como criar uma função de agregação

É possível criar uma função de agregação que aceite um conjunto de valores de coluna em um grupo de linhas e retorne um único número: por exemplo, retornando uma contagem ou média de valores. Veja a seguir uma implementação da função de agregação de contagem fornecida, que retorna uma contagem de quantas linhas há no grupo de linhas:

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

Esse método mescla duas tabelas de dados (objetos DataTable ou DataView) em uma única tabela de resultados, semelhante a uma instrução SQL JOIN. Você especifica um ou mais pares de colunas (colunas key) entre as duas tabelas, e a tabela de saída inclui as linhas de acordo com um método de mesclagem especificado: somente linhas com correspondência de ambas as chaves, todas as linhas de uma tabela ou todas as linhas de ambas, independentemente de as chaves corresponderem ou não. A tabela de resultados inclui apenas as colunas de chave, mais as outras que você especificar. Observe que dt2 não pode ter chaves duplicadas, mas dt1 pode. O termo "chave" significa a combinação de todos os valores de coluna de chave, não um valor de coluna de chave específico. Portanto, se uma linha tiver valores de célula A | B | C e as colunas 0 e 1 forem colunas-chave, a chave para essa linha será AB.

Sintaxe

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

Uma DataTable preenchida para mesclar com dt2.

dt2

Um DataTable preenchido para mesclar com dt1. Essa tabela não pode ter várias chaves idênticas (quando uma chave é uma combinação de valores de colunas-chave).

joinMethod

Uma string que especifica o tipo de mesclagem. Se dt1 tiver várias linhas que correspondam a uma dt2, a tabela de saída incluirá todas as linhas dt1 correspondentes. Escolha entre estes valores:

• "full": a tabela de saída inclui todas as linhas das duas tabelas, independentemente da correspondência das chaves. As linhas sem correspondência terão entradas de célula nulas, e as linhas correspondentes serão mescladas.
• "inner" - a junção completa filtrada para incluir apenas as linhas em que as chaves são correspondentes.
• "left": a tabela de saída inclui todas as linhas de dt1, independentemente de haver ou não linhas correspondentes de dt2.
• "right" - A tabela de saída inclui todas as linhas de dt2, independentemente de haver ou não linhas correspondentes de dt1.

keys

Uma matriz de colunas de chave a serem comparadas nas duas tabelas. Cada par é uma matriz de dois elementos. O primeiro é uma chave em dt1 e o segundo é uma chave em dt2. Essa matriz pode especificar colunas por índice, ID ou rótulo. Consulte getColumnIndex.
As colunas precisam ser do mesmo tipo nas duas tabelas. Todas as chaves especificadas precisam corresponder de acordo com a regra fornecida por joinMethod para incluir uma linha da tabela. As colunas de chave são sempre incluídas na tabela de saída. Somente dt1, a tabela à esquerda, pode incluir chaves duplicadas. As chaves em dt2 precisam ser exclusivas. Aqui, o termo "chave" significa um conjunto exclusivo de colunas de chave, e não valores de coluna individuais. Por exemplo, se as colunas de chave fossem A e B, a tabela a seguir teria apenas chaves-valor exclusivas e, portanto, poderia ser usada como dt2:

R	B
Ana	Ruivo
Ana	Azul
Fred	Ruivo

Exemplo: [[0,0], [2,1]] compara valores da primeira coluna em ambas as tabelas e da terceira coluna de dt1 com a segunda coluna de dt1.

dt1Columns

Uma matriz de colunas de dt1 a serem incluídas na tabela de saída, além das colunas de chave de dt1. Esta matriz pode especificar colunas por índice, ID ou rótulo. Consulte getColumnIndex.

dt2Columns

Uma matriz de colunas de dt2 para incluir na tabela de saída, além das colunas de chave de dt2. Esta matriz pode especificar colunas por índice, ID ou rótulo. Consulte getColumnIndex.

Valor de retorno

Uma DataTable com as principais colunas, dt1Columns e dt2Columns. A tabela é classificada pelas principais colunas, da esquerda para a direita. Quando joinMethod for "inner", todas as células principais serão preenchidas. Para outros métodos de mesclagem, se nenhuma chave correspondente for encontrada, a tabela terá um valor nulo para todas as células-chave sem correspondência.

Exemplos

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

Formatadores

A API de visualização do Google fornece formatadores que podem ser usados para reformatar dados em uma visualização. Esses formatadores alteram o valor formatado da coluna especificada em todas as linhas. Observações:

• Os formatadores modificam apenas os valores formatados, e não os subjacentes. Por exemplo, o valor exibido seria "US$ 1.000,00", mas o valor subjacente ainda seria "1000".
• Os formatadores afetam apenas uma coluna por vez. Para reformatar várias colunas, aplique um formatador a cada coluna que você quer alterar.
• Se você também usar formatadores definidos pelo usuário, alguns formatadores de visualização do Google substituirão todos os formatadores definidos pelo usuário.

A formatação real aplicada aos dados é derivada da localidade com que a API foi carregada. Para mais detalhes, consulte Como carregar gráficos com uma localidade específica .

Importante: os formatadores só podem ser usados com um DataTable. Eles não podem ser usados com um DataView (os objetos DataView são somente leitura).

Aqui estão as etapas gerais para usar um formatador:

1. Consiga o objeto DataTable preenchido.
2. Para cada coluna que você quer reformatar, faça o seguinte:
   1. Crie um objeto que especifique todas as opções para seu formatador. Esse é um objeto JavaScript básico com um conjunto de propriedades e valores. Consulte a documentação do formatador para saber quais propriedades são compatíveis. Você também pode passar um objeto de notação literal de objeto especificando suas opções.
   2. Crie seu formatador, transmitindo seu objeto de opções.
   3. Chame formatter.format(table, colIndex), transmitindo DataTable e o número da coluna (base em zero) dos dados a serem reformados. Só é possível aplicar um formatador a cada coluna. A aplicação de um segundo formatador simplesmente substitui os efeitos do primeiro.
      Importante: muitos formatadores exigem tags HTML para exibir formatação especial. Se sua visualização for compatível com uma opção allowHtml, defina-a como verdadeira.

Veja um exemplo de alteração dos valores de data formatados de uma coluna de data para usar um formato de data longo ("1o de janeiro de 2009"):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

A maioria dos formatadores expõe os dois métodos a seguir:

Método	Descrição
google.visualization.formatter_name(options)	Construtor, em que formatter_name é um nome de formatterclass específico. options: um objeto JavaScript genérico que especifica as opções para esse formatador. Esse objeto é um objeto genérico com pares de propriedades/valores com propriedades específicas para esse formatador. Consulte a documentação do seu formatador específico para saber quais opções são compatíveis. Veja dois exemplos de maneiras de chamar o construtor do objeto DateFormat, transmitindo duas propriedades: // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	Reformata os dados na coluna especificada. data: um DataTable contendo os dados a serem reformados. Não é possível usar um DataView aqui. colIndex: o índice baseado em zero da coluna a ser formatada. Para formatar várias colunas, você precisa chamar esse método várias vezes, com diferentes valores de colIndex.

 

A API de visualização do Google fornece os seguintes formatadores:

Nome do formatador	Descrição
ArrowFormat	Adiciona uma seta para cima ou para baixo, indicando se o valor da célula está acima ou abaixo de um valor especificado.
BarFormat	Adiciona uma barra colorida em que a direção e a cor indicam se o valor da célula está acima ou abaixo de um valor especificado.
ColorFormat	Colore a célula de acordo com os valores que se enquadram em um intervalo específico.
DateFormat	Formata um valor de Date ou DateTime de várias maneiras diferentes, incluindo "1 de janeiro de 2009", "1/1/09" e "1 de janeiro de 2009".
NumberFormat	Formata vários aspectos de valores numéricos.
PatternFormat	Concatena valores de célula da mesma linha em uma célula especificada, junto com texto arbitrário.

ArrowFormat

Adiciona uma seta para cima ou para baixo a uma célula numérica, dependendo se o valor está acima ou abaixo de um valor base especificado. Se for igual ao valor base, nenhuma seta será exibida.

Opções

ArrowFormat oferece suporte às seguintes opções, transmitidas para o construtor:

Option	Descrição
base	Um número que indica o valor de base, usado para comparação com o valor da célula. Se o valor da célula for maior, a célula incluirá uma seta verde para cima. Se o valor da célula for menor, ela incluirá uma seta vermelha para baixo. Se for a mesma, nenhuma seta.

Exemplo de código

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

Adiciona uma barra colorida a uma célula numérica que indica se o valor da célula está acima ou abaixo de um valor base especificado.

Opções

BarFormat oferece suporte às seguintes opções, transmitidas para o construtor:

Option	Exemplo Descrição
base	Um número que é o valor base para comparar com o valor da célula. Se o valor da célula for maior, ela será desenhado à direita da base. Se for menor, será desenhado para a esquerda. O valor padrão é 0.
colorNegative	String que indica a seção de valor negativo das barras. Os valores possíveis são "red", "green" e "blue". O valor padrão é "red".
colorPositive	String que indica a cor da seção de valores positivos das barras. Os valores possíveis são "red", "green" e "blue". O padrão é "azul".
drawZeroLine	Um booleano que indica se é necessário desenhar uma linha de base escura de 1 pixel quando valores negativos estiverem presentes. A linha escura está ali para aprimorar a leitura visual das barras. O valor padrão é "falso".
max	O valor numérico máximo para o intervalo de barras. O valor padrão é o mais alto na tabela.
min	O valor do número mínimo do intervalo de barras. O valor padrão é o menor valor na tabela.
showValue	Se verdadeiro, mostra valores e barras; se falso, mostra apenas barras. O valor padrão é true.
width	Espessura de cada barra, em pixels. O valor padrão é 100.

Exemplo de código

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

Atribui cores ao primeiro ou segundo plano de uma célula numérica, dependendo do valor da célula. Esse formatador é incomum, porque não aceita as opções no construtor. Em vez disso, chame addRange() ou addGradientRange() quantas vezes quiser, para adicionar intervalos de cores, antes de chamar format(). As cores podem ser especificadas em qualquer formato HTML aceitável, por exemplo, "preto", "#000000" ou "#000".

Métodos

ColorFormat é compatível com os seguintes métodos:

Método	Descrição
google.visualization.ColorFormat()	Construtor. Não aceita argumentos.
addRange(from, to, color, bgcolor)	Especifica uma cor de primeiro plano e/ou de plano de fundo para uma célula, dependendo do valor dela. Qualquer célula com um valor no intervalo especificado de from para to receberá color e bgcolor. É importante perceber que o intervalo não é inclusivo, porque a criação de um intervalo de 1 a 1.000 e de 1.000 a 2.000 não cobrirá o valor de 1.000. from: [String, Number, Date, DateTime ou TimeOfDay]: o limite inferior (inclusive) do intervalo ou nulo. Se for nulo, corresponderá a -✕. Os limites de string são comparados alfabeticamente com os valores de string. to - [String, Number, Date, DateTime ou TimeOfDay]: o limite máximo (não inclusivo) do intervalo ou nulo. Se for nulo, corresponderá a +✕. Os limites de string são comparados em ordem alfabética com os valores de string. color: a cor a ser aplicada ao texto nas células correspondentes. Os valores podem ser "#RRGGBB" ou constantes de cor definidas, como "#FF0000" ou "vermelho". bgcolor - A cor a ser aplicada ao plano de fundo das células correspondentes. Os valores podem ser "#RRGGBB" ou constantes de cor definidas, como "#FF0000" ou "vermelho".
addGradientRange(from, to, color, fromBgColor, toBgColor)	Atribui uma cor de plano de fundo de um intervalo, de acordo com o valor da célula. A cor é dimensionada para corresponder ao valor da célula em um intervalo de cor de limite inferior a uma cor de limite superior. Esse método não pode comparar valores de string, como addRange() pode. Dica: geralmente, os intervalos de cores são difíceis para os espectadores avaliarem com precisão. O intervalo mais simples e fácil de ler é de uma cor totalmente saturada para branco (por exemplo, #FF0000—FFFFFF). from: [Number, Date, DateTime ou TimeOfDay]: o limite mínimo (inclusivo) do intervalo ou nulo. Se for nulo, corresponderá a -✕. to - [Number, Date, DateTime ou TimeOfDay]: o limite mais alto (não inclusivo) do intervalo, ou nulo. Se nulo, corresponderá a +✕. color: a cor a ser aplicada ao texto nas células correspondentes. Essa cor é a mesma para todas as células, independentemente do valor. fromBgColor: a cor de fundo das células que contêm valores na extremidade inferior do gradiente. Os valores podem ser "#RRGGBB" ou constantes de cor definidas, por exemplo, "#FF0000" ou "vermelho". toBgColor - a cor de fundo das células que contêm valores na extremidade superior do gradiente. Os valores podem ser "#RRGGBB" ou constantes de cor definidas, por exemplo, "#FF0000" ou "vermelho".
format(dataTable, columnIndex)	O método format() padrão para aplicar a formatação à coluna especificada.

Exemplo de código

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

Formata um valor Date de JavaScript de várias maneiras, incluindo "1 de janeiro de 2016", "1/1/16" e "1o de janeiro de 2016".

Opções

DateFormat oferece suporte às seguintes opções, transmitidas para o construtor:

Option	Descrição
formatType	Uma opção de formatação rápida para a data. Os seguintes valores de string são aceitos, reformando a data de 28 de fevereiro de 2016 conforme mostrado: "short" - formato curto. Por exemplo, "28/02/16" "medium": é o formato médio. Por exemplo, "28 de fevereiro de 2016" "longo" - formato longo, ex.: "28 de fevereiro de 2016" Não é possível especificar formatType e pattern ao mesmo tempo.
pattern	Um padrão de formato personalizado para aplicar ao valor, semelhante ao formato de data e hora ICU. Por exemplo: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); Não é possível especificar formatType e pattern ao mesmo tempo. Leia mais detalhes sobre padrões na próxima seção.
timeZone	O fuso horário em que o valor de data será mostrado. Esse é um valor numérico, indicando GMT + esse número de fusos horários (pode ser negativo). Os objetos de data são criados por padrão com o fuso horário presumido do computador em que foram criados. Essa opção é usada para exibir o valor em um fuso horário diferente. Por exemplo, se você criou um objeto Date das 17h em um computador localizado em Greenwich, Inglaterra, e especificou o timeZone como -5 (options['timeZone'] = -5 ou Horário do Pacífico Oriental nos EUA), o valor exibido será 12h.

Métodos

DateFormat é compatível com os seguintes métodos:

Método	Descrição
google.visualization.DateFormat(options)	Construtor. Consulte a seção de opções acima para mais informações.
format(dataTable, columnIndex)	O método format() padrão para aplicar a formatação à coluna especificada.
formatValue(value)	Retorna o valor formatado de um determinado valor. Esse método não requer um DataTable.

Exemplo de código

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

Mais sobre padrões de data

Confira mais alguns detalhes sobre os padrões compatíveis:

Os padrões são semelhantes ao formato de data e hora ICU, mas os seguintes padrões ainda não são compatíveis: A e D F g Y u w W. Para evitar colisão com padrões, qualquer texto literal que você queira que apareça na saída precisa estar entre aspas simples, exceto as aspas simples, que precisam ser duplicadas: por exemplo, "K 'o''clock.'".

Padrão	Descrição	Exemplo de saída
GG	Designador da era.	"ANÚNCIO"
yy ou aaaa	ano.	1996
M	Mês do ano. Para janeiro: M produz 1 MM produz 01 MMM produz em janeiro MMMM produz janeiro	"Julho" “07”
d	Dia do mês. Valores "d" extras acrescentam zeros à esquerda.	10
h	Hora na escala de 12 horas. Valores "h" extras acrescentam zeros à esquerda.	12
H	Hora na escala de 24 horas. Os valores de Hk extras adicionarão zeros à esquerda.	0
m	Minuto em uma hora. Valores "M" extras acrescentam zeros à esquerda.	30
s	Segundos em um minuto. Os valores de "s" extras acrescentam zeros à esquerda.	55
S	Segundo fracionário. Os valores “S” extras serão preenchidos à direita com zeros.	978
E	Dia da semana. As seguintes saídas para "terça-feira": E produz T Produtividade em EE ou EEE na terça ou terça-feira EEEE produz na terça-feira	"Ter" "Terça-feira"
aa	Período do dia	"PM"
k	Hora do dia (1 a 24). Valores "k" extras somam zeros à esquerda.	24
K	Hora do meio-dia (0 a 11). Valores "k" extras somam zeros à esquerda.	0
z	Fuso horário. Para o fuso horário 5, produz "UTC+5"	"UTC+5"
Z	Fuso horário no formato RFC 822. Para o fuso horário -5: Z, ZZ, ZZZ produzir, -0500 ZZZZ e mais produtos "GMT -05:00"	“-0800” "GMT -05:00"
v	Fuso horário (genérico).	"Etc/GMT-5"
.	escape para texto	'Data='
"	aspas simples	"aa"

NumberFormat

Descreve como colunas numéricas devem ser formatadas. As opções de formatação incluem especificar um símbolo de prefixo (como um cifrão) ou a pontuação a ser usada como um marcador de milhares.

Opções

NumberFormat oferece suporte às seguintes opções, transmitidas para o construtor:

Option	Descrição
decimalSymbol	Um caractere a ser usado como marcador decimal. O padrão é um ponto (.).
fractionDigits	Um número que especifica quantos dígitos serão exibidos após o decimal. O padrão é 2. Se você especificar mais dígitos do que o número, ele exibirá zeros para os valores menores. Valores truncados são arredondados (5 arredondados para cima).
groupingSymbol	Um caractere a ser usado para agrupar dígitos à esquerda do decimal em conjuntos de três. O padrão é uma vírgula (,).
negativeColor	A cor do texto para valores negativos. Nenhum valor padrão. Os valores podem ser qualquer valor de cor HTML aceitável, como "vermelho" ou "#FF0000".
negativeParens	Um booleano, em que "true" indica que os valores negativos precisam ser colocados entre parênteses. O padrão é verdadeiro.
pattern	Uma string de formato. Quando fornecidas, todas as outras opções são ignoradas, exceto negativeColor. A string de formato é um subconjunto do conjunto de padrões de ICU . Por exemplo, {pattern:'#,###%'} resultará nos valores de saída "1.000%", "750%" e "50%" para os valores 10, 7,5 e 0,5.
prefix	Um prefixo de string para o valor, por exemplo, "$".
suffix	Um sufixo de string para o valor, por exemplo, "%".

Métodos

NumberFormat é compatível com os seguintes métodos:

Método	Descrição
google.visualization.NumberFormat(options)	Construtor. Consulte a seção de opções acima para mais informações.
format(dataTable, columnIndex)	O método format() padrão para aplicar a formatação à coluna especificada.
formatValue(value)	Retorna o valor formatado de um determinado valor. Esse método não requer um DataTable.

Exemplo de código

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

Permite mesclar os valores das colunas designadas em uma única coluna, junto com texto arbitrário. Por exemplo, se você tiver uma coluna para o nome e outra para o sobrenome, preencha uma terceira coluna com {last name}, {first name}. Esse formatador não segue as convenções para o construtor e o método format(). Consulte a seção Métodos abaixo para mais instruções.

Métodos

PatternFormat é compatível com os seguintes métodos:

Método	Descrição
google.visualization.PatternFormat(pattern)	Construtor. Não aceita um objeto de opções. Em vez disso, ele usa um parâmetro de string pattern. Essa é uma string que descreve quais valores de coluna colocar na coluna de destino, junto com qualquer texto arbitrário. Incorpore marcadores na sua string para indicar um valor de outra coluna a ser incorporada. Os marcadores são {#}, em que # é o índice de uma coluna de origem a ser usada. O índice é um índice da matriz srcColumnIndices do método format() abaixo. Para incluir um caractere { ou } literal, faça o escape desta forma: \{ ou \}. Para incluir um caractere \ literal, faça o escape como \\. Exemplo de código O exemplo a seguir demonstra um construtor para um padrão que cria um elemento âncora, com o primeiro e o segundo elementos retirados do método format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	A chamada de formatação padrão, com alguns parâmetros adicionais: dataTable: a tabela de dados na qual operar. srcColumnIndices: uma matriz de um ou mais índices de coluna (baseados em zero) para extrair como as fontes da tabela de dados subjacente. Isso será usado como uma fonte de dados para o parâmetro pattern no construtor. Os números das colunas não precisam estar na ordem de classificação. opt_dstColumnIndex: [opcional] a coluna de destino para posicionar a saída da manipulação pattern. Se não for especificado, o primeiro elemento em srcColumIndices será usado como destino. Confira os exemplos de formatação após a tabela.

Aqui estão alguns exemplos de entradas e saídas para uma tabela de quatro colunas.

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

Exemplo de código

O exemplo a seguir demonstra como combinar dados de duas colunas para criar um endereço de e-mail. Ela usa um objeto DataView para ocultar as colunas de origem originais:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

Uma classe auxiliar para simplificar a criação de Gadgets que usam a API de visualização do Google.

Construtor

google.visualization.GadgetHelper()

Métodos

Método	Valor de retorno	Descrição
createQueryFromPrefs(prefs)	google.visualization.Query	Estático. Crie uma nova instância de google.visualization.Query e defina as propriedades dela de acordo com os valores das preferências do gadget. O tipo de parâmetro prefs é _IG_Prefs. A preferência _table_query_url é usada para definir o URL da origem dos dados de consulta. A preferência _table_query_refresh_interval é usada para definir o intervalo de atualização da consulta (em segundos).
validateResponse(response)	Booleano	Estático. O parâmetro response é do tipo google.visualization.QueryResponse. Retorna true se a resposta contém dados. Retornará false se a execução da consulta falhar e a resposta não contiver dados. Se ocorrer um erro, esse método exibirá uma mensagem de erro.

Classes de consulta

Os objetos a seguir estão disponíveis para enviar consultas de dados a uma fonte de dados externa, como as Planilhas Google.

• Consulta: encapsula a solicitação de dados de saída.
• QueryResponse: lida com a resposta da fonte de dados.

Consulta

Representa uma consulta enviada a uma fonte de dados.

Construtor

google.visualization.Query(dataSourceUrl, opt_options)

Parâmetros

dataSourceUrl

[Obrigatório, String] URL para enviar a consulta. Consulte a documentação sobre gráficos e planilhas das Planilhas Google.

opt_options

[Opcional, objeto] Um mapa de opções para a solicitação. Observação : se você estiver acessando uma fonte de dados restrita , não use esse parâmetro. Veja as propriedades compatíveis:

• sendMethod: [opcional, string] especifica o método a ser usado para enviar a consulta. Escolha um dos seguintes valores de string:
  • 'xhr': envie a consulta usando XmlHttpRequest.
  • 'scriptInjection': envia a consulta usando a injeção de script.
  • 'makeRequest': [disponível apenas para gadgets, que foram descontinuados] envie a consulta usando o método makeRequest() da API de gadgets. Se especificado, você também precisa especificar makeRequestParams.
  • "auto": usa o método especificado pelo parâmetro de URL tqrt no URL da fonte de dados. tqrt pode ter os seguintes valores: 'xhr', 'scriptInjection' ou 'makeRequest'. Se tqrt estiver ausente ou tiver um valor inválido, o padrão será "xhr" para solicitações de mesmo domínio e "scriptInjection" para solicitações entre domínios.
• makeRequestParams: [Object] um mapa de parâmetros para uma consulta makeRequest(). Usado e obrigatório somente se sendMethod for 'makeRequest'.

Métodos

Método	Valor de retorno	Descrição
abort()	Nenhum	Interrompe o envio automático de consultas iniciadas com setRefreshInterval().
setRefreshInterval(seconds)	Nenhum	Define a consulta para chamar automaticamente o método send a cada duração especificada (número de segundos), começando pela primeira chamada explícita a send. seconds é um número maior ou igual a zero. Se você usar esse método, chame-o antes de chamar o método send. Cancele esse método chamando-o novamente com zero (o padrão) ou chamando abort().
setTimeout(seconds)	Nenhum	Define o número de segundos de espera da fonte de dados antes de gerar um erro de tempo limite. seconds é um número maior que zero. O tempo limite padrão é de 30 segundos. Esse método, se usado, precisa ser chamado antes do método send.
setQuery(string)	Nenhum	Define a string de consulta. O valor do parâmetro string precisa ser uma consulta válida. Esse método, se usado, precisa ser chamado antes do método send. Saiba mais sobre a linguagem de consulta.
send(callback)	Nenhum	Envia a consulta para a fonte de dados. callback precisa ser uma função que será chamada quando a fonte de dados responder. A função de retorno de chamada receberá um único parâmetro do tipo google.visualization.QueryResponse.

QueryResponse

Representa uma resposta da execução de uma consulta conforme recebida da fonte de dados. Uma instância dessa classe é transmitida como um argumento para a função de retorno de chamada configurada quando Query.send foi chamado.

Métodos

Método	Valor de retorno	Descrição
getDataTable()	DataTable	Retorna a tabela de dados conforme retornado pela fonte de dados. Retornará null se a execução da consulta falhar e nenhum dado tiver sido retornado.
getDetailedMessage()	String	Retorna uma mensagem de erro detalhada para consultas que falharam. Se a execução da consulta for bem-sucedida, esse método retornará uma string vazia. A mensagem retornada é destinada a desenvolvedores e pode conter informações técnicas, por exemplo, "A coluna {salary} não existe".
getMessage()	String	Retorna uma breve mensagem de erro para consultas que falharam. Se a execução da consulta for bem-sucedida, esse método retornará uma string vazia. A mensagem retornada é uma mensagem curta destinada a usuários finais, por exemplo, "Consulta inválida" ou "Acesso negado".
getReasons()	Matriz de strings	Retorna uma matriz de zero ou mais entradas. Cada entrada é uma string curta com um código de erro ou aviso que foi gerado durante a execução da consulta. Códigos possíveis: access_denied O usuário não tem permissão para acessar a fonte de dados. invalid_query A consulta especificada tem um erro de sintaxe. data_truncated Uma ou mais linhas de dados que correspondem à seleção da consulta não foram retornadas devido a limites de tamanho de saída. (aviso). timeout A consulta não respondeu no tempo esperado.
hasWarning()	Booleano	Retorna true se a execução da consulta tiver alguma mensagem de aviso.
isError()	Booleano	Retornará true se a execução da consulta falhar e a resposta não contiver nenhuma tabela de dados. Retorna <false> se a execução da consulta foi bem-sucedida e a resposta contém uma tabela de dados.

Exibição de erros

A API oferece várias funções para ajudar você a exibir mensagens de erro personalizadas para os usuários. Para usar essas funções, forneça um elemento de contêiner na página (normalmente um <div>), em que a API exibirá uma mensagem de erro formatada. Esse contêiner pode ser o elemento de contêiner da visualização ou um contêiner apenas para erros. Se você especificar o elemento que contém a visualização, a mensagem de erro será exibida acima da visualização. Em seguida, chame a função apropriada abaixo para exibir ou remover a mensagem de erro.

Todas as funções são estáticas no namespace google.visualization.errors.

Muitas visualizações podem lançar um evento de erro; veja o evento de erro abaixo para saber mais sobre isso.

Confira um exemplo de erro personalizado no Exemplo de wrapper de consulta.

Função	Valor de retorno	Descrição
addError(container, message, opt_detailedMessage, opt_options)	Valor do ID da string que identifica o objeto de erro criado. Esse é um valor exclusivo na página e pode ser usado para remover o erro ou encontrar o elemento que o contém.	Adiciona um bloco de exibição de erro ao elemento de página especificado, com o texto e a formatação especificados. container: o elemento DOM em que a mensagem de erro será inserida. Se o contêiner não for encontrado, a função gerará um erro de JavaScript. message: uma mensagem de string a ser exibida. opt_detailedMessage: uma string de mensagem detalhada opcional. Por padrão, o texto usado é posicionado ao passar o mouse sobre ele, mas isso pode ser alterado na propriedade opt_options.showInToolTip descrita abaixo. opt_options: um objeto opcional com propriedades que definem várias opções de exibição para a mensagem. As seguintes opções são aceitas: showInTooltip: um valor booleano em que "true" mostra a mensagem detalhada somente como texto de dica, e "false" mostra a mensagem detalhada no corpo do contêiner após a mensagem curta. O valor padrão é true. type: uma string que descreve o tipo de erro, determina quais estilos CSS devem ser aplicados a essa mensagem. Os valores compatíveis são "error" e "warning". O valor padrão é "error". style: uma string de estilo para a mensagem de erro. Ele vai substituir os estilos aplicados ao tipo de aviso (opt_options.type). Exemplo: 'background-color: #33ff99; padding: 2px;' O valor padrão é uma string vazia. removable: um valor booleano, em que "true" significa que a mensagem pode ser fechada com um clique do mouse do usuário. O valor padrão é “false”.
addErrorFromQueryResponse(container, response)	Valor do ID de string que identifica o objeto de erro criado ou nulo se a resposta não indicar um erro. Esse é um valor exclusivo na página e pode ser usado para remover o erro ou encontrar o elemento que o contém.	Transmita uma resposta de consulta e um contêiner de mensagens de erro para este método: se a resposta da consulta indicar um erro de consulta, uma mensagem de erro será exibida no elemento de página especificado. Se a resposta da consulta for nula, o método gerará um erro de JavaScript. Transmita o QueryResponse recebido no gerenciador de consultas a essa mensagem para exibir um erro. Ele também definirá o estilo da tela adequado ao tipo (erro ou aviso, semelhante a addError(opt_options.type)). container: o elemento DOM em que a mensagem de erro será inserida. Se o contêiner não for encontrado, a função gerará um erro de JavaScript. response: um objeto QueryResponse recebido pelo gerenciador de consultas em resposta a uma consulta. Se esse valor for nulo, o método gerará um erro de JavaScript.
removeError(id)	Booleano: verdadeiro se o erro tiver sido removido; caso contrário, retorna falso.	Remove o erro especificado pelo ID da página. id: o ID da string de um erro criado usando addError() ou addErrorFromQueryResponse().
removeAll(container)	Nenhum	Remove todos os blocos de erro de um contêiner especificado. Se o contêiner especificado não existir, um erro será gerado. container: o elemento DOM que contém as strings de erro a serem removidas. Se o contêiner não for encontrado, a função gerará um erro de JavaScript.
getContainer(errorId)	Processar um elemento DOM que contém o erro especificado ou nulo se não for possível encontrá-lo.	Recupera um handle para o elemento do contêiner que contém o erro especificado por errorID. errorId: ID da string de um erro criado usando addError() ou addErrorFromQueryResponse().

Eventos

A maioria das visualizações dispara eventos para indicar que algo ocorreu. Como usuário do gráfico, muitas vezes você quer detectar esses eventos. Se você codifica sua própria visualização, acione esses eventos por conta própria.

Os métodos a seguir permitem que os desenvolvedores detectem eventos, removam manipuladores de eventos atuais ou acionem eventos de dentro de uma visualização.

• google.visualization.events.addListener() e google.visualization.events.addOneTimeListener() detectam eventos.
• google.visualization.events.removeListener() remove um listener existente.
• google.visualization.events.removeAllListeners() remove todos os listeners de um gráfico específico
• google.visualization.events.trigger() dispara um evento.

addListener()

Chame esse método para se registrar para receber eventos disparados por uma visualização hospedada em sua página. Documente quais argumentos do evento, se houver, serão transmitidos para a função de gerenciamento.

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

Um identificador para a instância de visualização de origem.

event_name

O nome da string do evento a ser detectado. As visualizações precisam documentar quais eventos são gerados.

handling_function

O nome da função JavaScript local que será chamada quando a source_visualization disparar o evento event_name. A função de gerenciamento recebe todos os argumentos de evento como parâmetros.

Retorna

Um gerenciador para o novo listener. O gerenciador pode ser usado para remover esse listener posteriormente, se necessário, chamando google.visualization.events.removeListener().

Exemplo

Este é um exemplo de inscrição para receber o evento de seleção

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

Ele é idêntico a addListener(), mas destina-se a eventos que só devem ser ouvidos uma vez. Os acionamentos subsequentes do evento não invocarão a função de gerenciamento.

Um exemplo de quando isso é útil: todo desenho faz com que um evento ready seja gerado. Se você quiser que apenas o primeiro ready execute seu código, convém usar addOneTimeListener em vez de addListener.

removeListener()

Chame esse método para cancelar o registro de um listener de eventos.

google.visualization.events.removeListener(listener_handler)

listener_handler

O gerenciador do listener a ser removido, conforme retornado por google.visualization.events.addListener().

removeAllListeners()

Chame esse método para cancelar o registro de todos os listeners de eventos de uma instância de visualização específica.

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

Um handle para a instância de visualização de origem da qual todos os listeners de eventos precisam ser removidos.

trigger().

Chamado pelos implementadores de visualizações. Chame esse método na sua visualização para disparar um evento com um nome e um conjunto de valores arbitrários.

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

Um identificador para a instância de visualização de origem. Se você estiver chamando essa função de um método definido pela visualização de envio, basta transmitir a palavra-chave this.

event_name

Um nome de string para chamar o evento. É possível escolher qualquer valor de string.

event_args

[opcional] Um mapa de pares de nome/valor a serem transmitidos ao método de recebimento. Por exemplo: {message: "Hello there!", score: 10, name: "Fred"}. Você poderá transmitir nulo se nenhum evento for necessário. O receptor precisa estar preparado para aceitar o valor nulo para esse parâmetro.

Exemplo

Veja um exemplo de visualização que gera um método chamado "select" quando o método "onclick" é chamado. Ela não transmite nenhum valor.

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;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
}

Métodos e propriedades de visualização padrão

Toda visualização deve expor o seguinte conjunto de métodos e propriedades obrigatórios e opcionais. No entanto, não há verificação de tipo para aplicar esses padrões. Portanto, leia a documentação de cada visualização.

• Construtor
• draw() (em inglês)
• getAction() [opcional]
• getSelection() [opcional]
• removeAction() [opcional]
• setAction() [opcional]
• setSelection() [opcional]

Observação : esses métodos estão no namespace da visualização, não no namespace google.visualization.

Construtor

O construtor precisa ter o nome da sua classe de visualização e retornar uma instância dessa classe.

visualization_class_name(dom_element)

dom_element

Um ponteiro para um elemento DOM em que a visualização precisa ser incorporada.

Exemplo

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

Desenha a visualização na página. Em segundo plano, isso pode ser buscar um gráfico de um servidor ou criar o gráfico na página usando o código de visualização vinculado. Chame esse método sempre que os dados ou as opções mudarem. O objeto precisa ser desenhado dentro do elemento DOM transmitido ao construtor.

draw(data[, options])

dados

Um DataTable ou DataView contendo os dados a serem usados para desenhar o gráfico. Não há um método padrão para extrair um DataTable de um gráfico.

options

[Opcional] Um mapa de pares de nome/valor de opções personalizadas. Exemplos incluem altura e largura, cores de fundo e legendas. A documentação da visualização deve listar quais opções estão disponíveis e oferecer suporte às opções padrão se você não especificar esse parâmetro. Você pode usar a sintaxe literal do objeto JavaScript para transmitir um mapa de opções. Por exemplo, {x:100, y:200, title:'An Example'}

Exemplo

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

Isso pode ser exposto por visualizações que têm dicas e permitem ações de dica.

Retorna o objeto de ação da dica com o actionID solicitado.

Exemplo:

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

Isso pode ser exposto por visualizações que querem permitir o acesso aos dados selecionados no gráfico.

selection_array getSelection()

Retorna

selection_array Uma matriz de objetos selecionados, cada um descrevendo um elemento de dados na tabela subjacente usado para criar a visualização (um DataView ou um DataTable). Cada objeto tem as propriedades row e/ou column, com o índice da linha e/ou coluna do item selecionado no DataTable. Se a propriedade row for nula, a seleção será uma coluna. Se a propriedade column for nula, a seleção será uma linha. Se ambas forem não nulas, então será um item de dados específico. Você pode chamar o método DataTable.getValue() para receber o valor do item selecionado. A matriz recuperada pode ser transmitida para setSelection().

Exemplo

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

Isso pode ser exposto por visualizações que têm dicas e permitem ações de dica.

Remove o objeto de ação da dica com o actionID solicitado do seu gráfico.

Exemplo:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

Isso pode ser exposto por visualizações que têm dicas e permitem ações de dica. Ela só funciona nos gráficos principais (barras, colunas, linhas, área, dispersão, combinação, bolha, pizza, rosca, vela, histograma, área em degraus).

Define uma ação de dica a ser executada quando o usuário clica no texto de ação.

setAction(action object)

O método setAction usa um objeto como parâmetro de ação. Esse objeto precisa especificar três propriedades: id, o ID da ação definida, text, o texto que aparecerá na dica da ação, e action, a função que será executada quando um usuário clicar no texto da ação.

Todas as ações de dica precisam ser definidas antes de chamar o método draw() do gráfico.

Exemplo:

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

O método setAction também pode definir duas propriedades adicionais: visible e enabled. Essas propriedades precisam ser funções que retornam valores boolean indicando se a ação da dica vai ficar visível e/ou ativada.

Exemplo:

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

Opcionalmente, seleciona uma entrada de dados na visualização, por exemplo, um ponto em um gráfico de área ou uma barra em um gráfico de barras. Quando esse método é chamado, a visualização precisa indicar visualmente qual é a nova seleção. A implementação de setSelection() não deve disparar um evento "select". As visualizações podem 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() ou selecionar a linha inteira.

Toda vez que esse método é chamado, todos os itens selecionados são desmarcados, e a nova lista de seleção transmitida precisa ser aplicada. Não há uma maneira explícita de desmarcar itens individuais. Para fazer isso, chame setSelection() com os itens para permanecer selecionados. Para desmarcar todos os elementos, chame setSelection(), setSelection(null) ou setSelection([]).

setSelection(selection_array)

selection_array

Uma matriz de objetos, cada um com uma propriedade numérica de linha e/ou coluna. row e column são o número da linha ou coluna baseada em zero de um item na tabela de dados a ser selecionado. Para selecionar uma coluna inteira, defina row como nulo. Para selecionar uma linha inteira, defina column como nulo. Exemplo:setSelection([{row:0,column:1},{row:1, column:null}]) seleciona a célula em (0,1) e toda a linha 1.

Métodos estáticos variados

Esta seção contém vários métodos úteis expostos no namespace google.visualization.

arrayToDataTable()

Esse método recebe uma matriz bidimensional e a converte em uma DataTable.

Os tipos de dados da coluna são determinados automaticamente pelos dados fornecidos. Os tipos de dados da coluna também podem ser especificados usando a notação literal de objeto na primeira linha (a linha do cabeçalho da coluna) da matriz (ou seja, {label: 'Start Date', type: 'date'}). Papéis de dados opcionais também podem ser usados, mas precisam ser definidos explicitamente usando a notação literal de objeto. A notação literal de objeto também pode ser usada para qualquer célula, permitindo que você defina Objetos de célula.

Sintaxe

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

Uma matriz bidimensional, em que cada linha representa uma linha na tabela de dados. Se opt_firstRowIsData for falso (o padrão), a primeira linha será interpretada como rótulos de cabeçalho. Os tipos de dados de cada coluna são interpretados automaticamente a partir dos dados fornecidos. Se uma célula não tiver valor, especifique um valor nulo ou vazio, conforme o caso.

opt_firstRowIsData

Define se a primeira linha define uma linha de cabeçalho ou não. Se verdadeiro, todas as linhas serão consideradas dados. Se for falso, a primeira linha será considerada uma linha de cabeçalho, e os valores serão atribuídos como rótulos de coluna. O padrão é "false".

Retorna

Uma nova DataTable.

Exemplos

O código a seguir demonstra três maneiras de criar o mesmo objeto DataTable:

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

Esse método cria um gráfico com uma única chamada. A vantagem de usar esse método é que ele exige um pouco menos de código, e é possível serializar e salvar visualizações como strings de texto para reutilização. Esse método não retorna um identificador para o gráfico criado. Portanto, não é possível atribuir listeners de método para capturar eventos do gráfico.

Sintaxe

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

Uma string literal JSON ou um objeto JavaScript, com as seguintes propriedades (diferencia maiúsculas de minúsculas):

Propriedade	Tipo	Obrigatório	Padrão	Descrição
chartType	String	Obrigatório	nenhum	Nome da classe da visualização. O nome do pacote google.visualization pode ser omitido nos gráficos do Google. Se a biblioteca de visualização apropriada ainda não tiver sido carregada, esse método a carregará para você se for uma visualização do Google. É necessário carregar visualizações de terceiros explicitamente. Exemplos:Table, PieChart, example.com.CrazyChart.
containerId	String	Obrigatório	nenhum	O ID do elemento DOM em sua página que hospedará a visualização.
do modelo.	Objeto	Opcional	nenhum	Um objeto que descreve as opções da visualização. É possível usar a notação literal JavaScript ou fornecer um identificador para o objeto. Exemplo:"options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	Objeto	Opcional	Nenhum	Uma DataTable usada para preencher a visualização. Pode ser uma representação literal de string JSON de um DataTable, conforme descrito acima, um identificador para um objeto google.visualization.DataTable preenchido ou uma matriz bidimensional, como a aceita por arrayToDataTable(opt_firstRowIsData=false) . É necessário especificar essa propriedade ou a propriedade dataSourceUrl.
dataSourceUrl	String	Opcional	Nenhum	Uma consulta na fonte de dados para preencher os dados do gráfico (por exemplo, um Planilhas Google). É necessário especificar essa propriedade ou a propriedade dataTable.
consulta	String	Opcional	Nenhum	Se dataSourceUrl for especificado, será possível especificar uma string de consulta semelhante a SQL usando a Linguagem de consulta de visualização para filtrar ou manipular os dados.
refreshInterval	Número	Opcional	Nenhum	Com que frequência, em segundos, a visualização precisa atualizar a origem da consulta. Use essa opção somente ao especificar dataSourceUrl.
visualização	Objeto OU matriz	Opcional	Nenhum	Define um objeto inicializador DataView, que atua como um filtro sobre os dados subjacentes, conforme definido pelo parâmetro dataTable ou dataSourceUrl. Você pode transmitir uma string ou um objeto inicializador DataView, como aquele retornado por dataview.toJSON(). Exemplo:"view": {"columns": [1, 2]} também é possível transmitir uma matriz de objetos inicializadores DataView. Nesse caso, o primeiro DataView na matriz é aplicado aos dados subjacentes para criar uma tabela de dados, o segundo DataView é aplicado à tabela de dados resultante da aplicação do primeiro DataView e assim por diante.

Exemplos

Cria um gráfico de tabela com base na fonte de dados de uma planilha e inclui a consulta SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

O próximo exemplo cria a mesma tabela, mas cria uma DataTable localmente:

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

Este exemplo passa uma representação de string JSON do gráfico, que você pode ter carregado de um arquivo:

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

Esse é o construtor para o elemento da barra de ferramentas que pode ser anexado a muitas visualizações. Ela permite que o usuário exporte os dados da visualização em formatos diferentes ou forneça uma versão incorporável da visualização para uso em diferentes lugares. Consulte a página da barra de ferramentas para mais informações e um exemplo de código.