Referência da API Google Preview

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

Observação: o namespace da API Google preview é google.visualization.*.

Observação sobre matrizes

Alguns navegadores não processam corretamente vírgulas à direita em matrizes JavaScript, então não as utilizam. Valores vazios no meio de uma matriz são aceitos. Por exemplo:

data = ['a','b','c', ,]; // BAD
data = ['a','b','c'];   // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.

Classe DataTable

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

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

Além disso, é possível atribuir propriedades personalizadas (pares nome/valor) a qualquer célula, linha, coluna ou à tabela inteira. Algumas visualizações aceitam propriedades personalizadas específicas. Por exemplo, a visualização em tabela é compatível com uma propriedade de célula chamada "estilo", 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 (em inglês)
[Opcional] Dados usados para inicializar a tabela. Isso pode ser o JSON retornado chamando DataTable.toJSON() em uma tabela preenchida ou um objeto JavaScript contendo dados usados para inicializar a tabela. A estrutura do objeto literal do JavaScript é descrita aqui. Se esse parâmetro não for fornecido, uma nova tabela de dados vazia será retornada.
opt_version (link em inglês)
[Opcional] Um valor numérico que especifica a versão do protocolo com fio usado. Isso só é usado por implementadores de fontes de dados de ferramentas de gráfico. A versão atual é 0.6.

Detalhes

O objeto DataTable é usado para armazenar os dados transmitidos para uma visualização. Um DataTable é uma tabela básica bidimensional. Todos os dados de 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 colunas). O objeto DataTable também aceita um mapa de propriedades arbitrárias atribuídas a um valor específico, uma linha, uma coluna ou a DataTable inteira. As visualizações podem usá-las para oferecer suporte a outros recursos. 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. As células podem usar uma versão "formatada" dos dados. Essa é uma versão em string dos dados, formatada para exibição por uma visualização. Uma visualização pode (mas não é obrigatória) usar a versão formatada para exibição, mas sempre usará os próprios dados para qualquer classificação ou cálculo que fizer, como determinar onde um gráfico colocar um ponto. Um exemplo pode ser a atribuição dos valores "low" (médio) e "high" (alto) como valores formatados para os valores numéricos de célula 1, 2 e 3.

Para adicionar linhas de dados depois de chamar o construtor, chame addRow() para uma única linha ou addRows() para várias linhas. Também é possível adicionar colunas chamando os métodos addColumn(). Há métodos de remoção para linhas e colunas também, mas, em vez de remover linhas ou colunas, considere criar um DataView que seja uma visualização seletiva do DataTable.

Se você mudar os valores em um DataTable depois que ele for transmitido para o método draw() de uma visualização, as mudanças não mudarão imediatamente o gráfico. É necessário chamar draw() novamente para refletir as mudanças.

Observação: os gráficos do Google não realizam nenhuma validação nas tabelas de dados. Em caso afirmativo, a renderização dos gráficos seria mais lenta. Se você fornecer um número em que a coluna esteja esperando uma string ou vice-versa, os gráficos do Google farão o melhor possível para interpretar o valor de uma maneira que faça sentido, mas não sinalizarão erros.

Exemplos

Veja no exemplo a seguir como instanciar e preencher um DataTable com uma string literal, com os mesmos dados mostrados no exemplo 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'}]
]);
Devo criar minha tabela de dados em JavaScript ou notação literal de objeto?

É possível criar um DataTable chamando o construtor sem parâmetros e adicionando valores chamando os métodos addColumn()/ addRows() listados abaixo ou transmitindo um objeto literal JavaScript preenchido para inicializá-lo. Os dois métodos são descritos abaixo. Qual usar?

  • Criar e preencher uma tabela em JavaScript chamando addColumn(), addRow() e addRows() é um código muito legível. Esse método é útil quando você insere o código manualmente. Isso é mais lento do que usar a notação literal de objeto (descrita a seguir), mas, em tabelas menores (por exemplo, 1.000 células), você provavelmente não notará muita diferença.
  • A declaração direta do objeto DataTable usando a notação literal de objeto é consideravelmente mais rápida em tabelas grandes. No entanto, pode ser uma sintaxe complicada para acertar. Use-a se você puder gerar a sintaxe literal de objeto no código, o que reduz a possibilidade de erros.

 

Métodos

Método Valor de retorno Descrição

addColumn(type, opt_label, opt_id)

OU

addColumn(description_object)

Número

Adiciona uma nova coluna à tabela de dados e retorna o índice da nova coluna. Todas as células da nova coluna recebem um valor null. Esse método tem duas assinaturas:

A primeira assinatura tem os seguintes parâmetros:

  • type: uma string com o tipo de dados dos valores da coluna. O tipo pode ser um dos seguintes: 'string', 'number', 'boolean', 'date', 'datetime', e 'timeofday'.
  • opt_label: [opcional] uma string com o rótulo da coluna. O rótulo da coluna normalmente é exibido como parte da visualização, por exemplo, como um cabeçalho de coluna em uma tabela ou como um rótulo de legenda em um gráfico de pizza. Se nenhum valor for especificado, uma string vazia será atribuída.
  • opt_id: [opcional] uma string com um identificador exclusivo para a coluna. Se nenhum valor for especificado, uma string vazia será atribuída.

A segunda assinatura tem um único parâmetro de objeto com os seguintes membros:

  • type: uma string que descreve o tipo de dados da coluna. Os mesmos valores de type acima.
  • label: [opcional, string] um rótulo para a coluna.
  • id: [opcional, string] é um ID para a coluna.
  • role: [opcional, string] um papel para a coluna.
  • pattern: [opcional, string] uma string de formato de número (ou data) especificando como exibir o valor da coluna.

Consulte também: getColumnId, getColumnLabel, getColumnType, insertColumn, getColumnRole

addRow(opt_cellArray) Número

Adiciona uma nova linha à tabela de dados e retorna o índice da nova linha.

  • opt_cellArray [opcional] – um objeto de linha, em notação JavaScript, especificando os dados da nova linha. Se o parâmetro não for incluído, ele vai adicionar uma nova linha vazia ao fim da tabela. Esse parâmetro é uma matriz de valores de célula. Se você quiser especificar apenas um valor para uma célula, basta fornecer o valor da célula. Por exemplo, 55 ou "hello"; se quiser especificar um valor e/ou propriedades formatados para a célula, use um objeto de célula (por exemplo, {v:55, f:'Cinquenta e cinco'}). É possível misturar valores simples e objetos de célula na mesma chamada de método. Use null ou uma entrada de matriz vazia para uma célula vazia.

Exemplos:

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.
addRows(numOrArray) Número

Adiciona novas linhas à tabela de dados e retorna o índice da última linha adicionada. Chame esse método para criar novas linhas vazias ou com dados usados para preencher as linhas, conforme descrito abaixo.

  • numOrArray: um número ou uma matriz:
    • Número: um número que especifica quantas linhas novas não preenchidas precisam ser adicionadas.
    • Matriz: uma matriz de objetos row usados para preencher um conjunto de novas linhas. Cada linha é um objeto, conforme descrito em addRow(). Use null ou uma entrada de matriz vazia para uma célula vazia.

Exemplo:

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.
]);

Consulte também: insertRows

clone() Tabela de dados Retorna um clone da tabela de dados. O resultado é uma cópia detalhada da tabela de dados, exceto pelas propriedades de célula, propriedades de linha, propriedades de tabela e propriedades de coluna, que são cópias superficiais. Isso significa que as propriedades não primitivas são copiadas por referência, mas as primárias são copiadas por valor.
getColumnId(columnIndex) String Retorna o identificador de uma determinada coluna especificado pelo índice da coluna na tabela subjacente.
Para tabelas de dados recuperadas por consultas, o identificador da coluna é definido pela fonte e pode ser usado para se referir às colunas ao usar a linguagem de consulta.
Consulte também: Query.setQuery
getColumnIndex(columnIdentifier) String, Número Retorna o índice de determinada coluna especificada pelo índice, ID ou rótulo da coluna, se ele existir nesta tabela. Caso contrário, retornará -1. Quando columnIdentifier é uma string, ela é usada para encontrar a coluna primeiro pelo ID e, depois, pelo rótulo.
Consulte também: getColumnId, getColumnLabel
getColumnLabel(columnIndex) String Retorna o rótulo de determinada coluna especificada pelo índice da coluna na tabela subjacente.
O rótulo da coluna geralmente é exibido como parte da visualização. Por exemplo, o rótulo da coluna pode ser exibido como cabeçalho da coluna em uma tabela ou como o rótulo da legenda em um gráfico de pizza.
Para tabelas de dados recuperadas por consultas, o rótulo da coluna é definido pela fonte de dados ou pela cláusula label da linguagem da consulta.
Consulte também: setColumnLabel
getColumnPattern(columnIndex) String

Retorna o padrão de formatação usado para formatar os valores da coluna especificada.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

Para tabelas de dados recuperadas por consultas, o padrão da coluna é definido pela fonte de dados ou pela cláusula format da linguagem de consulta. Um exemplo de padrão é '#,##0.00'. Para mais informações sobre padrões, consulte a referência de linguagem de consulta.

getColumnProperties(columnIndex) Objeto

Retorna um mapa de todas as propriedades da coluna especificada. O objeto de propriedades é retornado por referência. Dessa forma, alterar valores no objeto recuperado os altera no DataTable.

  • columnIndex é o índice numérico da coluna para a qual recuperar propriedades.
getColumnProperty(columnIndex, name) Automático

Retornará o valor de uma propriedade nomeada ou null se essa propriedade não estiver definida para a coluna especificada. O tipo de retorno varia de acordo com a propriedade.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • name é o nome da propriedade, como uma string.

Consulte também: setColumnProperty setColumnProperties

getColumnRange(columnIndex) Objeto

Retorna os valores mínimos e máximos de valores em uma coluna especificada. O objeto retornado tem as propriedades min e max. Se o intervalo não tiver valores, min e max conterão null.

columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

getColumnRole(columnIndex) String Retorna a função da coluna especificada.
getColumnType(columnIndex) String

Retorna o tipo de uma determinada coluna especificada pelo índice da coluna.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

O tipo de coluna retornado pode ser um dos seguintes: 'string', 'number', 'boolean', 'date', 'datetime', e 'timeofday'

