Carregar as bibliotecas

Esta página mostra como carregar as bibliotecas de gráficos do Google.

Carregamento da biblioteca básica

Com algumas exceções, todas as páginas da Web com o Gráficos Google precisam incluir as seguintes linhas no <head> da página da Web:

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

A primeira linha desse exemplo carrega o próprio carregador. Só é possível carregar o carregador uma vez, não importa quantos gráficos você planeja desenhar. Depois de carregar o carregador, você pode chamar a função google.charts.load uma ou mais vezes para carregar pacotes de tipos de gráficos específicos.

O primeiro argumento para google.charts.load é o nome ou número da versão, como uma string. Se você especificar 'current', a versão oficial mais recente do Google Charts será carregada. Se você quiser testar o candidato para a próxima versão, use 'upcoming'. Em geral, haverá muito pouca diferença entre os dois, e eles serão completamente idênticos, exceto quando um novo lançamento estiver a caminho. Um motivo comum para usar upcoming é quando você quer testar um novo tipo de gráfico ou recurso que o Google está prestes a lançar nos próximos dois meses. Anunciamos as próximas versões no nosso fórum e recomendamos que você as teste quando for anunciado, para garantir que as alterações nos gráficos sejam aceitáveis.

O exemplo acima pressupõe que você quer exibir um corechart (barra, coluna, linha, área, área em degraus, balão, pizza, rosquinha, combinação, candlestick, histograma, dispersão). Se você quiser outro tipo de gráfico, substitua ou adicione o nome de pacote adequado de corechart acima (por exemplo, {packages: ['corechart', 'table', 'sankey']}. O nome do pacote pode ser encontrado na seção "Carregamento" da página de documentação de cada gráfico.

Este exemplo também pressupõe que você tenha uma função JavaScript chamada drawChart definida em algum lugar da página da Web. Dê o nome que quiser a essa função, mas verifique se ela é globalmente exclusiva e definida antes de fazer referência a ela na chamada para google.charts.setOnLoadCallback.

Observação: as versões anteriores dos gráficos do Google usavam códigos diferentes do acima para carregar as bibliotecas. Para atualizar os gráficos existentes e usar o novo código, consulte Atualizar código do carregador da biblioteca.

Veja um exemplo completo do desenho de um gráfico de pizza usando a técnica básica de carregamento:

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

    function drawChart() {
      // Define the chart to be drawn.
      var data = new google.visualization.DataTable();
      data.addColumn('string', 'Element');
      data.addColumn('number', 'Percentage');
      data.addRows([
        ['Nitrogen', 0.78],
        ['Oxygen', 0.21],
        ['Other', 0.01]
      ]);

      // Instantiate and draw the chart.
      var chart = new google.visualization.PieChart(document.getElementById('myPieChart'));
      chart.draw(data, null);
    }
  </script>
</head>
<body>
  <!-- Identify where the chart should be drawn. -->
  <div id="myPieChart"/>
</body>

Detalhes de carregamento

Primeiro, carregue o próprio carregador, o que é feito em uma tag script separada com src="https://www.gstatic.com/charts/loader.js". Essa tag pode estar no head ou no body do documento ou ser inserida dinamicamente no documento enquanto ele está sendo carregado ou depois que o carregamento é concluído. 

<script src="https://www.gstatic.com/charts/loader.js"></script>

Depois que o carregador for carregado, você estará livre para chamar google.charts.load. O local pode ser chamado em uma tag script no head ou body do documento, e é possível chamá-lo enquanto o documento ainda está sendo carregado ou a qualquer momento após o carregamento.

A partir da versão 45, você pode chamar google.charts.load mais de uma vez para carregar pacotes adicionais, embora seja mais seguro se puder evitar isso. Você precisa fornecer o mesmo número de versão e configurações de idioma todas as vezes.

Agora você pode usar o parâmetro de URL autoload da JSAPI, mas o valor desse parâmetro precisa usar formatação JSON rigorosa e codificação de URL. Em JavaScript, você pode fazer a codificação de jsonObject com este código: encodeURIComponent(JSON.stringify(jsonObject)).

Limitações

Se você estiver usando versões anteriores à v45, há algumas limitações pequenas, mas importantes, relacionadas ao carregamento de gráficos do Google:

  1. Só é possível chamar google.charts.load uma vez. No entanto, é possível listar todos os pacotes necessários em uma chamada, para que não seja necessário fazer chamadas separadas.
  2. Se você está usando um ChartWrapper, é necessário carregar explicitamente todos os pacotes necessários em vez de depender do ChartWrapper para carregá-los automaticamente.
  3. Para os gráficos de geográfico e mapa, é preciso carregar tanto o carregador de biblioteca antigo quanto o novo. Novamente, isso se aplica apenas para versões anteriores à v45, e não faça isso para versões posteriores. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Nome ou número da versão de carregamento

O primeiro argumento da chamada google.charts.load é o nome ou número da versão. No momento, existem apenas dois nomes de versões especiais e várias versões congeladas.

atuais
Esta é a versão oficial mais recente, que muda sempre que lançamos uma nova versão. Idealmente, essa versão é bem testada e não apresenta bugs, mas você poderá especificar uma versão congelada específica quando achar que está funcionando.
"Próximos"
Isso será para a próxima versão, enquanto ainda está em teste e antes de se tornar a versão atual oficial. Teste essa versão regularmente para saber o mais rápido possível se há algum problema que precisa ser resolvido antes que ela se torne oficial.

Quando lançamos novas versões do Google Charts, algumas das mudanças são grandes, como tipos de gráficos totalmente novos. Outras mudanças são pequenas, como melhorias na aparência ou no comportamento dos gráficos existentes.

Muitos criadores de gráficos do Google ajustam a aparência dos gráficos até que fiquem exatamente iguais. Alguns criadores podem se sentir mais confortáveis sabendo que as paradas nunca mudarão, independentemente das melhorias que fizermos no futuro. Para esses usuários, oferecemos suporte a gráficos congelados do Google.

As versões congeladas dos gráficos são identificadas por número e descritas nos nossos lançamentos oficiais. Para carregar uma versão congelada, substitua current ou upcoming na chamada de google.charts.load pelo número da versão congelada:

<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
    google.charts.load('43', {packages: ['corechart']});
    google.charts.setOnLoadCallback(drawChart);
    ...
</script>

Esperamos que as versões congeladas permaneçam disponíveis indefinidamente, mas podemos desativar as versões congeladas por questões de segurança. Normalmente, não oferecemos suporte para versões congeladas, exceto para sugerir que você atualize para uma versão mais recente.

Carregar configurações

O segundo parâmetro na chamada de google.charts.load é um objeto para especificar as configurações. As propriedades a seguir são compatíveis com as configurações.

pacotes
Uma matriz de zero ou mais pacotes. Cada pacote carregado terá o código necessário para dar suporte a um conjunto de funcionalidades, normalmente um tipo de gráfico. Os pacotes que você precisa carregar estão listados na documentação de cada tipo de gráfico. Você pode evitar a especificação de pacotes se usar um ChartWrapper para carregar automaticamente o que será necessário.
language
O código do idioma ou da localidade que precisa personalizar o texto que pode fazer parte do gráfico. Consulte Localidades para mais detalhes.
callback
Uma função que será chamada quando os pacotes forem carregados. Como alternativa, você pode especificar essa função chamando google.charts.setOnLoadCallback, conforme demonstrado no exemplo acima. Consulte Callback para mais detalhes. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Com essa configuração, é possível especificar uma chave que pode ser usada com o gráfico de mapa e o Gráfico de mapa. Faça isso em vez de usar o comportamento padrão, que pode resultar na limitação ocasional do serviço para seus usuários. Saiba como configurar sua própria chave para usar o serviço "API Google Maps JavaScript" aqui: Receber uma chave/autenticação. O código vai ficar assim: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Quando definida como verdadeira, todos os gráficos e dicas que geram HTML com base em dados fornecidos pelo usuário vão limpá-los, removendo elementos e atributos não seguros. Como alternativa (v49+), a biblioteca pode ser carregada no modo de segurança usando um atalho que aceita as mesmas configurações de carregamento, mas sempre carrega a versão "atual": 
  google.charts.safeLoad({ packages: ['corechart'] });

Localidades

Localidades são usadas para personalizar o texto de um país ou idioma, afetando a formatação de valores como moedas, datas e números.

Por padrão, o Google Charts é carregado com a localidade "en". É possível substituir esse padrão especificando explicitamente uma localidade nas configurações de carregamento.

Para carregar um gráfico formatado para uma localidade específica, use a configuração language da seguinte maneira: 

  // Load Google Charts for the Japanese locale.
  google.charts.load('current', {'packages':['corechart'], 'language': 'ja'});

Acesse este link para ver um exemplo ativo.

Chamada de retorno

Antes de usar qualquer um dos pacotes carregados por google.charts.load, é necessário aguardar a conclusão do carregamento. Não basta aguardar o documento terminar de carregar. Como pode levar algum tempo até que esse carregamento seja concluído, é necessário registrar uma função de callback. Há três maneiras de fazer isso. Especifique uma configuração callback na chamada google.charts.load ou chame setOnLoadCallback transmitindo uma função como argumento ou use a promessa retornada pela chamada de google.charts.load.

Observe que, para todas essas maneiras, você precisa fornecer uma definição de função, em vez de chamar a função. A definição de função fornecida pode ser uma função nomeada (você apenas fornece o nome dela) ou uma função anônima. Quando os pacotes terminarem de carregar, essa função de callback será chamada sem argumentos. O carregador também aguardará até que o documento termine de carregar antes de chamar o callback.

Se quiser desenhar mais de um gráfico, você pode registrar mais de uma função de callback usando setOnLoadCallback ou combiná-las em uma função. Saiba mais sobre como desenhar vários gráficos em uma página. 

  google.charts.setOnLoadCallback(drawChart1);
  google.charts.setOnLoadCallback(drawChart2);
  // OR
  google.charts.setOnLoadCallback(
    function() { // Anonymous function that calls drawChart1 and drawChart2
         drawChart1();
         drawChart2();
      });

Callback via promessa

Outra maneira de registrar o callback é usar a promessa retornada da chamada google.charts.load. Para fazer isso, adicione uma chamada ao método then() com um código semelhante ao seguinte. 

  google.charts.load('upcoming', {packages: ['corechart']}).then(drawChart);

Uma vantagem de usar a promessa é que você pode desenhar facilmente mais gráficos encadeando mais chamadas .then(anotherFunction). O uso da promessa também vincula o callback aos pacotes específicos necessários para esse callback, o que é importante se você quiser carregar mais pacotes com outra chamada de google.charts.load().

Atualizar o código do carregador da biblioteca

As versões anteriores do Google Charts usavam códigos diferentes para carregar as bibliotecas. A tabela abaixo mostra a comparação entre o código do carregador de biblioteca antigo e o novo.

Código do carregador antigo da biblioteca 
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
  google.load("visualization", "1", {packages:["corechart"]});
  google.setOnLoadCallback(drawChart);
</script>
Novo código do carregador de biblioteca 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Para atualizar os gráficos existentes, substitua o código antigo do carregador da biblioteca pelo novo. No entanto, lembre-se das limitações de carregamento de bibliotecas descritas acima.