Articles /

Caricare le librerie

Questa pagina mostra come caricare le librerie di Google Chart.

Caricamento della libreria di base

Con poche eccezioni, tutte le pagine web con Google Charts dovrebbero includere le seguenti righe nel <head> della pagina web:

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

La prima riga di questo esempio carica il caricatore stesso. Puoi caricare il caricatore solo una volta, non importa quanti grafici intendi disegnare. Dopo aver caricato il caricatore, potete chiamare la funzione google.charts.load una o più volte per caricare pacchetti per particolari tipi di grafico.

Il primo argomento di google.charts.load è il nome o il numero della versione, come una stringa. Se specifichi 'current', questo fa sì che venga caricata l’ultima versione ufficiale di Google Charts. Se vuoi provare la candidata per la prossima release, usa invece 'upcoming'. In generale ci sarà pochissima differenza tra i due, e saranno completamente identici tranne quando è in corso una nuova release. Una ragione comune per usare upcoming è che vuoi testare un nuovo tipo di grafico o una nuova caratteristica che Google sta per rilasciare nel prossimo mese o due. (Annunciamo i prossimi rilasci sul nostro forum e raccomandiamo di provarli quando vengono annunciati, per essere sicuri che ogni cambiamento ai tuoi grafici sia accettabile.)

L’esempio sopra presuppone che tu voglia visualizzare un corechart(barra, colonna, linea, area, area a gradini, bolla, torta, ciambella, combo, candela, istogramma, dispersione). Se volete un tipo di grafico diverso o aggiuntivo, sostituite o aggiungete il nome del pacchetto appropriato al precedente corechart (ad esempio, {packages: }. Puoi trovare il nome del pacchetto nella sezione ‘Loading’ della pagina di documentazione per ogni grafico.

Questo esempio presuppone anche che tu abbia una funzione JavaScript chiamata drawChart definita da qualche parte nella tua pagina web. Puoi nominare quella funzione come vuoi, ma assicurati che sia globalmente unica e che sia definita prima di fare riferimento ad essa nella tua chiamata agoogle.charts.setOnLoadCallback.

Nota: Le versioni precedenti di Google Charts usavano un codice diverso da quello sopra descritto per caricare le librerie. Per aggiornare i tuoi grafici esistenti utilizzando il nuovo codice, vedi Update Library Loader Code.

Qui c’è un esempio completo di disegno di un grafico a torta usando la tecnica di caricamento di base:

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

Dettagli del caricamento

Prima devi caricare il caricatore stesso, che è fatto in un tag separato script con src="https://www.gstatic.com/charts/loader.js". Questo tag può essere sia nel head o body del documento, oppure può essere inserito dinamicamente nel documento mentre viene caricato o dopo che il caricamento è stato completato. 

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

Dopo che il caricatore è stato caricato, siete liberi di chiamare google.charts.load. Dove lo chiami può essere in un tag script nel head o body del documento, e potresti chiamarlo sia mentre il documento è ancora in fase di caricamento sia in qualsiasi momento dopo che ha terminato il caricamento.

A partire dalla versione 45, puoi chiamare google.charts.load più di una volta per caricare pacchetti aggiuntivi, sebbene sia più sicuro se puoi evitare di farlo. Dovete fornire lo stesso numero di versione e le stesse impostazioni di lingua ogni volta.

Ora puoi usare il vecchio parametro URL JSAPI autoload, ma il valore di questo parametro deve usare una formattazione JSON e una codifica URL rigorose. In JavaScript, puoi fare la codifica di jsonObject con questo codice: encodeURIComponent(JSON.stringify(jsonObject)).

Limitazioni

Se stai usando versioni precedenti alla v45, ci sono un paio di limitazioni minori ma importanti su come carichi Google Charts:

  1. Puoi chiamare google.charts.load solo una volta. Ma puoi elencare tutti i pacchetti di cui avrai bisogno in una sola chiamata, quindi non c’è bisogno di fare chiamate separate.
  2. Se stai usando un ChartWrapper, devi caricare esplicitamente tutti i pacchetti di cui avrai bisogno, piuttosto che fare affidamento sul ChartWrapper per caricarli automaticamente per te.
  3. Per Geochart e Map Chart, devi caricare sia il vecchio library loader che il nuovo library loader. Di nuovo, questo è solo per le versioni precedenti alla v45, e non dovresti farlo per le versioni successive. 
    <script src="https://www.gstatic.com/charts/loader.js"></script><script src="https://www.google.com/jsapi"></script>

Carica nome o numero della versione

Il primo argomento della tua chiamata google.charts.load è il nome o il numero della versione. Ci sono solo due nomi di versioni speciali in questo momento, e diverse versioni congelate.

current Questo è per l’ultima versione ufficiale che cambia ogni volta che inviamo una nuova versione. Questa versione è idealmente ben testata e priva di bug, ma potresti voler specificare invece una particolare versione congelata una volta che sei soddisfatto che funzioni. upcoming Questo è per la prossima versione, mentre è ancora in fase di test e prima che diventi la versione corrente ufficiale. Si prega di testare questa versione regolarmente in modo da sapere il prima possibile se ci sono problemi che devono essere affrontati prima che questa versione diventi la release ufficiale.

Quando rilasciamo nuove versioni di Google Charts, alcuni dei cambiamenti sono grandi, come tipi di grafici completamente nuovi. Altri cambiamenti sono piccoli, come i miglioramenti all’aspetto o al comportamento dei grafici esistenti.

Molti creatori di Google Chart mettono a punto l’aspetto e la sensazione dei loro grafici finché non è esattamente quello che vogliono. Alcuni creatori potrebbero sentirsi più a loro agio sapendo che i loro grafici non cambieranno mai, indipendentemente dai miglioramenti che faremo in futuro. Per questi utenti, supportiamo i Google Charts congelati.

Le versioni congelate dei grafici sono identificate da un numero, e sono descritte nelle nostre release ufficiali.Per caricare una versione congelata, sostituisci current o upcoming nella tua chiamata di google.charts.load con il numero della versione congelata:

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

Prevediamo che le versioni congelate rimarranno disponibili a tempo indeterminato, anche se potremmo ritirare le versioni congelate che hanno problemi di sicurezza. In genere non forniremo supporto per le versioni congelate, eccetto che per suggerire con aiuto l’aggiornamento a una versione più recente.

Carica impostazioni

Il secondo parametro nella tua chiamata a google.charts.load è un oggetto per specificare le impostazioni. Le seguenti proprietà sono supportate per le impostazioni.

packages Un array di zero o più pacchetti. Ogni pacchetto che viene caricato avrà il codice richiesto per supportare un insieme di funzionalità, tipicamente un tipo di grafico. Il pacchetto o i pacchetti da caricare sono elencati nella documentazione per ogni tipo di grafico. Si può evitare di specificare qualsiasi pacchetto se si usa un ChartWrapper per caricare automaticamente ciò che sarà necessario. language Il codice per la lingua o il locale che dovrebbe essere per personalizzare il testo che potrebbe essere parte del grafico. Vedere Locales per maggiori dettagli. callback Una funzione che sarà chiamata una volta che i pacchetti sono stati caricati. In alternativa, è possibile specificare questa funzione chiamando

google.charts.setOnLoadCallbackcome dimostrato nell’esempio sopra. Vedere Callback per maggiori dettagli.

 google.charts.load('current', { packages: , callback: drawChart });

mapsApiKey (v45) Questa impostazione permette di specificare una chiave che si può usare con Geochart e Map Chart. Potresti voler fare questo piuttosto che usare il comportamento predefinito che potrebbe risultare in un occasionale strozzamento del servizio per i tuoi utenti. Scopri come impostare la tua chiave per utilizzare il servizio ‘Google Maps JavaScript API’ qui: Ottenere una chiave/Autenticazione. Il tuo codice sarà qualcosa di simile a questo:

 var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });

