Load the Libraries
Esta página mostra como carregar as bibliotecas do Google Chart.
Carregamento básico da biblioteca
Com poucas exceções, todas as páginas da web com Google Charts devem incluir as seguintes linhas no <head> da página web:
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
A primeira linha deste exemplo carrega o carregador em si. Você só pode carregar o carregador uma vez, não importa quantos gráficos você planeja desenhar. Após carregar a pá carregadora, você pode chamar a função google.charts.load uma ou mais vezes para carregar pacotes para determinados tipos de gráficos.
O primeiro argumento para google.charts.load é o nome ou número da versão, como uma string. Se você especificar 'current', isto faz com que a última versão oficial do Google Charts seja carregada. Se você quiser tentar o candidato para o próximo lançamento, use 'upcoming' em seu lugar. Em geral, haverá pouca diferença entre os dois, e eles serão completamente idênticos, exceto quando uma nova versão estiver em andamento. Uma razão comum para o touse upcoming é que você quer testar um novo tipo de gráfico ou recurso que o Google está prestes a lançar no próximo mês ou dois. (Anunciamos os próximos lançamentos em nosso fórum e recomendamos que você os experimente quando anunciados, para ter certeza que qualquer mudança em seus gráficos é aceitável.)
O exemplo acima assume que você quer exibir um corechart(bar, coluna, linha, área, área escalonada, bolha, torta, donut, combo, candlestick, histograma, scatter). Se você quiser um tipo diferente de gráfico oradicional, substitua ou adicione o nome do pacote apropriado antes de corechart acima (por exemplo, {packages: }. Você pode encontrar o nome do pacote na seção ‘Loading’ da página de documentação para cada gráfico.
Este exemplo também assume que você tem uma função JavaScript com o nome drawChart definida em algum lugar na sua página web. Você pode nomear essa função como quiser, mas certifique-se de que ela seja globalmente única e que esteja definida antes de referenciá-la na sua chamada paragoogle.charts.setOnLoadCallback.
Note: Versões anteriores dos Gráficos do Google usavam código que difere do acima para carregar as bibliotecas. Para atualizar seus gráficos existentes, veja Update Library Loader Code.
Aqui está um exemplo completo de 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: }); 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(, , ]); // 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/></body>
Detalhes de carregamento
Primeiro você deve carregar o próprio carregador, o que é feito em uma tag separada script com src="https://www.gstatic.com/charts/loader.js". Esta tag pode estar no head ou body do documento, ou pode ser inserida dinamicamente no documento enquanto ele está sendo carregado ou após o carregamento ser completado.
<script src="https://www.gstatic.com/charts/loader.js"></script>
Depois que o carregador estiver carregado, você está livre para chamar google.charts.load. Onde você o chamar pode ser em uma tag script no head ou body do documento, e você pode chamá-lo enquanto o documento ainda está sendo carregado ou a qualquer momento depois que ele tiver terminado de carregar.
A partir da versão 45, você pode chamar google.charts.load mais de uma vez a fim de carregar pacotes adicionais, embora seja mais seguro se você puder evitar fazer isso. Você deve fornecer o mesmo número de versão e as mesmas configurações de idioma a cada vez.
Agora você pode usar o antigo parâmetro JSAPI autoload URL, mas o valor deste parâmetro deve usar uma formatação JSON estrita e codificação de URL. No JavaScript, você pode fazer a codificação de jsonObject com este código: encodeURIComponent(JSON.stringify(jsonObject)).
Limitações
Se estiver a utilizar versões anteriores à v45, existem algumas limitações menores mas importantes na forma como carrega os Gráficos do Google:
- Só pode ligar para
google.charts.loaduma vez. Mas você pode listar todos os pacotes que você vai precisar em uma chamada, então não há necessidade de fazer chamadas separadas. - Se você está usando um ChartWrapper, você deve carregar explicitamente todos os pacotes que você vai precisar, ao invés de confiar no ChartWrapper para carregá-los automaticamente para você.
- Para o Geochart e Map Chart, você deve carregar tanto o antigo quanto o novo gerenciador de bibliotecas. Novamente, isto é somente para versões anteriores à v45, e você não deve fazer isto para versões posteriores.
<script src="https://www.gstatic.com/charts/loader.js"></script><script src="https://www.google.com/jsapi"></script>
Load Version Name or Number
O primeiro argumento da sua google.charts.load chamada é o nome ou número da versão. Existem apenas dois nomes de versão especiais neste momento, e várias versões congeladas.
current Isto é para o último lançamento oficial que muda cada vez que empurramos para fora um novo lançamento. Esta versão é idealmente bem testada e livre de bugs, mas você pode querer especificar uma versão congelada em particular uma vez que você esteja satisfeito que ela está funcionando. upcoming Esta é para a próxima versão, enquanto ainda está sendo testada e antes que ela se torne a versão oficial atual. Por favor teste esta versão regularmente para que você saiba o mais rápido possível se há algum problema que deve ser resolvido antes desta versão se tornar a versão oficial.
Quando lançamos novas versões do Google Charts, algumas das alterações são grandes, como tipos de gráficos totalmente novos. Outras mudanças são pequenas, como melhorias na aparência ou comportamento dos gráficos existentes.
Muitos criadores de Google Chart afinam a aparência e o comportamento de seus gráficos até que seja exatamente o que eles querem. Alguns criadores podem se sentir mais confortáveis sabendo que seus gráficos nunca irão mudar, independentemente das melhorias que fizermos no futuro. Para esses usuários, nós suportamos versões congeladas do Google Charts.
Frozen charts são identificadas por número, e são redescritas em nossasOfficial Releases.Para carregar uma versão congelada, substitua current ou upcoming na sua 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: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Esperamos que as versões congeladas permaneçam disponíveis indefinidamente, embora possamos retirar as versões congeladas que tenham preocupações de segurança. Normalmente não forneceremos suporte para versões congeladas, exceto que, de forma útil, sugerimos que você atualize para uma versão mais recente.
Load Settings
O segundo parâmetro na sua chamada de google.charts.load é um objeto para especificar configurações. As seguintes propriedades são suportadas para as configurações.
pacotes Um array de zero ou mais pacotes. Cada pacote que é carregado terá o código necessário para suportar um conjunto de funcionalidades, tipicamente um tipo de gráfico. O pacote ou pacotes que você precisa carregar estão listados na documentação para cada tipo de gráfico. Você pode evitar especificar quaisquer pacotes se você usar um ChartWrapper para carregar automaticamente o que será necessário. language O código para o idioma ou locale que deve ser para personalizar o texto que pode fazer parte do gráfico. Veja Locales para mais detalhes. callback Uma função que será chamada uma vez que os pacotes tenham sido carregados. Alternativamente, você pode especificar esta função chamandogoogle.charts.setOnLoadCallbackcomo demonstrado no exemplo acima. Veja Callback para mais detalhes.
google.charts.load('current', { packages: , callback: drawChart });
mapsApiKey (v45) Esta configuração permite que você especifique uma chave que você pode usar com Geochart e Map Chart. Você pode querer fazer isso em vez de usar o comportamento padrão que pode resultar em uma ocasional estrangulamento do serviço para seus usuários. Saiba como configurar a sua própria chave para utilizar o serviço ‘Google Maps JavaScript API’ aqui: Obtenha uma chave/autenticação. Seu código será algo parecido com isto:
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });
safeMode (v47) Quando definido como verdadeiro, todos os gráficos e dicas de ferramentas que geram HTML a partir de dados fornecidos pelo usuário irão higienizá-lo, removendo elementos e atributos inseguros. Alternativamente (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: });
Locales
Locales são usados 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, os Gráficos do Google são carregados com o locale “pt”. Você pode substituir este padrão especificando explicitamente um locale nas configurações de carregamento.
Para carregar um gráfico formatado para um locale específico, use a configuração language assim:
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':, 'language': 'ja'});
Seguir este link para um exemplo ao vivo.
Callback
Antes que você possa usar qualquer um dos pacotes carregados por google.charts.load você tem que esperar que o carregamento termine. Não é suficiente esperar apenas que o documento termine de carregar. Como pode demorar algum tempo até que este carregamento seja finalizado, você precisa registrar uma função de callback. Há três formas de fazer isso. Especifique uma configuração callback na sua chamada google.charts.load, ou ligue setOnLoadCallback passando uma função como argumento, ou use a Promessa que é retornada pela chamada de google.charts.load.
Note que para todas estas formas, você precisa fornecer uma definição de função, ao invés de chamar a função. A definição da função que você fornece pode ser uma função nomeada (então você apenas dá seu nome) ou uma função anônima. Quando os pacotes tiverem terminado de carregar, esta função de chamada de retorno será chamada sem argumentos. O carregador também aguardará que o documento termine de carregar antes de chamar a função de retorno.
Se você quiser desenhar mais de um gráfico, você pode registrar mais de uma função de callback usando setOnLoadCallback, ou você pode combiná-las em uma função. Aprenda 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 sua callback é usar a Promise que é retornada a partir da chamada google.charts.load. Você faz isso adicionando uma chamada para o método then() com um código que se parece com o seguinte.
google.charts.load('upcoming', {packages: }).then(drawChart);
Um benefício de usar o Promise é que então você pode facilmente desenhar mais gráficos apenas encadeando mais .then(anotherFunction) chamadas. Usando o Promise também vincula a callback aos pacotes específicos necessários para essa callback, o que é importante se você quiser carregar mais pacotes com outra chamada de google.charts.load().
Atualizar código do carregador da biblioteca
Versões anteriores do Google Charts usavam códigos diferentes para carregar as bibliotecas. A tabela abaixo mostra o código antigo do carregador de bibliotecas versus o novo.
<script type="text/javascript" src="https://www.google.com/jsapi"></script><script type="text/javascript"> google.load("visualization", "1", {packages:}); google.setOnLoadCallback(drawChart);</script>
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart);</script>
Para actualizar os seus gráficos existentes, pode substituir o código antigo do carregador de bibliotecas pelo novo código.
Leave a Reply