Papéis da coluna

Nesta página, descrevemos o conceito e o uso de papéis em tabelas de dados de gráficos.

  1. O que são papéis?
  2. Quais funções estão disponíveis?
  3. Hierarquia de papéis e associação
  4. 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
  • anotação
  • anotaçãoText
  • anotação
  • anotaçãoText
  • certo
  • ênfase
  • interval
  • escopo
  • style
  • dica
  • anotação
  • anotaçãoText
  • certo
  • ênfase
  • interval
  • escopo
  • style
  • dica

 

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.

  • As colunas de annotation especificam os rótulos estáticos no gráfico. Aqui, "A", "B" e "C" são anotações.
  • As colunas annotationText especificam ao passar o cursor sobre a anotação (não o ponto de dados).
  • As colunas de intervalo especificam as extremidades superior e inferior das barras de barras no gráfico. Há três barras de I no gráfico.
  • As colunas certeza indicam se os dados naquele momento estão corretos. O último ponto de dados está incerto, portanto, a linha que o leva a ele está pontilhada.

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: annotations: {'column_id': {style: 'line'}}

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:

  • color
  • opacity
  • stroke-width
  • stroke-color
  • stroke-opacity
  • fill-color
  • fill-opacity

Tipo de dado: string, em que vários estilos podem ser aplicados usando uma sintaxe 'firstProperty: value; secondProperty: value' ou defina estilos específicos para bar, line, e point especificando o tipo e encapsulando as propriedades de estilo dentro de chaves (por exemplo, bar { //properties go here }).

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 style. Os estilos podem ser definidos para pontos, linhas ou barras especificamente (consulte a linha do Homem-Aranha) ou geralmente, que vão aplicar os estilos a todos os pontos, linhas e barras, dependendo do tipo de gráfico.

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.