Carica le librerie

Questa pagina mostra come caricare le librerie di grafici Google.

Caricamento di librerie di base

Con poche eccezioni, tutte le pagine web con Google Charts devono 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: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
  ...
</script>

La prima riga di questo esempio carica il caricatore stesso. Puoi caricare il caricatore una sola volta, indipendentemente dal numero di grafici che prevedi di disegnare. Dopo aver caricato il caricatore, puoi chiamare la funzione google.charts.load una o più volte per caricare i pacchetti per determinati tipi di grafici.

Il primo argomento di google.charts.load è il nome o il numero della versione come stringa. Se specifichi 'current', viene caricata la release ufficiale più recente di Google Charts. Se vuoi provare il candidato per la prossima uscita, usa invece 'upcoming'. In genere, tra i due non c'è molta differenza e sono completamente identici, tranne quando è in corso una nuova release. Un motivo comune per utilizzare upcoming è che vuoi testare un nuovo tipo di grafico o una nuova funzionalità che Google sta per rilasciare nei prossimi uno o due mesi. Annuncieremo le release imminenti nel nostro forum e ti consigliamo di provarle quando vengono annunciate per assicurarti che eventuali modifiche ai tuoi grafici siano accettabili.

L'esempio riportato sopra presuppone che tu voglia visualizzare un corechart (a barre, a colonne, a linee, ad area, ad area con incrementi, a bolle, a torta, a ciambella, combinato, a candele, istogramma, a dispersione). Se vuoi un tipo di grafico diverso o aggiuntivo, sostituisci o aggiungi il nome del pacchetto appropriato per corechart sopra (ad es. {packages: ['corechart', 'table', 'sankey']}. Puoi trovare il nome del pacchetto nella sezione "Caricamento" della pagina della documentazione di ogni grafico.

Questo esempio presuppone inoltre che tu abbia una funzione JavaScript chiamata drawChart definita da qualche parte nella pagina web. Puoi assegnare alla funzione il nome che preferisci, ma assicurati che sia univoca a livello globale e che sia definita prima di farvi riferimento nella chiamata a google.charts.setOnLoadCallback.

Nota:le versioni precedenti di Google Grafici utilizzavano un codice diverso da quello riportato sopra per caricare le librerie. Per aggiornare i grafici esistenti in modo che utilizzino il nuovo codice, consulta Aggiornare il codice del caricatore della libreria.

Ecco un esempio completo di come disegnare un grafico a torta utilizzando la tecnica di caricamento di base:

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

Dettagli sul caricamento

Innanzitutto devi caricare il caricatore stesso, che viene eseguito in un tag script separato con src="https://www.gstatic.com/charts/loader.js". Questo tag può trovarsi in head o body del documento oppure può essere inserito dinamicamente nel documento durante il caricamento o al termine del caricamento. 

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

Una volta caricato il caricatore, puoi chiamare google.charts.load. Puoi chiamarlo in un tag script in head o body del documento e puoi chiamarlo mentre il documento è ancora in fase di caricamento o in qualsiasi momento dopo il caricamento.

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

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

Limitazioni

Se utilizzi versioni precedenti alla 45, ci sono alcune limitazioni minori, ma importanti, relative al caricamento di Google Grafici:

  1. Puoi chiamare google.charts.load una sola volta. Tuttavia, puoi elencare tutti i pacchetti di cui hai bisogno in una singola chiamata, quindi non è necessario effettuare chiamate separate.
  2. Se utilizzi un ChartWrapper, devi caricare esplicitamente tutti i pacchetti di cui hai bisogno, anziché fare affidamento su ChartWrapper per caricarli automaticamente per te.
  3. Per Geochart e Map Chart, devi caricare sia il caricatore della libreria precedente sia quello nuovo. Ancora una volta, questa operazione è valida solo per le versioni precedenti alla 45 e non deve essere eseguita per le versioni successive. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Carica il nome o il numero della versione

Il primo argomento della chiamata google.charts.load è il nome o il numero della versione. Al momento esistono solo due nomi di versioni speciali e diverse versioni bloccate.

attuale
Si tratta dell'ultima release ufficiale, che cambia ogni volta che viene rilasciata una nuova release. Questa versione è idealmente testata e priva di bug, ma potresti voler specificare una determinata versione bloccata quando ritieni che funzioni.
in programma
Si tratta della prossima release, mentre è ancora in fase di test e prima che diventi la release ufficiale corrente. Testa questa versione regolarmente per sapere il prima possibile se ci sono problemi da risolvere prima che diventi la release ufficiale.

Quando rilasciamo nuove versioni di Google Charts, alcune modifiche sono sostanziali, ad esempio tipi di grafici completamente nuovi. Altre modifiche sono di piccola entità, come miglioramenti all'aspetto o al comportamento dei grafici esistenti.

Molti creator di grafici Google perfezionano l'aspetto dei propri grafici finché non ottengono esattamente ciò che vogliono. Alcuni creator potrebbero sentirsi più a loro agio sapendo che i loro grafici non cambieranno mai, indipendentemente dai miglioramenti che apporteremo in futuro. Per questi utenti, supportiamo Google Charts congelato.

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

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