getDistinctValues(columnIndex) Matriz de objetos

Retorna os valores exclusivos em uma determinada coluna, em ordem crescente.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

O tipo dos objetos retornados é o mesmo retornado pelo método getValue.

getFilteredRows(filters) Matriz de objetos

Retorna os índices de linhas que correspondem a todos os filtros fornecidos. Os índices são retornados em ordem crescente. A saída desse método pode ser usada como entrada para DataView.setRows() a fim de mudar o conjunto de linhas exibido em uma visualização.

filters: uma matriz de objetos que descrevem um valor de célula aceitável. Um índice de linhas será retornado por esse método se corresponder a todos os filtros fornecidos. Cada filtro é um objeto com uma propriedade column numérica que especifica o índice da coluna na linha a ser avaliada, além de um dos seguintes:

  • Uma propriedade value com um valor que precisa ser exatamente igual à célula na coluna especificada. O valor precisa ser do mesmo tipo da coluna; ou
  • Uma ou ambas as propriedades a seguir, do mesmo tipo da coluna sendo filtrada:
    • minValue: um valor mínimo para a célula. O valor da célula na coluna especificada precisa ser maior ou igual a esse valor.
    • maxValue: um valor máximo para a célula. O valor da célula na coluna especificada precisa ser menor ou igual a esse valor.
    Um valor nulo ou indefinido para minValue (ou maxValue) significa que o limite inferior (ou superior) do intervalo não será aplicado.

Outra propriedade opcional, test, especifica uma função a ser combinada com a filtragem de valor ou intervalo. A função é chamada com o valor da célula, os índices de linha e coluna e a tabela de dados. Ela vai retornar "false" se a linha precisar ser excluída do resultado.

Exemplo: getFilteredRows([{column: 3, value: 42}, {column: 2, minValue: 'bar', maxValue: 'foo'}, {column: 1, test: (value, rowId, columnId, datatable) => { return value == "baz"; }}]) retorna uma matriz que contém, em ordem crescente, os índices de todas as linhas para as quais a quarta coluna (índice da coluna 3) é exatamente 42, e a terceira coluna (índice da coluna 2) está entre "bar" e "foo" (inclusive).

getFormattedValue(rowIndex, columnIndex) String

Retorna o valor formatado da célula nos índices de linha e coluna fornecidos.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • ColumnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

Para saber mais sobre a formatação de valores de coluna, consulte a referência de linguagem de consulta.

Consulte também: setFormattedValue

getNumberOfColumns() Número Retorna o número de colunas na tabela.
getNumberOfRows() Número Retorna o número de linhas na tabela.
getProperties(rowIndex, columnIndex) Objeto

Retorna um mapa de todas as propriedades da célula especificada. O objeto de propriedades é retornado por referência, portanto, a alteração de valores no objeto recuperado os altera no DataTable.

  • rowIndex é o índice da linha da célula.
  • columnIndex é o índice da coluna da célula.
getProperty(rowIndex, columnIndex, name) Automático

Retorna o valor de uma propriedade nomeada ou null se essa propriedade não estiver definida para a célula especificada. O tipo de retorno varia de acordo com a propriedade.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • name é uma string com o nome da propriedade.

Consulte também: setCell setProperties setProperty

getRowProperties(rowIndex) Objeto

Retorna um mapa de todas as propriedades da linha especificada. O objeto de propriedades é retornado por referência. Dessa forma, alterar valores no objeto recuperado os altera no DataTable.

  • rowIndex é o índice da linha para a qual recuperar propriedades.
getRowProperty(rowIndex, name) Automático

Retornará o valor de uma propriedade nomeada ou null, se essa propriedade não estiver definida para a linha especificada. O tipo de retorno varia de acordo com a propriedade.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • name é uma string com o nome da propriedade.

Consulte também: setRowProperty setRowProperties

getSortedRows(sortColumns) Matriz de números

Retorna uma versão ordenada da tabela sem modificar a ordem dos dados subjacentes. Para classificar permanentemente os dados subjacentes, chame sort(). É possível especificar a classificação de várias maneiras, dependendo do tipo transmitido ao parâmetro sortColumns:

  • Um único número especifica o índice da coluna a ser classificada. A classificação vai estar em ordem crescente. Exemplo: sortColumns(3) vai classificar pela quarta coluna, em ordem crescente.
  • Um único objeto que contém o número do índice da coluna a ser classificado e uma propriedade booleana opcional desc. Se desc for definida como verdadeira, a coluna específica será classificada em ordem decrescente. Caso contrário, a classificação será em ordem crescente. Exemplos: sortColumns({column: 3}) classificará a quarta coluna em ordem crescente, enquanto sortColumns({column: 3, desc: true}) classificará a quarta coluna em ordem decrescente.
  • Uma matriz de números dos índices de colunas pelos quais classificar. O primeiro número é a coluna principal de classificação, o segundo é a secundária e assim por diante. Isso significa que, quando dois valores na primeira coluna são iguais, os valores da coluna seguinte são comparados e assim por diante. Exemplo: sortColumns([3, 1, 6]) classificará primeiro pela quarta coluna (em ordem crescente), depois pela segunda coluna (em ordem crescente) e, depois, pela sétima coluna (em ordem crescente).
  • Uma matriz de objetos, cada um com o número do índice da coluna que será classificado e uma propriedade booleana opcional desc. Se desc for definida como verdadeira, a coluna específica será classificada em ordem decrescente (o padrão é crescente). O primeiro objeto é a coluna principal de classificação, o segundo é a secundária e assim por diante. Isso significa que, quando dois valores na primeira coluna são iguais, os valores da coluna seguinte são comparados e assim por diante. Exemplo: sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}]) vai classificar primeiro pela quarta coluna (em ordem crescente), depois pela coluna 2 em ordem decrescente e depois pela coluna 7 em ordem decrescente.

O valor retornado é uma matriz de números, cada número é um índice de uma linha DataTable. A iteração nas linhas de DataTable pela ordem da matriz retornada resultará em linhas ordenadas pela sortColumns especificada. A saída pode ser usada como entrada para DataView.setRows() para alterar rapidamente o conjunto exibido de linhas em uma visualização.

Observe que a classificação é estável, ou seja, se você ordenar com base em valores iguais de duas linhas, a mesma ordenação retornará as linhas na mesma ordem todas as vezes.
Veja também: sort

Exemplo: para iterar em linhas ordenadas pela terceira coluna, use:

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}
getTableProperties Objeto Retorna um mapa de todas as propriedades da tabela.
getTableProperty(name) Automático

Retorna o valor de uma propriedade nomeada ou null se nenhuma propriedade estiver definida para a tabela. O tipo de retorno varia de acordo com a propriedade.

  • name é uma string com o nome da propriedade.

Consulte também: setTableProperties setTableProperty

getValue(rowIndex, columnIndex) Objeto

Retorna o valor da célula nos índices de linha e coluna fornecidos.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().

O tipo do valor retornado depende do tipo de coluna (consulte getColumnType):

  • Se o tipo da coluna for "string", o valor será uma string.
  • Se o tipo da coluna for "number", o valor será um número.
  • Se o tipo da coluna for "booleano", o valor será um booleano.
  • Se o tipo da coluna for "date" ou "datetime", o valor será um objeto "Date".
  • Se o tipo da coluna for "timeofday", o valor será uma matriz de quatro números: [hora, minuto, segundo, milissegundos].
  • Se o valor da célula for nulo, ele retornará null.
insertColumn(columnIndex, type [,label [,id]]) Nenhum

Insere uma nova coluna na tabela de dados, no índice específico. Todas as colunas existentes no índice especificado ou depois dele são movidas para um índice mais alto.

  • columnIndex é um número com o índice obrigatório da nova coluna.
  • type precisa ser uma string com o tipo de dados dos valores da coluna. O tipo pode ser um destes: 'string', 'number', 'boolean', 'date', 'datetime', e 'timeofday'.
  • label precisa ser uma string com o rótulo da coluna. O rótulo da coluna normalmente é exibido como parte da visualização, por exemplo, como um cabeçalho de coluna em uma tabela ou como um rótulo de legenda em um gráfico de pizza. Se nenhum valor for especificado, uma string vazia será atribuída.
  • id precisa ser uma string com um identificador exclusivo para a coluna. Se nenhum valor for especificado, uma string vazia será atribuída.

Consulte também: addColumn

insertRows(rowIndex, numberOrArray) Nenhum

Insira o número de linhas especificado no índice de linhas especificado.

  • rowIndex é o número de índice em que as novas linhas serão inseridas. As linhas serão adicionadas, a partir do número de índice especificado.
  • numberOrArray é um número de linhas novas e vazias a serem adicionadas ou uma matriz de uma ou mais linhas preenchidas a serem adicionadas ao índice. Consulte addRows() para ver a sintaxe para adicionar uma matriz de objetos de linha.

Consulte também: addRows

removeColumn(columnIndex) Nenhum

Remove a coluna no índice especificado.

  • columnIndex precisa ser um número com um índice de coluna válido.

Consulte também: removeColumn

removeColumns(columnIndex, numberOfColumns) Nenhum

Remove o número especificado de colunas começando da coluna no índice especificado.

  • numberOfColumns é o número de colunas a serem removidas.
  • columnIndex precisa ser um número com um índice de coluna válido.

Consulte também: removeColumn

removeRow(rowIndex) Nenhum

Remove a linha no índice especificado.

  • rowIndex precisa ser um número com um índice de linhas válido.

Consulte também: removeRows

removeRows(rowIndex, numberOfRows) Nenhum

Remove o número de linhas especificado a partir da linha no índice especificado.

  • numberOfRows é o número de linhas a serem removidas.
  • rowIndex precisa ser um número com um índice de linhas válido.

Consulte também: removeRow

setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]]) Nenhum

