Gráfico de anotações

  1. Visão geral
  2. Exemplo
  3. Carregando
  4. Formato de dados
  5. Opções de configuração
  6. Métodos
  7. Eventos
  8. Política de dados
  9. Notes

Visão geral

Os gráficos de anotação são gráficos de linhas de série temporal interativos com suporte a anotações. Observe que a linha do tempo anotada agora usa o gráfico de anotações automaticamente.

Alerta de confusão:no momento, o gráfico de anotações do Google é diferente das anotações que outros gráficos do Google aceitam (área, barras, colunas, combinações, linhas e dispersão). Nesses gráficos, as anotações são especificadas em uma coluna separada da tabela de dados e exibidas como trechos de texto curtos sobre os quais os usuários podem passar o cursor para conferir o texto completo da anotação. Já o gráfico de anotações mostra as anotações completas no lado direito, conforme mostrado abaixo.

Exemplo

 
<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type='text/javascript'>
      google.charts.load('current', {'packages':['annotationchart']});
      google.charts.setOnLoadCallback(drawChart);

      function drawChart() {
        var data = new google.visualization.DataTable();
        data.addColumn('date', 'Date');
        data.addColumn('number', 'Kepler-22b mission');
        data.addColumn('string', 'Kepler title');
        data.addColumn('string', 'Kepler text');
        data.addColumn('number', 'Gliese 163 mission');
        data.addColumn('string', 'Gliese title');
        data.addColumn('string', 'Gliese text');
        data.addRows([
          [new Date(2314, 2, 15), 12400, undefined, undefined,
                                  10645, undefined, undefined],
          [new Date(2314, 2, 16), 24045, 'Lalibertines', 'First encounter',
                                  12374, undefined, undefined],
          [new Date(2314, 2, 17), 35022, 'Lalibertines', 'They are very tall',
                                  15766, 'Gallantors', 'First Encounter'],
          [new Date(2314, 2, 18), 12284, 'Lalibertines', 'Attack on our crew!',
                                  34334, 'Gallantors', 'Statement of shared principles'],
          [new Date(2314, 2, 19), 8476, 'Lalibertines', 'Heavy casualties',
                                  66467, 'Gallantors', 'Mysteries revealed'],
          [new Date(2314, 2, 20), 0, 'Lalibertines', 'All crew lost',
                                  79463, 'Gallantors', 'Omniscience achieved']
        ]);

        var chart = new google.visualization.AnnotationChart(document.getElementById('chart_div'));

        var options = {
          displayAnnotations: true
        };

        chart.draw(data, options);
      }
    </script>
  </head>

  <body>
    <div id='chart_div' style='width: 900px; height: 600px;'></div>
  </body>
</html>

Carregando

O nome do pacote google.charts.load é "annotationchart".

  google.charts.load("current", {packages: ['annotationchart']});

O nome da classe da visualização é google.visualization.AnnotationChart.

  var visualization = new google.visualization.AnnotationChart(container);

Formato de dados

Você pode mostrar uma ou mais linhas no gráfico. Cada linha representa uma posição X no gráfico, ou seja, um tempo específico, e cada linha é descrita por um conjunto de uma a três colunas.

  • A primeira coluna é do tipo date ou datetime e especifica o valor X do ponto no gráfico. Se essa coluna for do tipo date (e não datetime), a menor resolução de tempo no eixo X será de um dia.
  • Cada linha de dados é descrita por um conjunto de uma a três colunas extras, conforme descrito aqui:
    • Valor Y - [obrigatório, número] A primeira coluna em cada conjunto descreve o valor da linha no momento correspondente da primeira coluna. O rótulo da coluna é exibido no gráfico como o título da linha.
    • Título da anotação: [opcional, string] se uma coluna de string seguir a coluna de valor e a opção displayAnnotations for verdadeira, essa coluna terá um título curto que descreve esse ponto. Por exemplo, se essa linha representa a temperatura no Brasil e esse ponto é um número muito alto, o título pode ser "Dia mais quente registrado".
    • Texto de anotação: [string opcional] se houver uma segunda coluna de string para essa série, o valor da célula será usado como texto descritivo adicional para esse ponto. Defina a opção displayAnnotations como verdadeira para usar essa coluna. Você pode usar tags HTML se definir allowHtml como true. Basicamente, não há limite de tamanho, mas entradas excessivamente longas podem estourar a seção de exibição. Não é necessário ter essa coluna, mesmo que você tenha uma coluna de título de anotação para este ponto. O rótulo da coluna não é usado pelo gráfico. Por exemplo, se este foi o dia mais quente no ponto recorde, você pode dizer algo como "O dia mais próximo estava 10 graus mais frio!".

