Nesta página, descrevemos o conceito e o uso de papéis nas tabelas de dados dos gráficos.
- O que são papéis?
- Quais funções estão disponíveis?
- Hierarquia e associação de papéis
- Como atribuir uma função
O que são papéis?
Os objetos DataTable e DataView do Google agora aceitam papéis de coluna explicitamente atribuídos. Um papel de coluna descreve a finalidade dos dados nessa coluna: por exemplo, uma coluna pode conter dados que descrevem texto de dica, anotações de ponto de dados ou indicadores de incerteza. A maioria dos papéis de coluna se aplica à coluna "data" que a precede, seja imediatamente antes dela ou antes da primeira de um grupo consecutivo de colunas de papel. Por exemplo, é possível ter duas colunas após uma coluna "data", uma para "tooltip" e outra para "annotation". Mas, seguindo a coluna "domain", também geralmente permitimos os papéis das colunas "annotation" e "annotationText".
Observação: se você quer controlar o conteúdo das dicas que aparecem quando o usuário passa o cursor sobre um gráfico, consulte Dicas.
Originalmente, havia apenas duas funções disponíveis para uma coluna: "domain", que especifica os principais valores do eixo, e "data", que especifica a altura das barras, larguras das fatias da pizza e assim por diante. Esses papéis foram atribuídos implicitamente, com base na ordem e no tipo das colunas da tabela. No entanto, com a capacidade de atribuir explicitamente os papéis de coluna, é possível adicionar colunas opcionais que fornecem recursos novos e interessantes a um gráfico, como rótulos de anotação arbitrários, texto de passar o cursor e barras de incerteza.
Se você não atribuir explicitamente o papel de uma coluna, o papel dela será inferido pela ordem da coluna na tabela, de acordo com a especificação de formato de dados do gráfico. Esta página mostra quais papéis estão disponíveis para você atribuir explicitamente e como fazer isso.
Veja uma comparação do que é possível fazer com um gráfico de linhas usando apenas os papéis padrão inferidos e outros papéis explicitamente atribuídos.
Formato da tabela de dados do gráfico de linhas:
| Coluna 0 | Coluna 1 | ... | Coluna N | |
|---|---|---|---|---|
| Finalidade | Valores da linha 1 | ... | Valores da linha N | |
| Tipo de dados | number | ... | number | |
| Papel | domínio | dados | ... | dados |
| Papéis de coluna compatíveis opcionais |
|
|
... |
|
| Gráfico sem papéis de coluna explícitas | Gráfico com papéis de coluna explícita |
|---|---|
|
|
|
Este gráfico não aplica papéis explicitamente e, portanto, só pode usar os dados básicos e o layout de coluna do domínio mostrados acima. Tabela de dados: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addRows([
['April',1000],
['May', 1170],
['June', 660],
['July', 1030]
]); |
Este gráfico atribui papéis explicitamente e, portanto, as colunas opcionais podem ser adicionadas. Este gráfico tem colunas opcionais para os papéis de anotação, anotaçãoText, intervalo e certeza.
Tabela de dados: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'string', role:'annotation'}); // annotation role col.
data.addColumn({type:'string', role:'annotationText'}); // annotationText col.
data.addColumn({type:'boolean',role:'certainty'}); // certainty col.
data.addRows([
['April',1000, 900, 1100, 'A','Stolen data', true],
['May', 1170, 1000, 1200, 'B','Coffee spill', true],
['June', 660, 550, 800, 'C','Wumpus attack', true],
['July', 1030, null, null, null, null, false]
]); |
Quais funções estão disponíveis?
A tabela a seguir lista todos os papéis com suporte do Google Charts. Nem todos os papéis são compatíveis com todos os tipos de gráficos. A documentação de cada gráfico descreve quais papéis estão disponíveis e para onde eles estão. Os papéis são renderizados de maneiras diferentes para cada tipo de gráfico.
| Papel | Descrição | Exemplo |
|---|---|---|
| anotação | Texto a ser exibido no gráfico próximo ao ponto de dados associado. O texto é exibido sem qualquer interação do usuário. As anotações e o texto da anotação podem ser atribuídos a pontos de dados e categorias (rótulos de eixo). Há dois estilos de anotações: ponto (default), que desenha o texto da anotação perto do ponto especificado, e linha, que desenha o texto da anotação em uma linha que corta a área do gráfico. É possível especificar o estilo da linha definindo esta opção de gráfico: Tipo de dado: string Padrão: string vazia |
Dados: label3: 'Ano', 'Vendas', nulo, nulo, 'Despesas', nulo, nulo,
role: domínio, dados, anotação, anotação, dados, anotação, anotação, '2004', 1000, nulo, nulo, 400, nulo, nulo,
'2005', nulo, 1170, nulo, nulo '0', 1170, nulo, nulo, '0'
Os "A" e "B" neste gráfico são anotações. Passe o cursor sobre a anotação para ver o texto dela. Observe que você precisa passar o cursor sobre a anotação, não sobre o ponto de dados a que ela é aplicada, para exibir o valor annotationText. Valores nulos são aceitos para células de anotação e de anotaçãoText. No entanto, se você tiver um valor deannotationText, vai precisar de um valor de anotação associado. |
| annotationText | Texto estendido a ser exibido quando o usuário passa o cursor sobre a anotação associada. Anotações e texto da anotação podem ser atribuídos a pontos de dados e categorias (rótulos de eixo). Se você tiver uma colunaAnnotationText, também precisa ter uma coluna de anotação. Já o texto da dica é exibido quando o usuário passa o cursor sobre o ponto de dados associado no gráfico. Tipo de dado: string Padrão: string vazia |
|
| certeza | Indica se um ponto de dados é certo ou não. A forma como ela é exibida depende do tipo de gráfico. Por exemplo, linhas tracejadas ou preenchimento listrado podem aparecer. Nos gráficos de linhas e de área, o segmento entre dois pontos de dados será determinado se e somente se ambos os pontos de dados forem determinados. Tipo de dados: booleano, em que "true" é certo, "false" é incerto. Padrão: true |
|
| ênfase | Enfatiza pontos de dados especificados no gráfico. Exibida como uma linha grossa e/ou um ponto grande. Nos gráficos de linhas e de área, o segmento entre dois pontos de dados será destacado somente se ambos os pontos de dados forem enfatizados. Tipo de dado: booleano Padrão: false |
Dados: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, emphasis, data, emphasis
'2004', 1000, true, 400, false
'2005', 1170, true, 460, true
'2006', 660, false, 1120, true
'2007', 1030, false, 540, true
Neste gráfico, a série "Vendas" tem um segmento em destaque, designado pela coluna três, linhas um e dois. A série "Despesas" possui dois segmentos enfatizados, designados pela quinta coluna, pelas linhas dois, três e quatro. Observe como a ênfase exige que ambos os pontos delimitadores sejam enfatizados. |
| intervalo | Indica o possível intervalo de dados para um ponto específico. Os intervalos geralmente são exibidos como indicadores de intervalo de estilo da barra I. As colunas de intervalo são numéricas. Adicione colunas de intervalo em pares, marcando os valores baixo e alto da barra. Os valores de intervalo precisam ser adicionados em ordem crescente, da esquerda para a direita. Tipo de dados: número Padrão: sem intervalo |
Dados: label: 'Day', 'Stock value', null, null
role: domain, data, interval, interval
'Mon', 38, 20, 45
'Tue', 55, 31, 66
'Wed', 77, 50, 80
'Thurs', 66, 50, 77
Neste gráfico, os valores de intervalo definem uma barra I em torno dos pontos. Os valores aumentam da esquerda para a direita. Os intervalos mais altos e mais baixos em torno de um ponto marcam as partes superior e inferior da barra. Observação: para todos os detalhes sobre intervalos, consulte Intervalos. |
| escopo | Indica se um ponto está dentro ou fora do escopo. Se um ponto estiver fora do escopo, ele terá menos ênfase visualmente. Nos gráficos de linhas e de área, o segmento entre dois pontos de dados vai estar no escopo se um endpoint estiver no escopo. Tipo de dado: booleano, em que "true" significa no escopo. Padrão: true |
Dados: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, scope, data, scope
'2004', 1000, false, 400, true
'2005', 1170, false, 460, false
'2006', 660, true, 1120, false
'2007', 1030, true, 540, false
A primeira coluna de escopo se aplica à coluna de dados "Vendas" à esquerda. O primeiro segmento é renderizado fora do escopo porque os dois pontos de limite estão fora do escopo. A segunda coluna de escopo se aplica à coluna de dados "Despesas" à esquerda. O primeiro segmento é marcado como no escopo porque um dos pontos de limite está no escopo. O restante da linha está fora do escopo porque todos os outros pontos estão marcados como fora do escopo. |
| estilo |
Estiliza certas propriedades de diferentes aspectos dos dados. Esses valores são:
Tipo de dados: string, em que vários estilos podem ser aplicados usando uma sintaxe Padrão: nulo |
Dados:
label: 'Character', 'Popularity', 'Style',
role: domain, data, style,
'Hulk', 50, 'color: green',
'Captain America', 75, 'color: #0000cf;' +
'stroke-color: #cf001d',
'Wolverine', 90, 'opacity: 0.5;' +
'stroke-width: 5;' +
'stroke-color: #01a0ff;' +
'fill-color: #fff600',
'Iron Man', 60, 'color: #db9500;' +
'stroke-width: 10;' +
'stroke-color: #a30300',
'Spider Man', 100, 'bar {' +
'fill-color: #c8001d;' +
'stroke-width: 3;' +
'stroke-color: #1800c8}'
Neste gráfico, o estilo de cada barra é independente das outras usando o papel de coluna Observação: há mais detalhes documentados sobre como personalizar o estilo de pontos, linhas e barras. Confira também opções para cada tipo de gráfico em que é possível especificar estilos para outros tipos de entidades, como áreas, texto e caixas. |
| dica |
Texto a ser exibido quando o usuário passa o cursor sobre o ponto de dados associado a essa linha. Observação: isso não é compatível com a visualização do gráfico de bolhas. O conteúdo das dicas de HTML do gráfico de bolhas não é personalizável. Tipo de dado: string Padrão: valor do ponto de dados |
Dados: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, tooltip, data, tooltip
'2004', 1000, '1M$ sales, 400, '$0.4M expenses
in 2004' in 2004'
'2005', 1170, '1.17M$ sales, 460, '$0.46M expenses
in 2005' in 2005'
'2006', 660, '.66$ sales, 1120, '$1.12M expenses
in 2006' in 2006'
'2007', 1030, '1.03M$ sales, 540, '$0.54M expenses
in 2007' in 2007'
Passe o cursor sobre os pontos de dados para mostrar o texto da dica. Os dados da dica são atribuídos a todos os pontos nas duas linhas, nas colunas 3 e 5. Observação: para mais detalhes sobre como personalizar dicas, consulte Dicas. |
| domínio | Não é necessário atribuir esse papel explicitamente, a menos que você crie um gráfico de vários domínios (mostrado aqui). O formato básico da tabela de dados permite que o mecanismo de gráficos infera quais colunas são de domínio. No entanto, você deve estar ciente de quais colunas são colunas de domínio para que você saiba quais outras colunas podem modificá-las. As colunas de domínio especificam rótulos ao longo do maior eixo do gráfico. Às vezes, colunas com vários domínios podem ser usadas para suportar várias escalas no mesmo gráfico. Tipo de dados: normalmente string, mas ocasionalmente número ou data |
Dados:
label: '2009, '2009, '2009, '2008, '2008 '2008
Quarter', Sales', Expenses', Quarter', Sales', Expenses'
role: domain, data, data, domain, data, data
'Q1/09', 1000, 400, 'Q1/08', 800, 300
'Q2/09', 1170, 460, 'Q2/08', 750, 400
'Q3/09', 660, 1120, 'Q3/08', 700, 540
'Q4/09', 1030, 540, 'Q4/08', 820, 620
Este exemplo demonstra um gráfico com vários domínios. As duas primeiras colunas de dados modificam o primeiro domínio ("2009 Quarter") e as duas últimas modificam o segundo domínio ("2008 Quarter"). Os dois domínios estão sobrepostos nas escalas do mesmo eixo. |
| dados | Não é necessário atribuir esse papel explicitamente. O formato básico da tabela de dados permite que o mecanismo de gráficos infera quais colunas são de domínio. No entanto, você precisa estar ciente de quais colunas são colunas de dados para que você saiba quais outras colunas podem modificá-las. As colunas de papel de dados especificam os dados da série a serem renderizados no gráfico. Para a maioria dos gráficos, uma coluna = uma série, mas isso pode variar de acordo com o tipo de gráfico (por exemplo, os gráficos de dispersão exigem duas colunas de dados para a primeira série e mais uma para cada série adicional. Os gráficos candlestick exigem quatro colunas de dados para cada série). Tipo de dados: número |
Hierarquia e associação de papéis
O diagrama a seguir mostra quais colunas de papéis podem ser aplicadas a quais outras colunas de papéis. Todas as colunas, exceto as de domínio, se aplicam ao vizinho esquerdo mais próximo a que ela pode ser aplicada.
Assim, por exemplo, uma coluna scope se aplica à coluna data mais próxima à esquerda, uma coluna annotationText será aplicada à coluna annotation mais próxima à esquerda dela, e annotation será aplicada à coluna data ou domain mais próxima à esquerda.
Como atribuir uma função
Os papéis são atribuídos como uma propriedade da coluna em um objeto DataTable. Há várias maneiras de criar uma coluna de papel, mas estas são as mais comuns:
As duas primeiras técnicas desenham o seguinte gráfico:
Método DataTable.addColumn
O exemplo a seguir cria um gráfico de barras com um marcador de intervalo em três das barras. Os marcadores de intervalo são especificados pela terceira e quarta colunas com o método DataTable.addColumn().
var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain column.
data.addColumn('number', 'Sales'); // Implicit data column.
data.addColumn({type:'number', role:'interval'});
data.addColumn({type:'number', role:'interval'});
data.addColumn('number', 'Expenses');
data.addRows([
['April',1000, 900, 1100, 400],
['May', 1170, 1000, 1200, 460],
['June', 660, 550, 800, 1120],
['July', 1030, , , 540]
]);
var chart = new google.visualization.BarChart(
document.getElementById('visualization'));
chart.draw(data,
{width: 800, height: 600, title: 'Company Performance'});
Notação literal do JavaScript
No literal JSON, é preciso especificar uma propriedade p da coluna com o valor "role":"role-type".
O exemplo a seguir demonstra como especificar papéis usando a notação literal JavaScript. Isso só pode ser feito no momento da criação da tabela.
{"cols":[
{"id":"","label":"Month","pattern":"","type":"string"},
{"id":"","label":"Sales","pattern":"","type":"number"},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"Expenses","pattern":"","type":"number"}],
"rows":[
{"c":[
{"v":"April","f":null},
{"v":1000,"f":null},
{"v":900,"f":null},
{"v":1100,"f":null},
{"v":400,"f":null}]},
{"c":[
{"v":"May","f":null},
{"v":1170,"f":null},
{"v":1000,"f":null},
{"v":1200,"f":null},
{"v":460,"f":null}]},
{"c":[{"v":"June","f":null},
{"v":660,"f":null},
{"v":550,"f":null},
{"v":800,"f":null},
{"v":1120,"f":null}]},
{"c":[
{"v":"July","f":null},
{"v":1030,"f":null},
{"v":null,"f":null},
{"v":null,"f":null},
{"v":540,"f":null}]}],
"p":null
}
Método DataView.setColumns
Ao criar uma visualização, é possível definir explicitamente o papel de uma coluna. Isso é útil ao criar uma nova coluna calculada. Consulte DataView.setColumns() para mais informações.