Define o valor, o valor formatado e/ou as propriedades de uma célula.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • value [opcional] é o valor atribuído à célula especificada. Para evitar a substituição desse valor, defina esse parâmetro como undefined. Para apagar esse valor, defina-o como null. O tipo do valor depende do tipo da coluna (consulte getColumnType()):
    • Se o tipo da coluna for "string", o valor vai ser uma string.
    • Se o tipo da coluna for "number", o valor deverá ser um número.
    • Se o tipo da coluna for "booleano", o valor deverá ser booleano.
    • Se o tipo da coluna for "date" ou "datetime", o valor deverá ser um objeto "Date".
    • Se o tipo da coluna for "timeofday", o valor precisará ser uma matriz de quatro números: [hora, minuto, segundo, milissegundos].
  • formattedValue [opcional] é uma string com o valor formatado como uma string. Para evitar a substituição desse valor, defina esse parâmetro como undefined. Para limpar esse valor e fazer com que a API aplique a formatação padrão como value conforme necessário, defina-o como null. Para definir explicitamente um valor vazio, defina-o como uma string vazia. O valor formatado normalmente é usado por visualizações para exibir rótulos de valor. Por exemplo, o valor formatado pode aparecer como um texto de rótulo em um gráfico de pizza.
  • properties [opcional] é um Object (um mapa de nome/valor) com propriedades adicionais para esta célula. Para evitar a substituição desse valor, defina esse parâmetro como undefined. Para limpar esse valor, defina-o como null. Algumas visualizações aceitam propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

Consulte também: setValue(), setFormattedValue(), setProperty(), setProperties().

setColumnLabel(columnIndex, label) Nenhum

Define o rótulo de uma coluna.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • label é uma string com o rótulo a ser atribuído à coluna. O rótulo da coluna normalmente é exibido como parte da visualização. Por exemplo, o rótulo da coluna pode ser exibido como o cabeçalho da coluna em uma tabela ou como o rótulo de legenda em um gráfico de pizza.

Consulte também: getColumnLabel

setColumnProperty(columnIndex, name, value) Nenhum

Define uma propriedade de coluna única. Algumas visualizações são compatíveis com propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para saber quais propriedades são compatíveis.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • name é uma string com o nome da propriedade.
  • value é um valor de qualquer tipo para atribuir à propriedade nomeada especificada da coluna especificada.

Consulte também:setColumnProperties getColumnProperty

setColumnProperties(columnIndex, properties) Nenhum

Define várias propriedades da coluna. Algumas visualizações são compatíveis com propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para saber quais propriedades são compatíveis.

  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • properties é um Object (mapa de nome/valor) com propriedades adicionais para essa coluna. Se null for especificado, todas as propriedades adicionais da coluna serão removidas.

Consulte também: setColumnProperty getColumnProperty

setFormattedValue(rowIndex, columnIndex, formattedValue) Nenhum

Define o valor formatado de uma célula.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • formattedValue é uma string com o valor formatado para exibição. Para limpar esse valor e fazer com que a API aplique a formatação padrão ao valor da célula conforme necessário, defina-o como formattedValue null. Para definir explicitamente um valor vazio, defina como uma string vazia.

Consulte também: getFormattedValue

setProperty(rowIndex, columnIndex, name, value) Nenhum

Define uma propriedade de célula. Algumas visualizações aceitam propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • name é uma string com o nome da propriedade.
  • value é um valor de qualquer tipo para atribuir à propriedade nomeada especificada da célula especificada.

Consulte também: setCell setProperties getProperty

setProperties(rowIndex, columnIndex, properties) Nenhum

Define várias propriedades da célula. Algumas visualizações são compatíveis com propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para saber quais propriedades são compatíveis.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns().
  • properties é um Object (mapa de nome/valor) com propriedades adicionais para esta célula. Se null for especificado, todas as propriedades adicionais da célula serão removidas.

Consulte também: setCell setProperty getProperty

setRowProperty(rowIndex, name, value) Nenhum

Define uma propriedade de linha. Algumas visualizações aceitam propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • name é uma string com o nome da propriedade.
  • value é um valor de qualquer tipo para atribuir à propriedade nomeada especificada da linha especificada.

Consulte também: setRowProperties getRowProperty

setRowProperties(rowIndex, properties) Nenhum

Define várias propriedades de linha. Algumas visualizações aceitam propriedades de linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • properties é um Object (mapa de nome/valor) com propriedades adicionais para essa linha. Se null for especificado, todas as outras propriedades da linha serão removidas.

Consulte também: setRowProperty getRowProperty

setTableProperty(name, value) Nenhum

Define uma única propriedade de tabela. Algumas visualizações aceitam propriedades de tabela, linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

  • name é uma string com o nome da propriedade.
  • value é um valor de qualquer tipo para atribuir à propriedade nomeada especificada da tabela.

Consulte também: setTableProperties getTableProperty

setTableProperties(properties) Nenhum

Define várias propriedades de tabela. Algumas visualizações aceitam propriedades de tabela, linha, coluna ou célula para modificar a exibição ou o comportamento delas. Consulte a documentação da visualização para ver quais propriedades são compatíveis.

  • properties é um Object (mapa de nome/valor) com propriedades adicionais para a tabela. Se null for especificado, todas as propriedades adicionais da tabela serão removidas.

Consulte também: setTableProperty getTableProperty

setValue(rowIndex, columnIndex, value) Nenhum

Define o valor de uma célula. Além de substituir qualquer valor de célula existente, esse método também limpará o valor e as propriedades formatados para a célula.

  • rowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().
  • columnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornadas pelo método getNumberOfColumns(). Esse método não permite que você defina um valor formatado para esta célula. Para fazer isso, chame setFormattedValue().
  • value é o valor atribuído à célula especificada. O tipo do valor retornado depende do tipo de coluna (consulte getColumnType):
    • Se o tipo da coluna for "string", o valor vai ser uma string.
    • Se o tipo da coluna for "number", o valor deverá ser um número.
    • Se o tipo da coluna for "booleano", o valor deverá ser booleano.
    • Se o tipo da coluna for "date" ou "datetime", o valor deverá ser um objeto "Date".
    • Se o tipo da coluna for "timeofday", o valor precisará ser uma matriz de quatro números: [hora, minuto, segundo, milissegundos].
    • Para qualquer tipo de coluna, o valor pode ser definido como null.

Veja também: setCell, setFormattedValue, setProperty, setProperties

sort(sortColumns) Nenhum Classifica as linhas de acordo com as colunas de classificação especificadas. O DataTable é modificado por esse método. Consulte getSortedRows() para ver uma descrição dos detalhes da classificação. Esse método não retorna os dados ordenados.
Veja também: getSortedRows
Exemplo: para classificar pela terceira coluna e depois pela segunda, use: data.sort([{column: 2}, {column: 1}]);
toJSON() String Retorna uma representação JSON do DataTable que pode ser transmitido para o construtor DataTable. Por exemplo:
{"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 data do JavaScript Lite do construtor

Você pode inicializar um DataTable transmitindo um objeto literal de string JavaScript para o parâmetro data. Chamaremos esse objeto de data. É possível codificar esse objeto manualmente, de acordo com a descrição abaixo, ou usar uma biblioteca Python auxiliar se você souber como usar o Python, e seu site puder usá-lo. No entanto, se você quiser criar 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 de string, número e data):

{
  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 opcional p que é um mapa de valores arbitrários.

Observação:todos os nomes de propriedade e constantes de string mostrados diferenciam maiúsculas de minúsculas. Além disso, as propriedades descritas como valores de strings devem ser colocadas entre aspas. Por exemplo, se você quiser especificar a propriedade de tipo como número, ela poderá ser expressada assim: type: 'number', mas o valor em si, como numérico, seria 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] é o tipo dos dados na coluna. Oferece suporte aos seguintes valores de string (os exemplos incluem a propriedade v:, descrita posteriormente):
    • "boolean" – Valor booleano JavaScript ("true" ou "false"). Valor do exemplo: v:'true'
    • "number": valor do número do JavaScript. Exemplos de valores: v:7, v:3.14, v:-55
    • "string": valor da string do JavaScript. Valor do exemplo: v:'hello'
    • "date": objeto JavaScript de data (mês com base em zero), com o horário truncado. Exemplo de valor: v:new Date(2008, 0, 15)
    • "datetime": objeto JavaScript "Date" incluindo o horário. Valor do exemplo: v:new Date(2008, 0, 15, 14, 30, 45)
    • "timeofday": matriz de três números e um quarto opcional, representando a hora (0 indica a meia-noite), o minuto, o segundo e o 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 do host não exija escapes sofisticados para acessar a coluna em JavaScript. Tome cuidado para não escolher uma palavra-chave em 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 numéricos, de coluna de data ou de hora. Isso é apenas para referência e provavelmente não será necessário 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 for proveniente 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 o 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 ela for compatível com qualquer propriedade no nível de célula, as descreverá. Caso contrário, a propriedade será ignorada. Exemplo: p:{style: 'border: 1px solid green;'}.

Exemplo de cols

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

rows Propriedade

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 para atribuir a toda a linha. Se ela for compatível com qualquer propriedade no nível da linha, as descreverá. Caso contrário, a propriedade será ignorada.

Objetos de célula

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

  • v [opcional] é o valor da célula. O tipo de dados deve corresponder ao tipo de dados da coluna. Se a célula for nula, a propriedade v precisará ser nula, mas ainda poderá ter as 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 não sejam necessários. Portanto, se você especificar Date(2008, 0, 1) para v, especifique "1o de janeiro de 2008" ou uma string para essa propriedade. Esse valor não é verificado em relação ao valor de v. A visualização não 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 for compatível com qualquer propriedade no nível de célula, ela as descreverá. 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 que as descrições de colunas de cols. Para indicar uma célula nula, é possível especificar null, deixar um espaço em branco para uma célula em uma matriz ou omitir membros da matriz à direita. Assim, para indicar uma linha com valor nulo para as duas primeiras células, especifique [ , , {cell_val}] ou [null, null, {cell_val}].

Veja um exemplo de objeto de tabela 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 aplicados a todo o DataTable. Esses valores podem ser de qualquer tipo JavaScript. Se a visualização for compatível com qualquer propriedade no nível da tabela de dados, as descreverá. Caso contrário, essa propriedade estará disponível para uso no aplicativo. Exemplo: p:{className: 'myDataTable'}.

Classe DataView

Uma visualização somente leitura de uma DataTable subjacente. Uma DataView permite selecionar apenas um subconjunto das colunas e/ou linhas. Isso também permite reordenar colunas/linhas e duplicar colunas/linhas.