Opções de configuração

Nome
allowHtml

Se definido como verdadeiro, qualquer texto de anotação que inclua tags HTML será renderizado como HTML.

Tipo: booleano
Padrão:false
allValuesSuffix

Um sufixo a ser adicionado a todos os valores na legenda e nos rótulos de marcação nos eixos verticais.

Tipo: string
Padrão:nenhum
annotationsWidth

A largura (em porcentagem) da área de anotações em relação a toda a área do gráfico. Precisa ser um número no intervalo de 5 a 80.

Tipo: número
Padrão:25
cores

As cores a serem usadas para as linhas e rótulos do gráfico. Uma matriz de strings. Cada elemento é uma string em um formato de cor HTML válido. Por exemplo, "red" ou "#00cc00".

Tipo:matriz de strings
Padrão:cores padrão
dateFormat

O formato usado para exibir as informações de data no canto superior direito. O formato desse campo é o especificado pela classe java SimpleDateFormat.

Tipo: string
Padrão: "MMMM dd, aaaa" ou "HH:mm MMMM dd, aaaa", dependendo do tipo da primeira coluna (data ou data/hora, respectivamente).
displayAnnotations

Se ela for definida como falsa, o gráfico ocultará a tabela de anotações e as anotações e annotationText não ficarão visíveis (a tabela de anotações também não será exibida se não houver anotações nos dados, independentemente dessa opção). Quando essa opção é definida como verdadeira, depois de cada coluna numérica, duas colunas opcionais de string de anotação podem ser adicionadas, uma para o título da anotação e outra para o texto da anotação.

Tipo: booleano
Padrão:true
displayAnnotationsFilter

Se ela for definida como verdadeira, o gráfico vai mostrar um controle de filtros para filtrar as anotações. Use essa opção quando houver muitas anotações.

Tipo: booleano
Padrão:false
displayDateBarSeparator

Define se um separador de barra pequeno ( | ) será mostrado entre os valores da série e a data na legenda, em que "true" significa sim.

Tipo: booleano
Padrão:true
displayExactValues

Indica se uma versão arredondada e reduzida dos valores na parte superior do gráfico será exibida para economizar espaço. "false" indica que pode ser.Por exemplo, se definido como falso, 56.123, 45 poderá ser exibido como 56, 12k.

Tipo: booleano
Padrão:false
displayLegendDots

Indica se pontos ao lado dos valores no texto da legenda serão exibidos, em que "true" significa sim.

Tipo: booleano
Padrão:true
displayLegendValues

Indica se os valores destacados serão exibidos na legenda, em que verdadeiro significa sim.

Tipo: booleano
Padrão:true
displayRangeSelector

Indica se a área de seleção do intervalo de zoom será exibida (a área na parte de baixo do gráfico), em que "false" significa que não.

O contorno no seletor de zoom é uma versão em escala logarítmica da primeira série no gráfico, dimensionada para se ajustar à altura do seletor de zoom.

Tipo: booleano
Padrão:true
displayZoomButtons

Indica se os botões de zoom serão mostrados ("1d 5d 1m" e assim por diante), em que "false" significa não.

Tipo: booleano
Padrão:true
fill

Um número de 0 a 100 (inclusive) especificando o alfa do preenchimento abaixo de cada linha no gráfico de linhas. 100 significa 100% opaco e 0 significa nenhum preenchimento. A cor de preenchimento é a mesma cor da linha acima dela.

