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.*
.
- Classe DataTable
- Classe DataView
- Classe WrapperWrapper
- Classe ChartEditor
- Métodos de manipulação de dados
- Formatadores
- Formato de seta
- Formato de barra
- ColorFormat (em inglês)
- Formato de data
- NumberFormat (em inglês)
- FormatFormat (link em inglês)
- Classe GadgetHelper
- Classes de consulta
- Classe de erro de exibição
- Eventos
- Métodos e propriedades de visualização padrão
- Construtor
- draw();
- getAction().
- getSelection() (em inglês)
- removeAction().
- setAction().
- setSelection().
- Vários métodos estáticos
- arrayToDataTable().
- drawChart();
- drawToolbar() (link em inglês)
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'}] ]);
É 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()
eaddRows()
é 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 |
---|---|---|
OU
|
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 A primeira assinatura tem os seguintes parâmetros:
A segunda assinatura tem um único parâmetro de objeto com os seguintes membros:
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.
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.
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.
Para tabelas de dados recuperadas por consultas, o padrão da coluna é definido pela fonte de dados
ou pela cláusula |
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
|
getColumnProperty(columnIndex, name)
|
Automático |
Retornará o valor de uma propriedade nomeada ou
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
|
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.
O tipo de coluna retornado pode ser um dos seguintes: |
getDistinctValues(columnIndex) |
Matriz de objetos |
Retorna os valores exclusivos em uma determinada coluna, em ordem crescente.
O tipo dos objetos retornados é o mesmo retornado pelo método |
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
Outra propriedade opcional,
Exemplo: |
getFormattedValue(rowIndex, columnIndex)
|
String |
Retorna o valor formatado da célula nos índices de linha e coluna fornecidos.
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
|
getProperty(rowIndex, columnIndex, name)
|
Automático |
Retorna o valor de uma propriedade nomeada ou
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
|
getRowProperty(rowIndex, name)
|
Automático |
Retornará o valor de uma propriedade nomeada ou
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
O valor retornado é uma matriz de números, cada número é um índice de uma
linha
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. 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
Consulte também: setTableProperties setTableProperty |
getValue(rowIndex, columnIndex) |
Objeto |
Retorna o valor da célula nos índices de linha e coluna fornecidos.
O tipo do valor retornado depende do tipo de coluna (consulte getColumnType):
|
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.
Consulte também: addColumn |
insertRows(rowIndex, numberOrArray) |
Nenhum |
Insira o número de linhas especificado no índice de linhas especificado.
Consulte também: addRows |
removeColumn(columnIndex) |
Nenhum |
Remove a coluna no índice especificado.
Consulte também: removeColumn |
removeColumns(columnIndex, numberOfColumns)
|
Nenhum |
Remove o número especificado de colunas começando da coluna no índice especificado.
Consulte também: removeColumn |
removeRow(rowIndex) |
Nenhum |
Remove a linha no índice especificado.
Consulte também: removeRows |
removeRows(rowIndex, numberOfRows) |
Nenhum |
Remove o número de linhas especificado a partir da linha no índice especificado.
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.
Consulte também: setValue(), setFormattedValue(), setProperty(), setProperties(). |
setColumnLabel(columnIndex, label)
|
Nenhum |
Define o rótulo de uma coluna.
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.
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.
Consulte também: setColumnProperty getColumnProperty |
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
Nenhum |
Define o valor formatado de uma célula.
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.
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.
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.
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.
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.
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.
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.
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]
-
"boolean" – Valor booleano JavaScript ("true" ou "false"). Valor do exemplo:
-
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). SeDataTable
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'}]
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.
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 propriedadev
precisará ser nula, mas ainda poderá ter as propriedadesf
ep
. -
f
[opcional] uma versão de string do valorv
, formatada para exibição. Normalmente, os valores serão correspondentes, embora não sejam necessários. Portanto, se você especificarDate(2008, 0, 1)
parav
, especifique "1o de janeiro de 2008" ou uma string para essa propriedade. Esse valor não é verificado em relação ao valor dev
. 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 dev
será gerada automaticamente usando o formatador padrão. Os valoresf
podem ser modificados usando seu próprio formatador, definidos comsetFormattedValue()
ousetCell()
ou recuperados comgetFormattedValue()
. -
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étodosgetProperty()
egetProperties()
. 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
naDataTable
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étodossetRows() or hideRows()
e você adicionar ou remover linhas da tabela subjacente, o comportamento será inesperado. É preciso criar um novoDataView
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 chamardraw()
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
ouDataView
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étodosset...()
ouhide...()
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 oDataView
, em que você chamou oDataView.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.
Exemplo: se |
getTableRowIndex(viewRowIndex) |
Número |
Retorna o índice na tabela subjacente (ou visualização) de uma determinada linha especificada pelo índice nesta visualização.
Exemplo: se |
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.
Exemplo: se |
getViewColumns() |
Matriz de números |
Retorna as colunas dessa visualização em ordem. Ou seja, se você chamar |
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.
Exemplo: se |
getViewRows() |
Matriz de números |
Retorna as linhas dessa visualização em ordem. Ou seja, se você chamar |
hideColumns(columnIndexes) |
nenhum |
Oculta as colunas especificadas da visualização atual.
Exemplo: se você tiver uma tabela com 10 colunas e chamar |
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) |
Nenhum |
Oculta as linhas especificadas da visualização atual.
Exemplo: se você tiver uma tabela com 10 linhas e chamar |
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.
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) |
Nenhum |
Define as linhas visíveis nessa visualização, com base em números de índice da tabela/visualização subjacente.
Exemplo: para criar uma visualização com as linhas três e zero de uma tabela/visualização subjacente: |
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.
|
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
Todas as mudanças feitas no objeto retornado serão refletidas pelo gráfico na próxima vez que você chamar |
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
|
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:
-
Carregue o pacote
charteditor
. Emgoogle.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. -
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. -
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. -
Chame
ChartEditor.openDialog()
, transmitindo oChartWrapper
. 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ânciaChartEditor
ficará disponível enquanto estiver no escopo. Ela não é destruída automaticamente após o usuário fechar a caixa de diálogo. - 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
|
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 |
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:
|
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 chamandogroup()
. - 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 [[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.
- Acesse seu objeto
DataTable
preenchido. - Faça o seguinte para cada coluna que você quiser reformatar:
- 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.
- Crie o formatador e transmita o objeto de opções.
-
Chame
formatter
.format(table, colIndex)
, transmitindo oDataTable
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çãoallowHtml
, defina-a como "true".
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:
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.
// 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.
|
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 | ExemploDescriçã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.
|
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
|
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:
Não é possível especificar |
pattern |
Um padrão de formato personalizado para aplicar ao valor, semelhante ao
formato de data e hora de UTI.
Por exemplo:
Não é possível especificar |
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 |
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:
|
"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":
|
"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
A string de formato é um subconjunto do
conjunto de padrões de ICU
.
Por exemplo, |
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
|
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
Exemplo de códigoO 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 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:
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
|
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". Setqrt
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".
-
sendMethod: [opcional, string) especifica o método a ser usado para enviar a consulta. Escolha um dos seguintes valores de string:
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 Se você usar esse método, chame-o antes de chamar o método
Para cancelar esse método, chame-o novamente com zero (o padrão) ou
|
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:
|
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.
|
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
|
removeError(id) |
Booleano: verdadeiro se o erro foi removido. Caso contrário, será falso. |
Remove o erro especificado pelo ID da página.
|
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.
|
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.
|
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.
- google.visualization.events.addListener() e google.visualization.events.addOneTimeListener() detectam eventos.
- google.visualization.events.removeListener() remove um listener existente.
- google.visualization.events.removeAllListeners() remove todos os listeners de um gráfico específico.
- google.visualization.events.trigger() dispara um evento.
addListener().
Chame esse método para se registrar 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.
- Construtor
- draw();
- getAction() [opcional]
- getSelection() [opcional]
- removeAction() [opcional]
- setAction() [opcional]
- setSelection() [opcional]
Observação: esses métodos estão no namespace da visualização, não no namespace google.visualization.
Construtor
O construtor precisa ter o nome da 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
ouDataView
que contém os dados a serem usados para desenhar o gráfico. Não há um método padrão para extrair umDataTable
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
ecolumn
são o número de linhas ou colunas de um item na tabela de dados a ser selecionado. Para selecionar uma coluna inteira, definarow
como nulo. Para selecionar uma linha inteira, definacolumn
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.