Uma visualização é uma janela ativa no DataTable subjacente, e não um snapshot estático de dados. No entanto, ainda é necessário ter cuidado ao alterar a estrutura da própria tabela, conforme descrito aqui:

  • A adição ou remoção de colunas da tabela subjacente não será refletida pela visualização e poderá causar um comportamento inesperado na visualização. Será necessário criar uma nova DataView na DataTable para detectar essas alterações.
  • 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 todas as visualizações após a mudança para que a nova linha seja renderizada. 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. É preciso criar um novo DataView para refletir a nova tabela.
  • A alteração de valores de célula em células existentes é segura e as alterações são propagadas imediatamente para o DataView. No entanto, é preciso chamar draw() em todas as visualizações após a mudança para que os novos valores de célula sejam renderizados.

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

DataView também oferece suporte a colunas calculadas. Essas são colunas cujo valor é calculado em tempo real usando uma função que você fornece. Por exemplo, é possível incluir uma coluna que seja a soma de duas colunas anteriores ou uma coluna que calcule e mostre o trimestre de uma data usando outra coluna. Consulte setColumns() para mais detalhes.

Quando você modifica uma DataView ocultando ou mostrando linhas ou colunas, a visualização não é afetada até que você chame draw() na visualização novamente.

É possível combinar DataView.getFilteredRows() com DataView.setRows() para criar uma DataView com um subconjunto de dados interessante, como mostrado abaixo:

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 da tabela ou visualização de dados subjacente, na ordem original. Para ocultar ou mostrar linhas ou colunas nessa visualização, chame os métodos set...() ou hide...() adequados.

Veja também:

setColunas(), hideColunas(), setRows() e hideRows().

 

Construtor 2

Este construtor cria um novo DataView atribuindo um DataView serializado a um DataTable. Isso ajuda a recriar o DataView que foi serializado usando DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)
dados
O objeto DataTable usado para criar o DataView, em que você chamou o DataView.toJSON(). Se essa tabela for diferente da tabela original, você terá resultados imprevisíveis.
viewAsJson (link em japonês)
A string JSON retornada por DataView.toJSON(). Esta é uma descrição de quais linhas mostrar ou ocultar da tabela de dados data.

Métodos

Método Valor de retorno Descrição
Veja as descrições em DataTable. Igual aos métodos DataTable equivalentes, exceto que os índices de linha/coluna se referem ao índice na visualização e não na tabela/visualização subjacente.
getTableColumnIndex(viewColumnIndex) Número

Retorna o índice na tabela (ou visualização) subjacente de uma determinada coluna especificada pelo índice nesta visualização. viewColumnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas conforme retornado pelo método getNumberOfColumns(). Retorna -1, se essa for uma coluna gerada.

Exemplo: se setColumns([3, 1, 4]) tiver sido chamado anteriormente, getTableColumnIndex(2) retornará 4.

getTableRowIndex(viewRowIndex) Número

Retorna o índice na tabela subjacente (ou visualização) de uma determinada linha especificada pelo índice nesta visualização. viewRowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas retornadas pelo método getNumberOfRows().

Exemplo: se setRows([3, 1, 4]) tiver sido chamado anteriormente, getTableRowIndex(2) retornará 4.

getViewColumnIndex(tableColumnIndex) Número

Retorna o índice nessa visualização que é mapeado para uma determinada coluna especificada pelo índice na tabela ou visualização subjacente. Se houver mais de um índice, retornará o primeiro (menor). Se esse índice não existir (a coluna especificada não está na visualização), retornará -1. tableColumnIndex precisa ser um número maior ou igual a zero e menor que o número de colunas retornado pelo método getNumberOfColumns() da tabela/visualização subjacente.

Exemplo: se setColumns([3, 1, 4]) tiver sido chamado anteriormente, getViewColumnIndex(4) retornará 2.

getViewColumns() Matriz de números

Retorna as colunas dessa visualização em ordem. Ou seja, se você chamar setColumns com alguma matriz e depois chamar getViewColumns(), receberá uma matriz idêntica.

getViewRowIndex(tableRowIndex) Número

Retorna o índice nessa visualização que é mapeado para uma determinada linha especificada pelo índice na tabela ou visualização subjacente. Se houver mais de um índice, retornará o primeiro (menor). Se esse índice não existir (a linha especificada não está na visualização), retornará -1. tableRowIndex precisa ser um número maior ou igual a zero e menor que o número de linhas conforme retornado pelo método getNumberOfRows() da tabela/visualização subjacente.

Exemplo: se setRows([3, 1, 4]) tiver sido chamado anteriormente, getViewRowIndex(4) retornará 2.

getViewRows() Matriz de números

Retorna as linhas dessa visualização em ordem. Ou seja, se você chamar setRows com alguma matriz e depois chamar getViewRows(), receberá uma matriz idêntica.

hideColumns(columnIndexes) nenhum

Oculta as colunas especificadas da visualização atual. columnIndexes é uma matriz de números que representam os índices das colunas a serem ocultados. Esses índices são os números da tabela/visualização subjacente. Os números em columnIndexes não precisam estar em ordem, ou seja, [3,4,1] é aceitável. As colunas restantes mantêm a ordem de índice quando você faz iterações nelas. Inserir um número de índice para uma coluna já oculto não é um erro, mas inserir um índice que não existe na tabela/visualização subjacente gerará um erro. Para reexibir as colunas, chame setColumns().

Exemplo: se você tiver uma tabela com 10 colunas e chamar setColumns([2,7,1,7,9]) e depois hideColumns([7,9]), as colunas na visualização serão [2,1].

hideRows(min, max) Nenhum

Oculta todas as linhas com índices que estão entre mínimo e máximo (inclusivos) da visualização atual. Essa é uma sintaxe de conveniência para hideRows(rowIndexes) acima. Por exemplo, hideRows(5, 10) é equivalente a hideRows([5, 6, 7, 8, 9, 10]).

hideRows(rowIndexes) Nenhum

Oculta as linhas especificadas da visualização atual. rowIndexes é uma matriz de números que representam os índices das linhas a serem ocultas. Esses índices são os números de índice da tabela/visualização subjacente. Os números em rowIndexes não precisam estar em ordem, ou seja, [3,4,1] é aceitável. As linhas restantes mantêm a ordem do índice. Inserir um número de índice em uma linha já oculta não é um erro, mas inserir um índice que não existe na tabela/visualização subjacente gera um erro. Para reexibir as linhas, chame setRows().

Exemplo: se você tiver uma tabela com 10 linhas e chamar setRows([2,7,1,7,9]) e depois hideRows([7,9]), as linhas na visualização serão [2,1].

setColumns(columnIndexes) Nenhum

Especifica quais colunas estão visíveis nesta visualização. Todas as colunas não especificadas serão ocultadas. Trata-se de uma matriz de índices de colunas na tabela/visualização subjacente ou de colunas calculadas. Se você não chamar esse método, o padrão será mostrar todas as colunas. A matriz também pode conter cópias para mostrar a mesma coluna várias vezes. As colunas vão aparecer na ordem especificada.

  • columnIndexes: uma matriz de números e/ou objetos (pode ser misturada):
    • Numbers especificam o índice da coluna de dados de origem a ser incluída na visualização. Os dados são trazidos sem modificação. Se você precisar definir explicitamente um papel ou outras propriedades de coluna, especifique um objeto com uma propriedade sourceColumn.
    • Os objetos especificam uma coluna calculada. Uma coluna calculada cria um valor em tempo real para cada linha e o adiciona à visualização. O objeto precisa ter as seguintes propriedades:
      • calc [função]: uma função que será chamada para cada linha na coluna para calcular um valor para essa célula. A assinatura da função é func(dataTable, row), em que dataTable é a DataTable de origem e row é o índice da linha de dados de origem. A função precisa retornar um único valor do tipo especificado por type.
      • type [string]: o tipo de JavaScript do valor que a função calc retorna.
      • label [opcional, string]: um rótulo opcional para atribuir a essa coluna gerada. Se não for especificada, a coluna de visualização não terá rótulo.
      • id [opcional, string]: um ID opcional para atribuir à coluna gerada.
      • sourceColumn: [opcional, número] a coluna de origem a ser usada como um valor. Se especificado, não especifique a propriedade calc ou type. Isso é semelhante a transmitir um número em vez de um objeto, mas permite especificar um papel e propriedades para a nova coluna.
      • properties [opcional, objeto]: um objeto que contém qualquer propriedade arbitrária para atribuir a essa coluna. Se não for especificada, a coluna de visualização não terá propriedades.
      • role [opcional, string]: um papel a ser atribuído a essa coluna. Se não for especificado, o papel atual não será importado.

Exemplos:

// 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);
}
setRows(min, max) Nenhum

Define as linhas dessa visualização como todos os índices (na tabela/visualização subjacente) que estão entre o mínimo e o máximo (inclusivos). Essa é uma sintaxe de conveniência para setRows(rowIndexes) abaixo. Por exemplo, setRows(5, 10) é equivalente a setRows([5, 6, 7, 8, 9, 10]).

setRows(rowIndexes) Nenhum

Define as linhas visíveis nessa visualização, com base em números de índice da tabela/visualização subjacente. rowIndexes precisa ser uma matriz de números de índice que especifica quais linhas serão exibidas na visualização. A matriz especifica a ordem de exibição das linhas, que podem ser duplicadas. Somente as linhas especificadas em rowIndexes serão mostradas. Esse método limpa todas as outras linhas da visualização. A matriz também pode conter cópias, duplicando efetivamente a linha especificada nessa visualização. Por exemplo, setRows([3, 4, 3, 2]) fará com que a linha 3 apareça duas vezes nessa visualização. Assim, a matriz fornece um mapeamento das linhas da tabela/visualização subjacente a essa visualização. É possível usar getFilteredRows() ou getSortedRows() para gerar entrada para esse método.

Exemplo: para criar uma visualização com as linhas três e zero de uma tabela/visualização subjacente: view.setRows([3, 0])

toDataTable() Tabela de dados Retorna um objeto DataTable preenchido com as linhas e colunas visíveis do DataView.
toJSON() string Retorna uma representação em string desse DataView. Essa string não contém os dados reais, ela contém apenas as configurações específicas de DataView, como linhas e colunas visíveis. Você pode armazenar essa string e transmiti-la ao construtor DataView.fromJSON() estático para recriar essa visualização. Isso não inclui colunas geradas.