Tipo: número
Padrão:0
legendPosition

Define se a legenda colorida será colocada na mesma linha com os botões de zoom e a data ("sameRow") ou em uma nova linha ("newRow").

Tipo: string
Padrão: "sameRow"
max

O valor máximo a ser exibido no eixo Y. Se o ponto de dados máximo exceder esse valor, essa configuração será ignorada, e o gráfico será ajustado para mostrar a próxima marca de seleção acima do ponto máximo. Isso terá precedência sobre o máximo do eixo Y determinado por scaleType.

Esse número é semelhante ao maxValue nos gráficos principais.

Tipo: número
Padrão:automático
min

O valor mínimo a ser exibido no eixo Y. Se o ponto mínimo de dados for menor que esse valor, essa configuração será ignorada, e o gráfico será ajustado para mostrar a próxima marca de seleção abaixo do ponto mínimo. Isso terá precedência sobre o mínimo do eixo Y determinado por scaleType.

Esse número é semelhante ao minValue nos gráficos principais.

Tipo: número
Padrão:automático
numberFormats

Especifica os padrões de formato de número a serem usados para formatar os valores na parte superior do gráfico.

Os padrões precisam estar no formato especificado pela classe java DecimalFormat.

  • Se não for especificado, será usado o padrão de formato.
  • Se um único padrão de string for especificado, ele será usado para todos os valores.

  • Se um mapa for especificado, as chaves serão índices de séries (base zero) e os valores serão os padrões a serem usados para formatar a série especificada.

    Você não precisa incluir um formato para cada série no gráfico. Qualquer série não especificada usará o formato padrão.

Se essa opção for especificada, a opção displayExactValues será ignorada.

Tipo:string ou um mapa de pares número:string
Padrão:automático
scaleColumns

Especifica os valores que serão mostrados nas marcas de escala do eixo Y no gráfico. O padrão é ter uma única escala no lado direito, o que se aplica a ambas as séries. No entanto, você pode ter lados diferentes do gráfico dimensionados para diferentes valores de série.

Essa opção usa uma matriz de zero a três números que especificam o índice (baseado em zero) da série a ser usada como o valor de escalonamento. O local em que esses valores são mostrados depende de quantos valores você inclui na matriz:

  • Se você especificar uma matriz vazia, o gráfico não vai mostrar os valores de Y ao lado das marcações.
  • Se você especificar um valor, a escala da série indicada será exibida somente no lado direito do gráfico.
  • Se você especificar dois valores, a escala da segunda série será adicionada à direita do gráfico.
  • Se você especificar três valores, uma escala para a terceira série será adicionada ao meio do gráfico.
  • Todos os valores após o terceiro na matriz serão ignorados.

Ao exibir mais de uma escala, é aconselhável definir a opção scaleType como "allFixed" ou "allmaximized".

Tipo:matriz de números
Padrão:automático
scaleFormat

Formato de número a ser usado para os rótulos das escalas do eixo. O padrão de '#' é mostrado como um número inteiro.

Tipo: string
Padrão: '#'
scaleType

Define os valores máximo e mínimo mostrados no eixo Y. As seguintes opções estão disponíveis:

  • "maximizado" - o eixo Y abrangerá do mínimo aos valores máximos da série. Se você tiver mais de uma série, use allmaximized.
  • "fixo" [padrão]: o eixo Y varia, dependendo dos valores dos dados:
    • Se todos os valores forem >=0, o eixo Y abrangerá de zero até o valor máximo dos dados.
    • Se todos os valores forem <=0, o eixo Y abrangerá de zero até o valor mínimo de dados.
    • Se os valores forem positivos e negativos, o eixo Y variará do máximo da série para o mínimo da série.
      Para várias séries, use "allFixed".
  • "allmaximized": igual a "maximized", mas usado quando várias escalas são exibidas. Os dois gráficos serão maximizados na mesma escala, o que significa que um deles será deturpado em relação ao eixo Y, mas o valor real de cada série será exibido ao passar o cursor sobre cada série.
  • "allfixo": o mesmo que "fixo", mas usado quando várias escalas são exibidas. Essa configuração ajusta cada escala à série a que ela se aplica (use em conjunto com scaleColumns).

