Nesta página, descrevemos o conceito e o uso de papéis em tabelas de dados de gráficos.
- O que são papéis?
- Quais funções estão disponíveis?
- Hierarquia de papéis e associação
- Como atribuir um papel
O que são papéis?
Agora os objetos DataTable e DataView do Google são compatíveis com papéis de coluna atribuídos explicitamente. Um papel de coluna descreve a finalidade dos dados nessa coluna: por exemplo, uma coluna pode conter dados que descrevem o texto da dica, anotações de ponto de dados ou indicadores de incerteza. A maioria dos papéis de coluna se aplica à coluna de dados que o precede, seja imediatamente antes dela ou antes do primeiro de um grupo consecutivo de colunas de papéis. Por exemplo, é possível ter duas colunas após uma coluna de "dados", uma para "dica" e outra para "anotação". Mas após a coluna "domain", também permitimos os papéis da coluna "annotation" e "annotationText".
Observação: se você quiser controlar o conteúdo das dicas que aparecem quando o usuário passa o cursor sobre um gráfico, consulte Dicas.
Originalmente, havia apenas dois papéis disponíveis para uma coluna: "domain", que especifica os principais valores do eixo, e "data", que especifica a altura da barra, a largura das fatias da pizza e assim por diante. Esses papéis eram atribuídos implicitamente, com base na ordem e no tipo das colunas na tabela. No entanto, com a capacidade de atribuir explicitamente papéis de colunas, é possível adicionar colunas opcionais que fornecem recursos novos e interessantes a um gráfico, como rótulos de anotação arbitrários, texto flutuante e barras de incerteza.
Se você não atribuir explicitamente o papel de uma coluna, ele será inferido pela ordem da coluna na tabela, de acordo com a especificação do formato de dados do gráfico. Nesta página, você verá quais papéis estão disponíveis para serem atribuídos de maneira explícita 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, em comparação com outros papéis atribuídos explicitamente.
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 dado | number | … | number | |
Papel | domínio | dados | … | dados |
Papéis de coluna compatíveis opcionais |
|
|
… |
|
Gráfico sem papéis de coluna explícitos | Gráfico com papéis de coluna explícitos |
---|---|
|
|
Este gráfico não aplica papéis de forma explícita. Portanto, só é possível usar o layout básico das colunas de dados e domínios mostrado 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] ]); |
Esse gráfico atribui papéis de maneira explícita. Dessa forma, é possível adicionar as colunas opcionais. Este gráfico tem colunas opcionais para 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 compatíveis com os gráficos do Google. 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 sã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 nenhuma interação do usuário. As anotações e o texto 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 próximo ao ponto especificado, e linha, que mostra o texto da anotação em uma linha que cruza a área do gráfico. É possível especificar o estilo de linha
definindo esta opção de gráfico: Tipo de dado: string Padrão: string vazia |
Dados: label: 'Ano', 'Vendas', nulo, nulo, 'Despesas', nulo, nulo
role: domínio, dados, anotação, anotaçãoText, dados, anotação, anotaçãoText
'2004', 1000, nulo, nulo, 400, nulo, nulo, nulo, '2', '2', '2'
"A" e "B" neste gráfico são anotações. Passe o cursor sobre a anotação para ver o texto. É necessário passar o cursor sobre a anotação, não o ponto de dados a que ela é aplicada, para exibir o valor de anotaçõesText. Valores nulos são aceitos para células de anotação e anotaçãoText. No entanto, se você tiver um valor de anotaçãoText, precisará ter um valor de anotação associado. |
annotationText (link em inglês) | Texto estendido a ser exibido quando o usuário passa o cursor sobre a anotação associada. As anotações e o texto das anotações podem ser atribuídos a pontos de dados e categorias (rótulos de eixos). Se você tem uma coluna de anotaçãoText, também precisa ter uma coluna de anotação. O texto da dica, por outro lado, é 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 de exibição depende do tipo de gráfico. Por exemplo, isso pode ser indicado por linhas tracejadas ou um preenchimento listrado. Nos gráficos de linhas e áreas, o segmento entre os dois pontos de dados é certo apenas se os dois pontos de dados forem determinados. Tipo de dado: booleano, em que verdadeiro é determinado, falso é incerto. Padrão: true |
|
ênfase | Enfatiza pontos de dados do gráfico especificados. Exibida como uma linha grossa e/ou um ponto grande. Nos gráficos de linhas e áreas, o segmento entre dois pontos de dados é enfatizado somente se os dois pontos de dados são destacados. 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 Nesse gráfico, a série "Vendas" tem um segmento em destaque, designado pela coluna três, linhas um e dois. A série "Gastos" tem dois segmentos enfatizados, designados pela quinta coluna, linhas dois, três e quatro. Observe como a ênfase exige que os dois pontos delimitadoras sejam enfatizados. |
intervalo | Indica um possível intervalo de dados para um ponto específico. Os intervalos geralmente são exibidos como indicadores de intervalo de estilo da barra de I. As colunas de intervalo são colunas numéricas. Adicione colunas de intervalo em pares, marcando o valor baixo e alto da barra. Os valores de intervalo precisam ser adicionados em valor crescente, da esquerda para a direita. Tipo de dado: 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 do intervalo definem uma barra de I ao redor 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 de cima e de baixo da barra. Observação: para ver 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 será visualmente desencorajado. Para gráficos de linhas e áreas, o segmento entre dois pontos de dados estará no escopo se um dos endpoints 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 do escopo se aplica à coluna de dados "Gastos" à esquerda. O primeiro segmento está 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. |
style |
Estiliza determinadas propriedades de diferentes aspectos dos dados. Esses valores são:
Tipo de dado: 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, cada barra é estilizada independente das outras usando o papel de coluna Observação: mais detalhes estão documentados em outro lugar sobre como personalizar o estilo de pontos, linhas e barras. Veja também as opções de cada tipo de gráfico em que os estilos podem ser especificados para outros tipos de entidades, como áreas, texto e caixas. |
dica |
Texto a ser exibido quando o usuário passar 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 para o gráfico de círculos 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 exibir o texto da dica. Os dados de dicas 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 de ferramentas, consulte Dicas. |
domínio | Não é necessário atribuir esse papel explicitamente, a menos que você projete 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 reconheça quais colunas são de domínio. No entanto, é necessário estar ciente de quais colunas são de domínio para que possa saber quais outras podem modificá-la. As colunas do domínio especificam rótulos ao longo do eixo principal do gráfico. Às vezes, é possível usar várias colunas de domínio para aceitar várias escalas no mesmo gráfico. Tipo de dado: geralmente string, mas, às vezes, 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 de vários domínios. As duas primeiras colunas de dados modificam o primeiro domínio ("2009 trimestre"), e as duas últimas colunas de dados modificam o segundo domínio ("2008 trimestre"). Ambos os domínios estão sobrepostos nas mesmas escalas de 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 inferir quais colunas são colunas de domínio. No entanto, é necessário estar ciente de quais colunas são colunas de dados para que você saiba quais outras colunas podem modificá-la. As colunas de papel de dados especificam os dados de série a serem renderizados no gráfico. Para a maioria dos gráficos, uma coluna = uma série, mas isso varia 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 uma adicional para cada série adicional. Os gráficos de velas exigem quatro colunas de dados para cada série. Tipo de dado: número |
Hierarquia e associação de papéis
O diagrama a seguir mostra as colunas de papel que podem ser aplicadas a outras. Todas as colunas, exceto as de domínio, se aplicam ao vizinho mais próximo à esquerda a que ela pode ser aplicada.
Por exemplo, uma coluna scope se aplica à coluna data mais próxima à esquerda. Uma coluna annotationText será aplicada à coluna annotation mais próxima à esquerda, uma annotation será aplicada à coluna data ou domain mais próxima à esquerda.
Como atribuir um papel
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 gráfico a seguir:
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 usando 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, é necessário 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 de 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.setColunas
Ao criar uma visualização, é possível definir explicitamente a função de uma coluna. Isso é útil ao criar uma nova coluna calculada. Consulte DataView.setColumns()
para mais informações.