Carregar as bibliotecas

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

Carregamento básico da biblioteca

Com algumas 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 deste exemplo carrega o próprio carregador. Você só pode carregar o carregador uma vez, independentemente de quantos gráficos você pretenda desenhar. Depois de carregar o carregador, você pode chamar a função google.charts.load uma ou mais vezes para carregar pacotes para tipos específicos de grá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 dos gráficos do Google será carregada. Se você quiser testar o candidato para a próxima versão, use 'upcoming'. Em geral, haverá pouquíssima diferença 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 é que você quer testar um novo tipo de gráfico ou recurso que o Google está prestes a lançar em um ou dois meses. Anunciamos as próximas versões no nosso fórum e recomendamos que você as teste quando forem anunciadas para ter certeza de que as alterações nos gráficos serão aceitáveis.

No exemplo acima, suponha que você queira exibir um corechart (barra, coluna, linha, área, área em degraus, bolha, torta, rosca, combo, velas, histograma, dispersão). Se você quiser um tipo de gráfico diferente ou adicional, substitua ou adicione o nome do pacote apropriado para 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 sua página da Web. Você pode dar um nome a essa função, mas verifique se ela é exclusiva globalmente e que ela esteja definida antes de se referir a ela na chamada para google.charts.setOnLoadCallback.

Observação:as versões anteriores dos gráficos do Google usavam códigos diferentes dos 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.

Este é um exemplo completo de como desenhar 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 do 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 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ê poderá chamar google.charts.load. O local onde você o chama pode estar em uma tag script no head ou body do documento e pode ser chamado enquanto o documento ainda está sendo carregado ou a qualquer momento depois do carregamento.

A partir da versão 45, é possível chamar google.charts.load mais de uma vez para carregar pacotes adicionais, embora seja mais seguro se você puder evitar isso. É necessário 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 antigo da JSAPI, mas o valor desse parâmetro precisa usar formatação JSON e codificação de URL rígidas. Em JavaScript, é possível 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 secundárias, mas importantes, com relação a como você carrega gráficos do Google:

  1. Só é possível chamar google.charts.load uma vez. Porém, você pode listar todos os pacotes necessários em uma chamada, então não é necessário fazer chamadas separadas.
  2. Se você estiver usando um ChartWrapper, precisará carregar explicitamente todos os pacotes necessários, em vez de confiar no ChartWrapper para carregá-los automaticamente para você.
  3. Para o Geográfico e o Gráfico de mapa, é preciso carregar o carregador da biblioteca antiga e o novo. Novamente, isso é apenas para versões anteriores à v45, e não deve fazer isso para versões posteriores.
    <script src="https://www.gstatic.com/charts/loader.js"></script>
    <script src="https://www.google.com/jsapi"></script>

Carregar o nome ou o número da versão

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

atual
Esta é a versão oficial mais recente, que é alterada sempre que uma nova versão é lançada. O ideal é que essa versão seja bem testada e sem bugs, mas recomendamos que você especifique uma versão congelada específica quando achar que está funcionando.
"Próximos"
Esta é a próxima versão, enquanto ainda está sendo testada e antes de se tornar a versão oficial oficial. Teste esta versão regularmente para que você saiba, o mais rápido possível, se há algum problema que precise ser resolvido antes que esta se torne o lançamento oficial.

Quando lançamos novas versões do Gráficos do Google, 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 Maps ajustam a aparência dos gráficos até que seja exatamente o que eles querem. Alguns criadores de conteúdo podem se sentir mais confortáveis sabendo que os gráficos nunca mudarão, independentemente das melhorias que faremos no futuro. Para esses usuários, temos compatibilidade com os Gráficos do Google congelados.

As versões congeladas do gráfico são identificadas pelo número e descritas em 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, mesmo que possam desativar as versões congeladas que têm problemas de segurança. Em geral, não oferecemos suporte a versões congeladas, exceto sugerimos 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. Você poderá 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 deve ser 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, é possível especificar essa função chamando google.charts.setOnLoadCallback, conforme demonstrado no exemplo acima. Consulte Callback para saber mais.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
chave da API Maps
(v45) Essa configuração permite especificar uma chave que você poderá usar com o Geográfico e o Gráfico de mapa. Isso é melhor do que o comportamento padrão, que pode resultar em uma limitação de serviço ocasional para os 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 ficará assim:
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
Modo seguro
(v47) Quando definido como verdadeiro, todos os gráficos e dicas que geram HTML de dados fornecidos pelo usuário limpam os dados removendo atributos e atributos não seguros. Como alternativa, 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

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

Por padrão, os gráficos do Google são carregados com a localidade "en". Para substituir esse padrão, especifique 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'});

Clique neste link para ver um exemplo ativo.

Callback

Antes de usar qualquer um dos pacotes carregados por google.charts.load, é necessário aguardar o término do carregamento. Não basta aguardar o documento terminar de ser carregado. Como pode levar algum tempo até que esse carregamento seja concluído, você precisa 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 o argumento ou use a promessa que é retornada pela chamada de google.charts.load.

Para todas essas maneiras, você precisa fornecer uma definição de função, em vez de chamar a função. A definição da função que você fornece pode ser uma função nomeada (para que você apenas nomeie) ou uma função anônima. Quando o carregamento dos pacotes for concluído, essa função de callback será chamada sem argumentos. O carregador também aguardará que o documento termine de carregar antes de chamar o callback.

Se quiser desenhar mais de um gráfico, registre mais de uma função de callback usando setOnLoadCallback ou combine-as em uma única 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 Promise

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

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

Um benefício de usar a promessa é que você pode desenhar mais gráficos facilmente encadeando mais chamadas de .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 código do carregador da biblioteca

As versões anteriores dos gráficos do Google usavam códigos diferentes para carregar as bibliotecas. A tabela abaixo mostra o antigo código do carregador de bibliotecas em comparação ao novo.

Código antigo do carregador de bibliotecas
<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 da 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 antigo código do carregador de bibliotecas pelo novo. No entanto, lembre-se das limitações para o carregamento de bibliotecas descritas acima.