safeMode (v47) Quando è impostato a true, tutti i grafici e i tooltip che generano HTML dai dati forniti dall’utente lo sterilizzeranno eliminando elementi e attributi non sicuri. In alternativa (v49+), la libreria può essere caricata in modalità sicura usando una scorciatoia che accetta le stesse impostazioni di caricamento, ma carica sempre la versione “attuale”:

 google.charts.safeLoad({ packages: });

Locales

Locales sono usati per personalizzare il testo per un paese o una lingua, influenzando la formattazione di valori come valute, date e numeri.

Di default, Google Charts è caricato con il locale “en”. Puoi sovrascrivere questo default specificando esplicitamente un locale nelle impostazioni di caricamento.

Per caricare un grafico formattato per un locale specifico, usa l’impostazione language in questo modo:

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

Segui questo link per un esempio dal vivo.

Callback

Prima di poter utilizzare qualsiasi pacchetto caricato da google.charts.load devi aspettare che il caricamento finisca. Non è sufficiente aspettare che il documento finisca di essere caricato. Poiché può passare del tempo prima che il caricamento sia finito, è necessario registrare una funzione di callback. Ci sono tre modi per farlo. O specifichi un’impostazione callback nella tua chiamata google.charts.load, o chiami setOnLoadCallback passando una funzione come argomento, o usi la Promessa che viene restituita dalla chiamata di google.charts.load.

Notate che per tutti questi modi, dovete fornire una definizione di funzione, piuttosto che chiamare la funzione. La definizione di funzione che fornite può essere sia una funzione nominata (quindi date solo il suo nome) o una funzione anonima. Quando i pacchetti hanno finito di essere caricati, questa funzione di callback sarà chiamata senza argomenti. Il caricatore aspetterà anche che il documento finisca il caricamento prima di chiamare la callback.

Se vuoi disegnare più di un grafico, puoi registrare più di una funzione di callback usando setOnLoadCallback, oppure puoi combinarle in una sola funzione. Per saperne di più su come disegnare più grafici su una pagina. 

 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

Un altro modo di registrare la tua callback è usare la Promise che viene restituita dalla chiamata google.charts.load. Lo si fa aggiungendo una chiamata al metodo then() con un codice simile al seguente. 

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

Un vantaggio dell’uso della Promessa è che si possono facilmente disegnare più grafici semplicemente concatenando più chiamate .then(anotherFunction). L’uso della Promise lega anche il callback ai pacchetti specifici richiesti per quel callback, il che è importante se si vogliono caricare più pacchetti con un’altra chiamata di google.charts.load().

Aggiornamento del codice di caricamento delle librerie

Le versioni precedenti di Google Charts usavano un codice diverso per caricare le librerie. La tabella sottostante mostra il vecchio codice di caricamento delle librerie rispetto al nuovo.

Old Library Loader Code 

<script type="text/javascript" src="https://www.google.com/jsapi"></script><script type="text/javascript"> google.load("visualization", "1", {packages:}); google.setOnLoadCallback(drawChart);</script>

New Library Loader Code 

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

Per aggiornare i tuoi grafici esistenti, puoi sostituire il vecchio codice di caricamento delle librerie con quello nuovo.

Leave a Reply