Classe WrapperWrapper

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

Outro bônus do uso do ChartWrapper é que é possível reduzir o número de carregamentos da biblioteca usando o carregamento dinâmico. Além disso, você não precisa carregar os pacotes explicitamente, porque ChartWrapper vai processar e carregar os pacotes de gráficos para você. Veja os exemplos abaixo para mais detalhes.

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 ChartWrapper. Para receber outros, você precisa chamar getChart() e se inscrever nos eventos diretamente no gerenciador de gráficos, conforme 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 (link em inglês)
[Opcional] - Um objeto JSON que define o gráfico ou uma versão em string serializada desse objeto. O formato desse objeto é mostrado na documentação do drawChart(). Se não for especificado, você precisará definir todas as propriedades adequadas usando os métodos set... expostos por esse objeto.

Métodos

O ChartWrapper expõe os seguintes métodos adicionais:

Método Tipo de retorno Descrição
draw(opt_container_ref) Nenhum

Desenha o gráfico. Esse método precisa ser chamado após as alterações feitas no gráfico ou nos dados para exibi-las.

  • opt_container_ref [Opcional] Uma referência a um elemento de contêiner válido na página. Se especificado, o gráfico será desenhado nesse local. Caso contrário, o gráfico será desenhado no elemento com o ID especificado por containerId.
toJSON() String Retorna uma versão de string da representação JSON do gráfico.
clone() ChartWrapper (link em inglês) Retorna uma cópia detalhada do wrapper do gráfico.
getDataSourceUrl() String Se esse gráfico receber os dados de uma fonte de dados, retornará o URL da fonte. Caso contrário, retorna nulo.
getDataTable() google.visualization.DataTable

Se esse gráfico receber os dados de um DataTable definido localmente, retornará uma referência ao DataTable do gráfico. Se esse gráfico receber os dados de uma fonte, retornará como nulo.

Todas as mudanças feitas no objeto retornado serão refletidas pelo gráfico na próxima vez que você chamar ChartWrapper.draw().

getChartType() String O nome da classe do gráfico encapsulado. Se este for um gráfico do Google, o nome não estará qualificado com google.visualization. Por exemplo, se for um gráfico de mapa de árvore, ele retornará "mapa de árvore" em vez de "google.visualization.treemap".
getChartName() String Retorna o nome do gráfico atribuído por setChartName().
getChart() Referência de objetos do gráfico Retorna uma referência ao gráfico criado por este ChartWrapper, por exemplo, um google.visualization.BarChart ou um google.visualization.ColumnChart . Ele retornará um valor nulo até que você tenha chamado draw() no objeto ChartWrapper e lançar um evento pronto. Os métodos chamados no objeto retornado serão refletidos na página.
getContainerId() String ID do elemento do contêiner DOM do gráfico.
getQuery() String A string de consulta desse gráfico, se tiver uma, e consulta uma fonte de dados.
getRefreshInterval() Número Qualquer intervalo de atualização desse gráfico, se ele consultar uma fonte de dados. Zero indica que não há atualização.
getOption(key, opt_default_val) Qualquer tipo

Retorna o valor especificado da opção do gráfico

  • key: o nome da opção a ser recuperada. Pode ser um nome qualificado, como 'vAxis.title'.
  • opt_default_value [opcional]: se o valor especificado for indefinido ou nulo, esse valor será retornado.
getOptions() Objeto Retorna o objeto de opções deste gráfico.
getView() Objeto OU Matriz Retorna o objeto inicializador DataView no mesmo formato de dataview.toJSON() ou uma matriz desses objetos.
setDataSourceUrl(url) Nenhum Define o URL de uma fonte de dados para usar no gráfico. Se você também definir uma tabela de dados para esse objeto, o URL da fonte de dados será ignorado.
setDataTable(table) Nenhum Define a tabela de dados para o gráfico. Transmita um dos seguintes valores: nulo, um objeto DataTable, uma representação JSON de um DataTable ou uma matriz seguindo a sintaxe de arrayToDataTable().
setChartType(type) Nenhum Define o tipo de gráfico. Transmita o nome da classe do gráfico encapsulado. Se este gráfico for do Google, não o qualifique com google.visualization. Por exemplo, para um gráfico de pizza, transmita "PieChart".
setChartName(name) Nenhum Define um nome arbitrário para o gráfico. Isso não é mostrado em nenhuma parte do gráfico, a menos que um gráfico personalizado seja projetado explicitamente para usá-lo.
setContainerId(id) Nenhum Define o ID do elemento DOM que contém o gráfico.
setQuery(query_string) Nenhum Define uma string de consulta, se este gráfico consulta uma fonte de dados. Se você especificar esse valor, também precisará definir o URL da fonte de dados.
setRefreshInterval(interval) Nenhum Define o intervalo de atualização desse gráfico, se ele consultar uma fonte de dados. Se você especificar esse valor, também vai precisar definir um URL de fonte de dados. Zero indica que não há atualização.
setOption(key, value) Nenhum Define um único valor da opção do gráfico, em que key é o nome da opção e value é o valor. Para desativar uma opção, transmita o valor nulo para o valor nulo. key pode ser um nome qualificado, como 'vAxis.title'.
setOptions(options_obj) Nenhum Define um objeto de opções completo para um gráfico.
setView(view_spec) Nenhum Define um objeto inicializador DataView que atua como filtro sobre os dados subjacentes. O wrapper do gráfico precisa ter dados de uma tabela de dados ou de uma fonte de dados para aplicar essa visualização. É possível transmitir uma string ou um objeto inicializador DataView, como o retornado por dataview.toJSON(). 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 nova tabela de dados, o segundo DataView é aplicado à tabela de dados resultante da aplicação do primeiro DataView e assim por diante.

Eventos

O objeto ChartWrapper gera os eventos a seguir. É preciso chamar ChartWrapper.draw() antes que qualquer evento seja gerado.

Nome Descrição Propriedades
error Disparado quando ocorre um erro ao tentar renderizar o gráfico. ID, mensagem
ready O gráfico está pronto para chamadas de método externo. Se você quiser interagir com o gráfico e chamar métodos depois de desenhá-lo, configure um listener para esse evento antes de chamar o método draw e chame-o somente depois que o evento for acionado. Nenhum
select Disparado quando o usuário clica em uma barra ou legenda. Quando um elemento do gráfico é selecionado, a célula correspondente da tabela de dados é selecionada. Quando uma legenda é selecionada, a coluna correspondente na tabela de dados é selecionada. Para saber o que foi selecionado, chame ChartWrapper.getChart(). getSelection(). Isso só será gerado quando o tipo de gráfico subjacente gerar um evento de seleção. Nenhum

Exemplo

Os dois snippets a seguir criam um gráfico de linhas equivalente. O primeiro usa a notação literal de JSON para definir o gráfico, e 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>

Mesmo gráfico, agora usando os 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 ChartEditor

A classe ChartEditor é usada para abrir uma caixa de diálogo na página que permite que o usuário personalize uma visualização em tempo real.

Para usar o ChartEditor:

  1. Carregue o pacote charteditor. Em google.charts.load(), carregue o pacote "grapheditor". Não é necessário carregar os pacotes para o tipo de gráfico renderizado no editor. O editor carregará todos os pacotes para você conforme necessário.
  2. Crie um objeto ChartWrapper que defina o gráfico a ser personalizado pelo usuário. Esse gráfico será mostrado na caixa de diálogo, e o usuário usará o editor para reformular o gráfico, alterar os tipos de gráfico ou até mesmo mudar os dados de origem.
  3. Crie uma nova instância ChartEditor e faça o registro para ouvir o evento "ok". Esse evento é gerado quando o usuário clica no botão "OK" da caixa de diálogo. Quando o valor for recebido, chame ChartEditor.getChartWrapper() para recuperar o gráfico modificado pelo usuário.
  4. Chame ChartEditor.openDialog(), transmitindo o ChartWrapper. Isso abre a caixa de diálogo. Os botões da caixa de diálogo permitem que o usuário feche o editor. A instância ChartEditor ficará disponível enquanto estiver no escopo. Ela não é destruída automaticamente após o usuário fechar a caixa de diálogo.
  5. Para atualizar o gráfico no código, chame setChartWrapper().

Métodos

Método Valor de retorno Descrição
openDialog(chartWrapper, opt_options) null

Abre o editor de gráficos como uma caixa de diálogo incorporada na página. A função retorna imediatamente. Ela não espera que a caixa de diálogo seja fechada. Se você não perder o escopo da instância, poderá chamar openDialog() novamente para reabrir a caixa de diálogo, embora precise transmitir um objeto ChartWrapper novamente.

  • graphWrapper: um objeto ChartWrapper que define o gráfico inicial a ser renderizado na janela. O gráfico precisa ter um DataTable preenchido ou estar conectado a uma fonte de dados válida. Esse wrapper é copiado internamente para o editor de gráficos. Por isso, as alterações posteriores feitas no identificador ChartWrapper não serão refletidas na cópia do editor de gráficos.
  • opt_options: [opcional] um objeto que contém todas as opções do editor de gráficos. Veja a tabela de opções abaixo.
getChartWrapper() ChartWrapper Retorna um ChartWrapper que representa o gráfico, com modificações do usuário.
setChartWrapper(chartWrapper) null

Use esse método para atualizar o gráfico renderizado no editor.

graphWrapper: um objeto ChartWrapper que representa o novo gráfico a ser renderizado. O gráfico precisa ter um DataTable preenchido ou estar conectado a uma fonte de dados válida.

closeDialog() null Fecha a caixa de diálogo do editor de gráficos.

Opções

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

Nome Tipo Padrão Descrição
dataSourceInput Alça do elemento ou "urlbox" null