Prevediamo che le versioni bloccate rimarranno disponibili a tempo indeterminato, anche se potremmo ritirare quelle che presentano problemi di sicurezza. In genere, non forniamo assistenza per le versioni bloccate, tranne che per suggerirti di eseguire l'upgrade a una versione più recente.

Carica impostazioni

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

pacchi
Un array di zero o più pacchetti. Ogni pacchetto caricato avrà il codice necessario per supportare un insieme di funzionalità, in genere un tipo di grafico. Il pacchetto o i pacchetti da caricare sono elencati nella documentazione per ogni tipo di grafico. Puoi evitare di specificare i pacchetti se utilizzi un ChartWrapper per caricare automaticamente ciò che sarà necessario.
language
Il codice della lingua o delle impostazioni internazionali che deve essere utilizzato per personalizzare il testo che potrebbe essere parte del grafico. Per ulteriori dettagli, consulta la sezione Locali.
callback
Una funzione che verrà chiamata una volta caricati i pacchetti. In alternativa, puoi specificare questa funzione chiamando google.charts.setOnLoadCallback come mostrato nell'esempio precedente. Per ulteriori dettagli, consulta la sezione Chiamata in arrivo. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Questa impostazione consente di specificare una chiave che puoi utilizzare con Grafico geografico e Grafico della mappa. Ti consigliamo di farlo anziché utilizzare il comportamento predefinito, che potrebbe comportare un occasionale throttling del servizio per i tuoi utenti. Scopri come configurare la tua chiave per utilizzare il servizio "API JavaScript di Google Maps" qui: Ottieni una chiave/autenticazione. Il tuo codice sarà simile al seguente: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Se impostato su true, tutti i grafici e le descrizioni comando che generano HTML dai dati forniti dall'utente lo sanitizeranno rimuovendo elementi e attributi non sicuri. In alternativa (v49 e versioni successive), la libreria può essere caricata in modalità sicura utilizzando una scorciatoia che accetta le stesse impostazioni di caricamento, ma carica sempre la versione "attuale": 
  google.charts.safeLoad({ packages: ['corechart'] });

Impostazioni internazionali

Le impostazioni internazionali vengono utilizzate per personalizzare il testo per un paese o una lingua, influendo sulla formattazione di valori come valute, date e numeri.

Per impostazione predefinita, Google Charts viene caricato con la lingua "it". Puoi eseguire l'override di questa impostazione predefinita specificando esplicitamente un'impostazione internazionale nelle impostazioni di caricamento.

Per caricare un grafico formattato per una specifica impostazioni internazionali, utilizza l'impostazione language nel seguente modo: 

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

Segui questo link per un esempio pratico.

Richiamata

Prima di poter utilizzare i pacchetti caricati da google.charts.load, devi attendere il completamento del caricamento. Non è sufficiente attendere il completamento del caricamento del documento. Poiché il caricamento può richiedere del tempo, devi registrare una funzione di callback. Puoi procedere in tre modi. Specifica un'impostazione callback nella chiamata google.charts.load, chiama setOnLoadCallback passando una funzione come argomento o utilizza la promessa restituita dalla chiamata di google.charts.load.

Tieni presente che, per tutti questi modi, devi fornire una definizione di funzione, anziché chiamare la funzione. La definizione di funzione fornita può essere una funzione con nome (quindi devi solo specificarne il nome) o una funzione anonima. Al termine del caricamento dei pacchetti, questa funzione di callback verrà chiamata senza argomenti. Il caricatore attenderà inoltre il completamento del caricamento del documento prima di chiamare il callback.

Se vuoi disegnare più di un grafico, puoi registrare più di una funzione callback utilizzando setOnLoadCallback oppure puoi combinarle in un'unica funzione. Scopri di più su come disegnare più grafici in una pagina. 

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

Richiamata tramite promessa

Un altro modo per registrare il callback è utilizzare la promessa restituita dalla chiamata google.charts.load. Aggiungi una chiamata al metodo then() con il seguente codice. 

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

Un vantaggio dell'utilizzo della promessa è che puoi facilmente creare altri grafici semplicemente collegando più chiamate .then(anotherFunction). L'utilizzo di Promise collega anche il callback ai pacchetti specifici richiesti per quel callback, il che è importante se vuoi caricare più pacchetti con un'altra chiamata di google.charts.load().

Aggiorna il codice del caricatore della libreria

Le versioni precedenti di Google Grafici utilizzavano un codice diverso per caricare le librerie. La tabella seguente mostra il codice del programma di caricamento della libreria precedente e quello nuovo.

Codice del caricatore della libreria precedente 
<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>
Nuovo codice del caricatore della libreria 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Per aggiornare i grafici esistenti, puoi sostituire il vecchio codice del caricatore della libreria con il nuovo codice. Tuttavia, tieni presente le limitazioni relative al caricamento delle librerie descritte sopra.