Gráfico de anotações

Visão geral

Os gráficos de anotações são gráficos interativos de linhas de série temporal com suporte. Observe que o cronograma comentado agora usa automaticamente o gráfico de anotações.

Alerta de confusão: no momento, o gráfico de anotações do Google é distinto das anotações compatíveis com outros gráficos do Google (atualmente área, barra, coluna, combinação, linha e dispersão). Nesses gráficos, as anotações são especificadas em uma coluna de tabela de dados separada e exibidas como trechos curtos de texto em que os usuários podem passar o cursor para ver 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 do layout é google.visualization.AnnotationChart.

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

Formato de dados

Você pode exibir uma ou mais linhas no gráfico. Cada linha representa uma posição X no gráfico, ou seja, um horário 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 de X do ponto no gráfico. Se essa coluna for do tipo date, e não datetime, a menor resolução no eixo X será de um dia.
  • Cada linha de dados é descrita por um conjunto de uma a três colunas adicionais, conforme descrito aqui:
    • Y value - [obrigatório, número] a primeira coluna em cada conjunto descreve o valor da linha no momento correspondente a partir da primeira coluna. O rótulo da coluna é exibido no gráfico como o título dessa linha.
    • Annotation title - [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 "O melhor dia registrado".
    • Texto da anotação: [string opcional] se existir 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. Não há essencialmente um limite de tamanho, mas entradas excessivamente longas podem transbordar na 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 do ponto de registro, você pode dizer algo como "O dia seguinte mais próximo foi 10 graus mais frios".

Opções de configuração

Nome
permitirHTML

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

Tipo: booleano
Padrão:falso
allValuesSuffix

Um sufixo a ser adicionado a todos os valores nas legendas e marcações nos eixos verticais.

Tipo: string
Padrão:nenhum
Largura das anotações

A largura (em porcentagem) da área das anotações em 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 nas 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, "vermelho" ou "#00cc00".

Tipo: matriz de strings
Padrão:cores padrão
Formato da data

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

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

Se definido como false, o gráfico ocultará a tabela de anotações, e as anotações e anotaçõesText não ficarão visíveis (a tabela de anotações também não será exibida se não houver anotações nos seus dados, independentemente dessa opção). Quando essa opção é definida como verdadeira, após cada coluna numérica, é possível adicionar duas colunas de string de anotação, uma para o título da anotação e outra para o texto.

Tipo: booleano
Padrão:verdadeiro
Filtro de anotações

Se definido como verdadeiro, o gráfico exibirá um controle de filtro para filtrar as anotações. Use essa opção quando houver muitas anotações.

Tipo: booleano
Padrão: falso
displayDateBarSeparator

Indica se um pequeno separador de barra ( | ) deve ser exibido entre os valores de série e a data na legenda, em que verdadeiro significa sim.

Tipo: booleano
Padrão: verdadeiro
Valores de exibição exata

Indica se uma versão arredondada dos valores é exibida na parte superior do gráfico para economizar espaço. Já "false" indica que isso pode ser feito. Por exemplo, se ela for definida como "false" (falsa), 56.123.45 poderá ser exibida como 56.12 mil.

Tipo: booleano
Padrão:falso
Pontos de exibição de display

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

Tipo: booleano
Padrão:verdadeiro
Valores de exibição

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

Tipo: booleano
Padrão:verdadeiro
Intervalo de exibição

Mostra ou não a área de seleção do intervalo de zoom (a área na parte inferior do gráfico), em que false significa não.

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

Tipo: booleano
Padrão: verdadeiro
Botões de exibiçãodeZoom

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

Tipo: booleano
Padrão:verdadeiro
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 que não há preenchimento. A cor de preenchimento é a mesma da linha acima dela.

Tipo: número
Padrão: 0
legenda

Indica se você quer colocar a legenda colorida 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 exibir a próxima marcação principal acima do ponto de dados máximo. Ele terá precedência sobre o eixo Y máximo determinado por scaleType.

Isso é semelhante a 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 de dados mínimo for menor que esse valor, essa configuração vai ser ignorada, e o gráfico vai ser ajustado para mostrar a próxima grande marcação abaixo do ponto de dados mínimo. Ele terá precedência sobre o mínimo do eixo Y determinado por scaleType.

Isso é semelhante a minValue nos gráficos principais.

Tipo: número
Padrão: automático
Formatos de número

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 decimalFormat java.

  • Se não for especificado, o padrão de formato será usado.
  • 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érie (baseados em zero), e os valores serão os padrões a serem usados para formatar a série especificada.

    Não é necessário incluir um formato para cada série no gráfico. Todas as séries não especificadas usarão o formato padrão.

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

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

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

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

  • Se você especificar uma matriz vazia, o gráfico não vai mostrar 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, será adicionada uma escala para a terceira série no meio do gráfico.
  • Qualquer valor após o terceiro na matriz será ignorado.

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

Tipo:matriz de números
Padrão: automático
Formato da escala

Formato de número a ser usado para as etiquetas de marcação do eixo. O padrão de '#' é exibido como um número inteiro.

Tipo: string
Padrão: '#'
Tipo de escala

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á os 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 valores de dados:
    • Se todos os valores forem >=0, o eixo Y vai abranger de zero ao valor máximo de dados.
    • Se todos os valores forem <=0, o eixo Y vai abranger de zero ao valor mínimo dos dados.
    • Se os valores são positivos e negativos, o eixo Y varia entre o número máximo e o mínimo da série.
      Para várias séries, use "allfix".
  • "allmaximized" - o mesmo que "maximized", mas é usado quando várias escalas são exibidas. Ambos os gráficos serão maximizados dentro da mesma escala, o que significa que um número será deturpado em relação ao eixo Y, mas ao passar o cursor sobre cada série, ele exibirá o valor real.
  • "allFixed" – o mesmo que "Fixo", mas é usado quando várias escalas são mostradas. Essa configuração ajusta cada escala à série a que se aplica (use com scaleColumns).

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

Tipo: string
Padrão: "corrigido"
tabela

Contém opções relacionadas à tabela de anotações. Para especificar 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:falso
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 de anotação ou 1 para a coluna de texto de anotação.

Tipo:número
Padrão: 0
espessura

Um número de 0 a 10 (inclusivo) que especifica a espessura das linhas, em que 0 é o mais fino.

Tipo: número
Padrão: 0
Horário de término do zoom

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

Tipo:data
Padrão: nenhum
Horário de início do zoom

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.

Tipo de retorno:nenhum
draw(data, options, state)

Desenha o gráfico.

Tipo de retorno:nenhum
getContainer()

Recupera um identificador para o elemento de contêiner que contém o gráfico de anotações.

Tipo de retorno:processe um elemento DOM
getSelection()

Implementação padrão de getSelection(). Os elementos selecionados são os de células. Somente 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, representando a seleção atual.

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

Oculta a série de dados especificada 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.

Tipo de retorno: nenhum
setVisibleChartRange(start, end)

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

Tipo de retorno: nenhum
showDataColumns(columnIndexes)

Mostra as séries de dados especificadas do gráfico, depois que elas foram 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.

Tipo de retorno:nenhum

Eventos

Nome
rangechange

Disparado quando o usuário muda 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é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.

Propriedades:nenhuma
select

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

Propriedades:nenhuma

Política de dados

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