Use essa opção para permitir que o usuário especifique uma fonte de dados para o gráfico. Essa propriedade pode ser um dos dois valores:

  • 'urlbox': mostre o URL da fonte de dados do gráfico na caixa de diálogo em uma caixa de texto editável. O usuário pode modificar isso, e o gráfico vai ser redesenhado com base na nova fonte de dados.
  • Elemento DOM: permite que você forneça um elemento HTML personalizado para selecionar uma fonte de dados. Transmita um identificador para um elemento HTML, um criado no código ou copiado da página. Esse elemento será exibido na caixa de diálogo. Use-o para permitir que o usuário escolha a fonte do gráfico. Por exemplo, crie uma caixa de listagem que contenha vários URLs de fonte de dados ou nomes fáceis de escolher. O elemento precisa implementar um gerenciador de seleção e usá-lo para mudar a fonte de dados do gráfico. Por exemplo, mudar o DataTable subjacente ou modificar o campo dataSourceUrl do gráfico.

Eventos

O editor de gráfico gera os seguintes eventos:

Nome Descrição Propriedades
ok Disparado quando o usuário clica no botão "OK" da caixa de diálogo. Depois de receber esse método, chame getChartWrapper() para recuperar o gráfico configurado pelo usuário. nenhum
cancel Disparado quando o usuário clica no botão "Cancelar" na caixa de diálogo. nenhum

Exemplo

O código de exemplo a seguir abre uma caixa de diálogo do editor de gráfico 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, unindo-os ou agrupando por valor de coluna.

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

Método Descrição
google.visualization.data.group Realiza uma ação SQL GROUP BY para retornar uma tabela agrupada por valores em colunas especificadas.
google.visualization.data.join Mescla duas tabelas de dados em uma ou mais colunas principais.

group()

Usa 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 DataTable de entrada.

A tabela retornada inclui uma linha para cada combinação de valores nas colunas de chaves especificadas. Cada linha inclui as colunas de chave mais uma coluna com um valor de coluna agregada 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 (em inglês)
A entrada DataTable. Isso não será modificado chamando group().
keys
Uma matriz de números e/ou objetos especificando em quais colunas o agrupamento será feito. A tabela de resultados inclui todas as colunas nessa matriz e todas as colunas em colunas. Se for um número, será um índice de colunas da entrada DataTable a ser agrupado. 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 para 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 auxiliar no agrupamento. Por exemplo, chamando uma função whatQuarter que calcula um trimestre de uma coluna de data. Assim, a API pode agrupar linhas por trimestre. O valor calculado é exibido nas colunas de chave da tabela retornada. Essa função pode ser declarada in-line dentro do objeto ou pode ser definida em outro lugar do código (precisa estar no escopo da chamada). A API oferece uma função modificadora simples. Veja instruções sobre como criar funções próprias e mais úteis. Você precisa saber o tipo de dados que essa função pode aceitar e chamá-lo apenas em colunas desse tipo. Você também precisa saber o tipo de retorno dessa função e declará-la 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: "number" ou "boolean".
  • label: [opcional] um rótulo de string para atribuir essa coluna no DataTable retornado.
  • id: [opcional] um código de string para atribuir essa coluna no DataTable retornado.

Exemplos:[0], [0,2] e [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]
colunas
[Opcional] Permite especificar quais colunas, além das principais, incluir na tabela de saída. Como todas as linhas do grupo são compactadas em uma única linha de saída, é necessário determinar o valor a ser exibido para esse grupo. Por exemplo, você pode optar por mostrar o valor da coluna da primeira linha no conjunto ou uma média de todas as linhas nesse grupo. columns é uma matriz de objetos com as seguintes propriedades:
  • coluna: um número que especifica o índice da coluna a ser exibida.
  • aggregate: uma função que aceita uma matriz de todos os valores dessa coluna no grupo de linhas e retorna um único valor para mostrar na linha de resultados. O valor de retorno precisa ser do tipo especificado pela propriedade type do objeto. Veja abaixo os detalhes sobre como criar sua própria função de agregação. Você precisa saber que tipos de dados esse método aceita e chamá-lo apenas nas colunas do tipo apropriado. A API 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: tipo de retorno da função de agregação. Precisa ser um tipo de string JavaScript, por exemplo, "number" ou "boolean".
  • label: [opcional] um rótulo de string para aplicar a esta coluna na tabela retornada.
  • id: [opcional] um código de string para aplicar a esta 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 importantes, 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 do modificador fornecidas

A API oferece as seguintes funções de modificador que podem ser transmitidas para as chaves. modifier para personalizar o comportamento do agrupamento.

Função Tipo de matriz de entrada Tipo de retorno Descrição
google.visualization.data.month Data number Dada uma data, ela retornará o valor do mês com base em zero (0, 1, 2 e assim por diante).

Funções de agregação fornecidas

A API oferece as seguintes funções de agregação, que podem ser transmitidas para as colunas. matriz de parâmetro aggregate.

Função Tipo de matriz de entrada Tipo de retorno Descrição
google.visualization.data.avg number number O valor médio da matriz transmitida.
google.visualization.data.count qualquer tipo number A contagem de linhas no grupo. Valores nulos e duplicados são contabilizados.
google.visualization.data.max número, string, data número, string, data, nulo O valor máximo na matriz. Para strings, esse é o primeiro item de uma lista lexicograficamente classificada. Para valores de data, é a data mais recente. Os valores nulos são ignorados. Retorna nulo se não houver máximo.
google.visualization.data.min número, string, data número, string, data, nulo O valor mínimo na matriz. Para strings, esse é o último item de uma lista lexicograficamente classificada. Para valores de data, é a data mais antiga. Os valores nulos são ignorados. Retornará nulo se não houver um mínimo.
google.visualization.data.sum number number A soma de todos os valores na matriz.

Criar uma função modificadora

É possível criar uma função de modificador para realizar uma transformação simples de valores de chave antes que a função group() agrupe suas linhas. Essa função usa um único valor de célula, executa uma ação nele (por exemplo, adiciona 1 ao valor) e a retorna. Os tipos de entrada e retorno não precisam ser do mesmo tipo, mas o autor da chamada precisa saber os tipos de entrada e de saída. Veja um exemplo de uma 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 colunas em um grupo de linhas e retorne um único número. Por exemplo, retorna uma contagem ou média de valores. Veja aqui uma implementação da função de agregação de contagem fornecida, que retorna uma contagem de quantas linhas estão no grupo:

// 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. Especifique um ou mais pares de colunas (colunas key) entre as duas tabelas. A tabela de saída incluirá as linhas de acordo com o método de mesclagem especificado: somente linhas em que as duas chaves correspondem, todas as linhas de uma tabela ou todas as linhas de ambas as tabelas, mesmo que não correspondam. A tabela de resultados inclui apenas as colunas de chave, além de outras colunas 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 da 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 de chave, a chave para essa linha será AB.

Sintaxe

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);
dt1 (link em inglês)
Um DataTable preenchido para mesclar com dt2.
dt2 (link em inglês)
Um DataTable preenchido para mesclar com dt1. Essa tabela não pode ter várias chaves idênticas (em que uma chave é uma combinação de valores de coluna de chaves).
joinMethod.
Uma string que especifica o tipo de mesclagem. Se dt1 tiver várias linhas que correspondem a uma linha dt2, a tabela de saída incluirá todas as linhas dt1 correspondentes. Escolha um destes valores:
  • 'full': a tabela de saída inclui todas as linhas das duas tabelas, independentemente de as chaves corresponderem. As linhas sem correspondência terão entradas de célula nulas, e as linhas correspondentes serão mescladas.
  • "inner": a mesclagem completa é filtrada para incluir apenas as linhas em que as chaves correspondem.
  • "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 linhas correspondentes de dt1.
keys
Uma matriz de colunas de chaves para comparar entre as 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 à regra fornecida por joinMethod para incluir uma linha da tabela. As colunas de chave sempre são incluídas na tabela de saída. Somente dt1, a tabela à esquerda, pode incluir chaves duplicadas. As chaves em dt2 precisam ser exclusivas. O termo "chave" aqui significa um conjunto exclusivo de colunas de chave, 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 únicas e, assim, poderia ser usada como dt2:
R B
Joana Vermelho
Joana Azul
Fred Vermelho
Exemplo: [[0,0], [2,1]] compara os valores da primeira coluna nas duas tabelas e na terceira coluna de dt1 com a segunda coluna de dt2.
dt1Colunas
Uma matriz de colunas de dt1 para incluir na tabela de saída, além das colunas de chave de dt1. Essa matriz pode especificar colunas por índice, ID ou rótulo. Consulte getColumnIndex.
dt2Colunas
Uma matriz de colunas de dt2 para incluir na tabela de saída, além das colunas de chave de dt2. Essa matriz pode especificar colunas por índice, ID ou rótulo. Consulte getColumnIndex.

Valor de retorno

