Carregar as bibliotecas

Esta página mostra como carregar as bibliotecas do Google Chart.

Carregamento da biblioteca básica

Com poucas exceções, todas as páginas da Web com gráficos do 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 loader, você pode chamar a função google.charts.load uma ou mais vezes para carregar pacotes de tipos de gráfico específicos.

O primeiro argumento de 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á poucas diferenças entre os dois, e eles serão completamente idênticos, exceto quando uma nova versão estiver em andamento. 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 meses. Vamos anunciar os próximos lançamentos no nosso fórum e recomendamos que você os teste quando forem anunciados para garantir que qualquer mudança nas suas tabelas seja aceitável.

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 "Carregando" da página de documentação de cada gráfico.

Neste exemplo, também presumimos que você tenha uma função JavaScript chamada drawChart definida em algum lugar da página da Web. Você pode nomear essa função como quiser, mas ela precisa ser globalmente exclusiva e estar definida antes de ser referenciada na chamada para google.charts.setOnLoadCallback.

Observação:as versões anteriores do Google Charts usavam um código diferente do acima para carregar as bibliotecas. Para atualizar os gráficos atuais para usar o novo código, consulte Atualizar o código do carregador de biblioteca.

Confira um exemplo completo de como desenhar um gráfico de pizza usando a técnica de carregamento básica:

<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 do carregamento

Primeiro, você precisa carregar o 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 body do documento ou pode ser inserida dinamicamente no documento enquanto ele está sendo carregado ou após a conclusão do carregamento. 

<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 da chamada pode ser em uma tag script no head ou body do documento. Você pode fazer a chamada enquanto o documento ainda está sendo carregado ou a qualquer momento após o término do 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. No JavaScript, é possível codificar jsonObject com este código: encodeURIComponent(JSON.stringify(jsonObject)).

Limitações

Se você estiver usando versões anteriores à v45, há algumas limitações menores, mas importantes, na forma como você carrega os 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ê estiver usando um ChartWrapper, será necessário carregar explicitamente todos os pacotes necessários, em vez de depender do ChartWrapper para fazer o carregamento automaticamente.
  3. Para Geochart e Map Chart, é necessário carregar o antigo e o novo carregador de biblioteca. Novamente, isso é somente para versões anteriores à v45. Não faça isso para versões mais recentes. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Carregar nome ou número da versão

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

atual
Isso é para a versão oficial mais recente, que muda sempre que lançamos uma nova versão. Essa versão é idealmente bem testada e sem bugs, mas você pode especificar uma versão congelada específica depois de ter certeza de que ela está funcionando.
em breve
Isso é para a próxima versão, enquanto ela ainda está sendo testada e antes de se tornar a versão oficial atual. 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 a versão 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 de 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 tabelas deles nunca vão mudar, independente das melhorias que fizermos no futuro. Para esses usuários, oferecemos suporte a gráficos do Google congelados.

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. Geralmente, não oferecemos suporte a versões congeladas, exceto para sugerir que você faça upgrade para uma versão mais recente.

Carregar configurações

O segundo parâmetro na chamada de google.charts.load é um objeto para especificar 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 oferecer 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. É possível evitar a especificação de pacotes se você usar um ChartWrapper para carregar automaticamente o que será necessário.
language
O código do idioma ou localidade que precisa ser usado para 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) Essa configuração permite especificar uma chave que pode ser usada com o Mapa e o Mapa. É recomendável fazer isso em vez de usar o comportamento padrão, que pode resultar em redução ocasional do serviço para os usuários. Saiba como configurar sua própria chave para usar o serviço da API Google Maps JavaScript: 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 definido como "true", todos os gráficos e dicas de ferramentas que geram HTML a partir de dados fornecidos pelo usuário vão higienizar os dados, removendo elementos e atributos não seguros. Como alternativa (v49+), a biblioteca pode ser carregada no modo seguro usando um atalho que aceita as mesmas configurações de carregamento, mas sempre carrega a versão "atual": 
  google.charts.safeLoad({ packages: ['corechart'] });

Localidades

As localidades são usadas para personalizar textos em 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'});

Siga este link para conferir um exemplo em tempo real.

Chamada de retorno

Antes de usar qualquer um dos pacotes carregados por google.charts.load, você precisa aguardar a conclusão do carregamento. Não basta esperar o carregamento do documento ser concluído. Como pode levar algum tempo até que o 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.

Para todas essas maneiras, é necessário fornecer uma definição de função, em vez de chamar a função. A definição de função que você fornece pode ser uma função nomeada (basta informar o nome dela) ou uma função anônima. Quando o carregamento dos pacotes terminar, essa função de callback será chamada sem argumentos. O loader também vai esperar o carregamento do documento ser concluído 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();
      });

Chamada de retorno via promessa

Outra maneira de registrar seu callback é usar a promessa retornada da chamada google.charts.load. Para 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 de biblioteca

As versões anteriores do Google Charts usavam um código diferente para carregar as bibliotecas. A tabela abaixo mostra o código antigo do carregador de biblioteca em comparação com o novo.

Código antigo do carregador de 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.