Se você especificar as opções mínima e/ou máxima, elas terão precedência sobre os valores mínimo e máximo determinados pelo seu tipo de escala.

Tipo: string
Padrão: "fixo"
table

Contém opções relacionadas à tabela de anotações. Para especificar as propriedades desse objeto, use a notação literal de objeto: 

var options: {
  table: {
    sortAscending: true,
    sortColumn: 1
  }
};
Tipo: objeto
Padrão:nulo
table.sortAscending

Se definido como true, inverte a ordem da tabela de anotações e as exibe em ordem crescente.

Tipo: booleano
Padrão:false
table.sortColumn

O índice de colunas da tabela de anotações em que as anotações serão classificadas. O índice precisa ser 0 para a coluna de rótulo da anotação ou 1 para a coluna de texto da anotação.

Tipo: número
Padrão:0
espessura

Um número de 0 a 10 (inclusive) especificando a espessura das linhas, em que 0 é a mais fina.

Tipo: número
Padrão:0
zoomEndTime

Define a data/hora de término do intervalo de zoom selecionado.

Tipo: data
Padrão:nenhum
zoomStartTime

Define a data/hora de início do intervalo de zoom selecionado.

Tipo: data
Padrão:nenhum

Métodos

Método
clearChart()

Limpa o gráfico e libera todos os recursos alocados.

Return Type: nenhum
draw(data, options, state)

Desenha o gráfico.

Return Type: nenhum
getContainer()

Recupera um handle para o elemento de contêiner que contém o gráfico de anotação.

Tipo de retorno: identificador para um elemento DOM
getSelection()

Implementação padrão de getSelection(). Os elementos selecionados são elementos de célula. Apenas uma célula pode ser selecionada por vez pelo usuário.

Tipo de retorno:matriz de elementos de seleção
getVisibleChartRange()

Retorna um objeto com as propriedades start e end, sendo que cada uma delas é um objeto Date, que representa a seleção de tempo atual.

Tipo de retorno: um objeto com as propriedades start e end
hideDataColumns(columnIndexes)

Oculta as séries de dados especificadas do gráfico. Aceita um parâmetro, que pode ser um número ou uma matriz de números, em que 0 se refere à primeira série de dados e assim por diante.

Return Type: nenhum
setVisibleChartRange(start, end)

Define o intervalo visível (zoom) para o intervalo especificado. Aceita dois parâmetros do tipo Date que representam o primeiro e o último horário do intervalo visível selecionado. Defina start como nulo para incluir tudo desde a data mais antiga até o end. Defina end como nulo para incluir tudo desde start até a última data.

Return Type: nenhum
showDataColumns(columnIndexes)

Mostra as séries de dados especificadas do gráfico, depois de ocultadas usando o método hideDataColumns. Aceita um parâmetro, que pode ser um número ou uma matriz de números, em que 0 se refere à primeira série de dados e assim por diante.

Return Type: nenhum

Eventos

Nome
rangechange

Disparado quando o usuário altera o controle deslizante de intervalo. Os novos endpoints de intervalo estarão disponíveis como event['start'] e event['end']: 

google.visualization.events.addListener(chart, 'rangechange', rangechange_handler);

function rangechange_handler(e) {
  console.log('You changed the range to ', e['start'], ' and ', e['end']);
}
Propriedades:início, fim
ready

O gráfico está pronto para chamadas de métodos externos. 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 disparado.

Properties:nenhuma
select

Disparado quando o usuário clica em uma entidade visual. Para saber o que foi selecionado, chame getSelection().

Properties:nenhuma

Política de dados

Todos os códigos e dados são processados e renderizados no navegador. Nenhum dado é enviado para nenhum servidor.