Um DataTable com as colunas de chave, dt1Colunas e dt2Colunas. Essa tabela é classificada pelas colunas principais, da esquerda para a direita. Quando joinMethod é "inner", todas as células-chave precisam ser 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 Google preview 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, não os valores 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, determinados formatadores definidos pelo Google vão modificar 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).

    Veja as etapas gerais para usar um formatador:

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

    Veja um exemplo de alteração dos valores de data formatados de uma coluna de data para que use 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 é genérico e tem pares de propriedade/valor com propriedades específicas desse formatador. Consulte a documentação do seu formatador específico para saber quais opções são aceitas. Veja dois exemplos de como chamar o construtor para o 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: uma DataTable contendo os dados a serem formatados. Não é possível usar uma DataView aqui.
    • colIndex: índice baseado em zero da coluna a ser formatada. Para formatar várias colunas, é necessário chamar esse método várias vezes, com diferentes valores de colIndex.

     

    A API Google preview fornece os seguintes formatadores:

    Nome do formatador Descrição
    Formato de seta Adiciona uma seta para cima ou para baixo, indicando se o valor da célula está acima ou abaixo de um valor especificado.
    Formato de barra 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 (em inglês) Colore uma célula de acordo com a frequência em que os valores se enquadram em um intervalo especificado.
    Formato de data Formata um valor de data ou data/hora de várias maneiras diferentes, incluindo "1o de janeiro de 2009", "1/1/09" e "1o de janeiro de 2009".
    NumberFormat (em inglês) Formata vários aspectos dos valores numéricos.
    FormatFormat (link em inglês) Concatena valores de célula na mesma linha em uma célula especificada, além de texto arbitrário.

    Formato de seta

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

    Opções

    O ArrowFormat oferece suporte às seguintes opções, transmitidas ao construtor:

    Opção Descrição
    base

    Um número que indica o valor base, usado para comparar com o valor da célula. Se o valor da célula for maior, ela incluirá uma seta verde para cima. Se o valor da célula for menor, incluirá uma seta vermelha para baixo. Se o valor for o mesmo, nenhuma seta será exibida.

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

    Formato de barra

    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

    O BarFormat oferece suporte às seguintes opções, transmitidas ao construtor:

    Opção

    Exemplo

    Descrição
    base Um número que representa o valor base para comparar o valor da célula. Se o valor da célula for maior, ele será desenhado à direita da base. Se for menor, ele será desenhado à esquerda. O valor padrão é 0.
    colorNegative Uma 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 Uma 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 é preciso desenhar uma linha de base escura de 1 pixel quando valores negativos estiverem presentes. A linha escura aprimora a leitura visual das barras. O valor padrão é "false".
    max O valor máximo para o intervalo de barras. O valor padrão é o mais alto da tabela.
    min O valor mínimo para o intervalo de barras. O valor padrão é o mais baixo da tabela.
    showValue Se for verdadeiro, mostrará valores e barras; se for falso, mostrará 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 dele 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 da célula. Qualquer célula com um valor no intervalo especificado de: to receberá color e bgcolor. É importante perceber que o intervalo não é inclusivo, porque criar um intervalo de 1 a 1.000 e um segundo de 1.000 não cobrirá o valor de 1.000.

    • from - [String, Number, Date, DateTime ou TimeOfDay] é o limite inferior (inclusivo) do intervalo ou é nulo. Se nulo, ele corresponderá a -()`. Os limites de string são comparados em ordem alfabética em relação aos valores de string.
    • to: [String, Number, Date, DateTime ou TimeOfDay] é o limite alto (não inclusivo) do intervalo ou nulo. Se nulo, ele corresponderá a +θ. Os limites de string são comparados alfabeticamente com os valores de string.
    • cor: a cor a ser aplicada ao texto nas células correspondentes. Os valores podem ser valores "#RRGGBB" ou constantes de cores definidas, por exemplo, "#FF0000" ou "vermelho".
    • corgb: a cor a ser aplicada ao plano de fundo das células correspondentes. Os valores podem ser "#RRGGBB" ou constantes de cores definidas, por exemplo, "#FF0000" ou "red".
    addGradientRange(from, to, color, fromBgColor, toBgColor)

    Atribui uma cor de plano de fundo a um intervalo, de acordo com o valor da célula. A cor é dimensionada para corresponder ao valor da célula em um intervalo de cores de limite inferior a cor de limite superior. Esse método não pode comparar valores de string, como addRange(). Dica: intervalos de cores geralmente são difíceis para os espectadores medirem com precisão. O intervalo mais simples e fácil de ler é de uma cor totalmente saturada a branca (por exemplo, #FF0000: FFFFFF).

    • from - [Number, Date, DateTime, ou TimeOfDay] O limite inferior (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 for nulo, ele corresponderá a "+".
    • cor: a cor a ser aplicada ao texto nas células correspondentes. Essa cor é a mesma para todas as células, independentemente do valor delas.
    • 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 cores definidas, por exemplo, "#FF0000" ou "red".
    • toBgColor: a cor do plano de fundo de células que contêm valores na extremidade superior do gradiente. Os valores podem ser "#RRGGBB" ou constantes de cores definidas, por exemplo, "#FF0000" ou "red".

     

    format(dataTable, columnIndex) O método format() padrão para aplicar 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%'});

    Formato de data

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

    Opções

    O DateFormat oferece suporte às seguintes opções, transmitidas ao construtor:

    Opção Descrição
    formatType

    Uma opção de formatação rápida para a data. Os seguintes valores de string são compatíveis, reformatando a data de 28 de fevereiro de 2016, conforme mostrado:

    • "short" – formato curto, por exemplo, "28/02/16"
    • "medium" (médio): formato médio: por exemplo, "28 de fevereiro de 2016"
    • "long": formato longo (por exemplo, "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 de UTI. Por exemplo: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"});

    Não é possível especificar formatType e pattern ao mesmo tempo. Saiba mais sobre padrões na próxima seção.

    timeZone O fuso horário em que o valor da data será exibido. Este é um valor numérico que indica GMT + esse número de fusos horários (pode ser negativo). O objeto de data é criado por padrão com o fuso horário do computador em que é criado. Essa opção é usada para exibir esse valor em um fuso horário diferente. Por exemplo, se você tiver criado um objeto Data de 17h em um computador localizado em Greenwich, Inglaterra e tiver especificado o fuso horário 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 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

    Veja mais detalhes sobre os padrões compatíveis:

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

    Padrão Descrição Exemplo de saída
    GG designer da Era. "ANÚNCIO"
    aa ou aaaa ano. 1996
    M

    Mês do ano. Para janeiro:

    • M produz 1
    • MM produz 01
    • MMM produz janeiro
    • MMMM produz janeiro

    "Julho"

    “07”

    d Dia do mês. Valores "d" extras adicionarão zeros à esquerda. 10
    h Hora em escala de 12 horas. Valores "h" extras adicionarão zeros à esquerda. 12
    H Hora em escala de 24 horas. Os valores extras de Hk adicionarão zeros à esquerda. 0
    m Minuto em uma hora. Os valores "M" extras vão adicionar zeros à esquerda. 30
    s Segundos em um minuto. Valores extras "s" vão adicionar zeros à esquerda. 55
    S Segundo fracionário. Valores extras "S" serão preenchidos à direita com zeros. 978
    E

    Dia da semana. Os resultados a seguir são para "terça-feira":

    • E produz T
    • Produção de EE ou EEE ter ou terças
    • Produtos de EEEE produzidos na terça-feira

    "Ter"

    "Terça-feira"

    aa Período do dia "PM"
    k Hora do dia (1~24). Valores "k" extras vão adicionar zeros à esquerda. 24
    K Hora em AM/PM (0~11). Valores "k" extras vão adicionar 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 fuso horário -5:

    Produto Z, ZZ, ZZZ -0500

    ZZZZ e mais produtos "GMT -05:00"

    “-0800”

    "GMT -05:00"

    v

    Fuso horário (genérico).

    "Etc/GMT-5"
    . escape para texto 'Date='
    '' aspas simples aa

    NumberFormat

    Descreve como formatar as colunas numéricas. 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

    O NumberFormat oferece suporte às seguintes opções, transmitidas ao construtor:

    Opção Descrição
    decimalSymbol

    Um caractere para usar 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 nos valores menores. Valores truncados serão arredondados (5 arredondados para cima).

    groupingSymbol Um caractere que 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 "verdadeiro" indica que os valores negativos precisam ser cercados por parênteses. O padrão é "true".
    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 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 de colunas designadas em uma única coluna, com o texto arbitrário. Por exemplo, se você tem 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 do construtor e do método format(). Consulte a seção "Métodos" abaixo para ver 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 pattern de string. Essa é uma string que descreve quais valores de coluna precisam ser colocados na coluna de destino, além de qualquer texto arbitrário. Incorpore marcadores de posição na string para indicar um valor de outra coluna a ser incorporada. Os marcadores de posição são {#}, em que # é o índice de uma coluna de origem a ser usado. O índice é um índice da matriz srcColumnIndices do método format() abaixo. Para incluir um caractere { ou } literal, faça o escape dela desta maneira: \{ ou HTTP. Para incluir uma marca \ 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 extraídos 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 em que operar.
    • srcColumnIndices: uma matriz de um ou mais índices de colunas (baseados em zero) a serem extraídos como as origens da DataTable subjacente. Ele será usado como fonte de dados para o parâmetro pattern no construtor. Os números das colunas não precisam estar em ordem de classificação.
    • opt_dstColumnIndex: [opcional] a coluna de destino para colocar a saída da manipulação do padrão. Se não for especificado, o primeiro elemento em srcColumIndices será usado como destino.

    Veja os exemplos de formatação após a tabela.

    Veja 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

    No exemplo a seguir, demonstramos 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:

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

    Ajudar com o gadget

    Uma classe auxiliar para simplificar a gravação de gadgets que usam a API Google Preview.

    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
    1. A preferência _table_query_url é usada para definir o URL da fonte de dados da consulta.
    2. 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. Retornará true se a resposta contiver dados. Retornará false se a execução da consulta falhar e a resposta não contiver dados. Se ocorreu um erro, este método exibe uma mensagem de erro.

    Classes de consulta

    Os objetos a seguir estão disponíveis para enviar consultas 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 para uma fonte de dados.

    Construtor

    google.visualization.Query(dataSourceUrl, opt_options)

    Parâmetros

    DataSourceUrl.
    [Obrigatório, String] URL para onde enviar a consulta. Consulte a documentação sobre gráficos e planilhas para ver as Planilhas do Google.
    opt_options
    [Opcional, objeto] Um mapa de opções para a solicitação. Observação: se você está acessando uma fonte de dados restrita, não use esse parâmetro. Veja as propriedades aceitas:
    • 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 scripts.
      • 'makeRequest': [disponível somente para gadgets que foram descontinuados] Envie a consulta usando o método makeRequest() da API de gadgets. Se especificado, também precisa especificar makeRequestParams.
      • "auto": usa o método especificado pelo parâmetro de URL tqrt do 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 de vários domínios.
    • makeRequestParams: [Object] um mapa de parâmetros para uma consulta makeRequest(). Usado e obrigatório apenas se sendMethod for "makeRequest".

    Métodos

    Método Valor de retorno Descrição
    abort() Nenhum Interrompe o envio automatizado de consultas iniciado 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 como 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.

    Para cancelar esse método, chame-o novamente com zero (o padrão) ou abort().

    setTimeout(seconds) Nenhum Define o número de segundos de espera da resposta 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. Se for usado, esse método precisa ser chamado antes de chamar o método send.
    setQuery(string) Nenhum Define a string de consulta. O valor do parâmetro string precisa ser uma consulta válida.
    Se solicitado, esse método precisa ser chamado antes de chamar o 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 callback receberá um único parâmetro do tipo google.visualization.QueryResponse.

    Resposta de consulta

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

    Métodos

    Método Valor de retorno Descrição
    getDataTable() Tabela de dados Retorna a tabela de dados, conforme retornada pela fonte de dados. Retornará null se a execução da consulta falhar e nenhum dado for 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 aos 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 aos usuários finais, por exemplo, "Consulta inválida" ou "Acesso negado".
    getReasons() Matriz de strings Retorna uma matriz de zero entradas. Cada entrada é uma string curta com um erro ou código de alerta que foi gerado durante a execução da consulta. Códigos possíveis:
    • access_denied o usuário não tem permissões 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 de 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 Retornará true se a execução da consulta tiver mensagens 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 for bem-sucedida e a resposta contiver 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 seus usuários. Para usar essas funções, forneça um elemento de contêiner na página (normalmente um <div>), em que a API vai desenhar uma mensagem de erro formatada. Esse contêiner pode ser o elemento do contêiner de visualização ou um contêiner apenas para erros. Se você especificar o elemento de visualização, a mensagem de erro vai ser exibida acima da visualização. Em seguida, chame a função apropriada abaixo para mostrar ou remover a mensagem de erro.

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

    Muitas visualizações podem gerar um evento de erro. Veja o evento de erro abaixo para saber mais.

    Veja 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 dele.

    Adiciona um bloco de exibição de erros ao elemento de página especificado, com texto e formatação especificados.

    • container: o elemento DOM em que a mensagem de erro deve 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_detailMessage: uma string de mensagem detalhada opcional. Por padrão, é o texto sobre o mouse, 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 compatíveis:
      • showInTooltip: um valor booleano em que "true" mostra a mensagem detalhada apenas 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, que determina quais estilos CSS devem ser aplicados a essa mensagem. Os valores aceitos são "error" e "warning". O valor padrão é "error".
      • style: uma string de estilo da mensagem de erro. Esse estilo substituirá todos os estilos aplicados ao tipo de aviso (opt_options.type). Exemplo: 'background-color: #33ff99; padding: 2px;' O valor padrão é uma string vazia.
      • removível: um valor booleano, em que "true" significa que a mensagem pode ser fechada por um clique do usuário. O valor padrão é “false”.
    addErrorFromQueryResponse(container, response)

    Valor do ID da 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 dele.

    Transmita um contêiner de mensagem de erro e de resposta de consulta a este método: se a resposta da consulta indicar um erro de consulta, ele exibirá uma mensagem de erro 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 seu gerenciador de consulta 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 deve ser inserida. Se o contêiner não for encontrado, a função gerará um erro de JavaScript.
    • response: um objeto QueryResponse recebido por seu gerenciador de consulta em resposta a uma consulta. Se for nulo, o método gerará um erro JavaScript.
    removeError(id) Booleano: verdadeiro se o erro foi removido. Caso contrário, será 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, será gerado um erro.

    • 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 em um elemento DOM que contém o erro especificado ou nulo se não for encontrado.

    Recupera um identificador para o elemento de contêiner com o erro especificado por errorID.

    • errorId: ID de 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, você precisa detectar esses eventos. Se você codificar sua própria visualização, também convém acionar 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.

    addListener().

    Chame esse método para se registrar e receber eventos acionados por uma visualização hospedada na sua página. Você precisa documentar quais argumentos de evento, se houver, serão transmitidos para a função de manipulação.

    google.visualization.events.addListener(source_visualization,
      event_name, handling_function)
    source_visualization (link em inglês)
    Um identificador para a instância de visualização de origem.
    event_name
    O nome da string do evento a ser detectado. Uma visualização precisa documentar quais eventos são gerados.
    handling_function [função_de_manuseio]
    O nome da função JavaScript local a ser chamada quando source_visualization dispara o evento event_name. A função de manipulação receberá todos os argumentos de evento como parâmetros.

    Retorna

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

    Exemplo

    Veja um exemplo de inscrição para receber o evento selecionado

    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()

    Isso é idêntico a addListener(), mas é destinado a eventos que só devem ser ouvidos uma vez. Depois, o evento não invocará a função de manipulação.

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

    removeListener().

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

    google.visualization.events.removeListener(listener_handler)
    listener_Handler (em inglês)
    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 evento de uma instância de visualização específica.

    google.visualization.events.removeAllListeners(source_visualization)
    source_visualization (link em inglês)
    Um identificador para a instância de visualização de origem da qual todos os listeners de eventos precisam ser removidos.

    trigger()

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

    google.visualization.events.trigger(source_visualization, event_name,
      event_args)
    source_visualization (link em inglês)
    Um identificador para a instância de visualização de origem. Se você chamar 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. Você pode escolher qualquer valor de string que quiser.
    event_args (em inglês)
    [opcional] um mapa de pares de nome/valor para transmitir ao método de recebimento. Por exemplo:{message: "Hello there!", pontuação: 10, nome: "Fred"}. É possível transmitir nulo se nenhum evento for necessário. O receptor precisa estar preparado para aceitar nulo para esse parâmetro.

    Exemplo

    Veja o exemplo de uma visualização que gera um método chamado "select" quando o método onclick é chamado. Ele não retorna 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);
    }

    Propriedades e métodos de visualização padrão

    Cada visualização precisa 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.

    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 classe de visualização e retornar uma instância dela.

    visualization_class_name(dom_element)
    dom_element (link em inglês)
    Um ponteiro para um elemento DOM onde a visualização deve ser incorporada.

    Exemplo

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

    draw()

    Exibição da visualização na página. Em segundo plano, ele pode buscar um gráfico em um servidor ou criar um 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
    Uma DataTable ou DataView que contém 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 de visualização precisa listar quais opções estão disponíveis e oferecer suporte a opções padrão se você não especificar esse parâmetro. Você pode usar a sintaxe literal de 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()

    Se quiser, essa opção é exposta por visualizações que têm dicas e permitem ações de dica.

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

    Exemplo:

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

    getSelection().

    Opcionalmente, essa opção é exposta por visualizações que permitem acessar os 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 usada para criar a visualização (DataView ou DataTable). Cada objeto tem propriedades row e/ou column, com o índice da linha e/ou coluna do item selecionado no DataTable subjacente. 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 não forem nulas, ela 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()

    Se quiser, essa opção é exposta por visualizações que têm dicas e permitem ações de dica.

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

    Exemplo:

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

    setAction()

    Se quiser, essa opção é exposta por visualizações que têm dicas e permitem ações de dica. Ele só funciona para os gráficos principais (barra, coluna, linha, área, dispersão, combo, balão, torta, 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 sendo definida, text, o texto que vai aparecer na dica da ação, e action, a função que precisa ser executada quando um usuário clica no texto da ação.

    Toda e qualquer ação de dica precisa ser definida 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 outras propriedades: visible e enabled. Essas propriedades precisam ser funções que retornam valores boolean indicando se a ação de 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().

    É possível selecionar 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 vai disparar um evento "select". As visualizações podem ignorar parte da seleção. Por exemplo, uma tabela que pode mostrar apenas linhas selecionadas pode ignorar elementos de célula ou coluna na implementação de setSelection() ou selecionar a linha inteira.

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

    setSelection(selection_array)
    matriz de seleção
    Uma matriz de objetos, cada um com uma propriedade numérica de linha e/ou coluna. row e column são o número de linhas ou colunas 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 em toda a linha 1.

    Vários métodos estáticos

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

    arrayToDataTable()

    Esse método usa 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 (link em inglês)
    Uma matriz bidimensional, em que cada linha representa uma linha na tabela de dados. Se opt_firstRowIsData for falso (padrão), a primeira linha será interpretada como rótulos de cabeçalho. Os tipos de dados de cada coluna são interpretados automaticamente com base nos dados fornecidos. Se uma célula não tiver valor, especifique um valor nulo ou vazio conforme apropriado.
    opt_firstRowIsData (em inglês)
    Define se a primeira linha define ou não uma linha de cabeçalho. Se for 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

    Um novo 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 em uma única chamada. A vantagem de usar esse método é que ele exige um pouco menos de código, e você pode 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)
    gráfico_JSON_ou_objeto
    Uma string JSON literal ou um objeto JavaScript com as seguintes propriedades (diferencia maiúsculas de minúsculas):
    Propriedade Tipo Obrigatório Padrão Descrição
    TipoDeGráfico String Obrigatório nenhum Nome da classe da visualização. O nome do pacote google.visualization pode ser omitido para gráficos do Google. Se a biblioteca de visualização apropriada ainda não foi carregada, esse método carregará a biblioteca 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 ID do elemento DOM na sua página que vai hospedar a visualização.
    opções Objeto Opcional nenhum Um objeto que descreve as opções de visualização. Você pode usar a notação literal do JavaScript ou fornecer um identificador para o objeto. Exemplo:"options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
    tabela de dados Objeto Opcional Nenhum Um DataTable usado para preencher a visualização. Pode ser uma representação literal de string JSON de uma 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.
    URL da origem dos dados String Opcional Nenhum Uma consulta de fonte de dados para preencher os dados do gráfico (por exemplo, uma planilha do Google). É necessário especificar essa propriedade ou a propriedade dataTable.
    consulta String Opcional Nenhum Ao especificar dataSourceUrl, você tem a opção de especificar uma string de consulta semelhante a SQL usando a Linguagem de consulta de visualização para filtrar ou manipular os dados.
    Intervalo de atualização Número Opcional Nenhum Com que frequência, em segundos, a visualização precisa atualizar a origem da consulta. Use isso apenas ao especificar dataSourceUrl.
    visualização Objeto OU Matriz Opcional Nenhum Define um objeto inicializador DataView, que atua como um filtro sobre os dados, conforme definido pelo parâmetro dataTable ou dataSourceUrl. É possível transmitir uma string ou um objeto inicializador DataView, como o retornado por dataview.toJSON(). Exemplo: "view": {"columns": [1, 2]}. Também é possível transmitir uma matriz de objetos inicializadores DataView, em que o primeiro DataView na matriz é aplicado aos dados subjacentes para criar uma nova tabela de dados, e 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 em uma fonte de dados de 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 um 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 transmite uma representação em string JSON do gráfico, que você pode ter carregado usando 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 do elemento da barra de ferramentas que pode ser anexado a muitas visualizações. Essa barra de ferramentas permite que o usuário exporte os dados de visualização em diferentes formatos 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.