Carica le librerie

Questa pagina mostra come caricare le librerie di grafici di Google.

Caricamento di base della raccolta

Tranne alcune eccezioni, tutte le pagine web con grafici Google dovrebbero includere le seguenti righe nella sezione <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 solo una 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 per google.charts.load è il nome o il numero della versione, come stringa. Se specifichi 'current', verrà caricata l'ultima release ufficiale di Google Classifiche. Se vuoi provare il candidato per la prossima uscita, usa invece 'upcoming'. In generale ci saranno pochissime differenze e saranno completamente identiche, tranne quando è in corso una nuova versione. Un motivo comune per utilizzare upcoming è quello di voler testare un nuovo tipo di grafico o una nuova funzionalità che Google sta per rilasciare nel prossimo mese o due. (Annunciamo le prossime versioni nel nostro forum e ti consigliamo di provarle quando verranno annunciate, per assicurarti che eventuali modifiche ai grafici siano accettabili).

L'esempio precedente presuppone che tu voglia visualizzare un corechart (barra, colonna, linea, area, area con rientri, fumetto, torta, anello, combinato, candela, istogramma, a dispersione). Se vuoi un tipo di grafico diverso o aggiuntivo, sostituisci o aggiungi il nome del pacchetto appropriato per corechart in alto (ad es. {packages: ['corechart', 'table', 'sankey']}. Puoi trovare il nome del pacchetto nella sezione "Caricamento" della pagina della documentazione per ogni grafico.

In questo esempio si presuppone anche che tu abbia una funzione JavaScript denominata drawChart definita in qualche punto della 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 Graph utilizzavano codice diverso da quello riportato sopra per caricare le librerie. Per aggiornare i grafici esistenti in modo da utilizzare 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 di caricamento

Per prima cosa devi caricare il caricatore stesso, operazione che viene eseguita in un tag script separato con src="https://www.gstatic.com/charts/loader.js". Questo tag può trovarsi nella sezione head o body del documento oppure può essere inserito in modo dinamico nel documento mentre viene caricato 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. Dove lo chiami può essere 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 che è stato completato.

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

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

Limitazioni

Se utilizzi versioni precedenti alla v45, esistono un paio di limitazioni minori, ma importanti, relative al caricamento dei grafici Google:

  1. Puoi chiamare google.charts.load solo una volta. Tuttavia, puoi elencare tutti i pacchetti di cui hai bisogno in una singola chiamata, quindi non è necessario effettuare chiamate separate.
  2. Se utilizzi ChartWrapper, devi caricare esplicitamente tutti i pacchetti di cui hai bisogno, anziché affidarti a ChartWrapper per il caricamento automatico.
  3. Per Grafico geografico e Grafico della mappa, devi caricare sia il vecchio caricatore della libreria che quello nuovo. Come già detto, ciò è solo per le versioni precedenti alla 45 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 di 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 pubblicata 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 applica alla prossima release, mentre è ancora in fase di test e prima che diventi la release ufficiale ufficiale. Testa regolarmente questa versione in modo da sapere il prima possibile se ci sono problemi che dovrebbero essere risolti prima che questa versione diventi la release ufficiale.

Quando vengono rilasciate nuove versioni di Google, alcune modifiche sono notevoli, come tipi di grafici completamente nuovi. Altre modifiche sono di piccola entità, come miglioramenti all'aspetto o al comportamento dei grafici esistenti.

Molti creatori di grafici di Google perfezionano l'aspetto delle proprie classifiche fino a ottenere quelle che desiderano. Alcuni creator potrebbero sentirsi più a proprio agio sapendo che le loro classifiche non cambieranno mai, indipendentemente dai miglioramenti che apporteremo in futuro. Per questi utenti, supportiamo i grafici Google bloccati.

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 di 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 per sempre, ma potremmo ritirare le versioni bloccate che presentano problemi di sicurezza. In genere non forniamo assistenza per le versioni bloccate, tranne per suggerire inutilmente di eseguire l'upgrade a una versione più recente.

Carica impostazioni

Il secondo parametro nella chiamata a 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. I pacchetti da caricare sono elencati nella documentazione per ciascun tipo di grafico. Puoi evitare di specificare qualsiasi pacchetto se utilizzi ChartWrapper per caricare automaticamente ciò che sarà richiesto.
language
Il codice per la lingua o le impostazioni internazionali da utilizzare per personalizzare il testo che potrebbe far parte del grafico. Per ulteriori dettagli, consulta la sezione Lingue.
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. Vedi Callback per ulteriori dettagli. 
  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 invece di utilizzare il comportamento predefinito, che potrebbe comportare una limitazione occasionale del servizio per i tuoi utenti. Scopri come impostare la tua chiave per l'utilizzo del servizio "API Google Maps JavaScript" qui: Ottieni una chiave/autenticazione. Il codice sarà simile a questo: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Se il criterio viene impostato su true, tutti i grafici e le descrizioni comando che generano codice HTML a partire dai dati forniti dall'utente lo sanificeranno mediante l'eliminazione di elementi e attributi non sicuri. In alternativa (v49+), la libreria può essere caricata in modalità provvisoria utilizzando una scorciatoia che accetta le stesse impostazioni di caricamento, ma carica sempre la versione "attuale": 
  google.charts.safeLoad({ packages: ['corechart'] });

Lingue

Le locali vengono utilizzate per personalizzare il testo per un paese o una lingua, influenzando la formattazione dei valori, ad esempio valute, date e numeri.

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

Per caricare un grafico formattato per una lingua specifica, utilizza l'impostazione language in questo modo: 

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

Segui questo link per un esempio reale.

Richiamata

Prima di poter utilizzare uno qualsiasi dei pacchetti caricati da google.charts.load, devi attendere il completamento del caricamento. Non è sufficiente attendere il completamento del caricamento del documento. Poiché può essere necessario del tempo prima che il caricamento sia completato, devi registrare una funzione di callback. Ci sono tre modi per farlo. Specifica un'impostazione callback nella chiamata google.charts.load o chiama setOnLoadCallback passando una funzione come argomento oppure 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 della funzione fornita può essere una funzione con nome (devi solo assegnare il nome) o una funzione anonima. Al termine del caricamento dei pacchetti, questa funzione di callback viene 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 di callback utilizzando setOnLoadCallback oppure puoi combinarle in un'unica funzione. Scopri 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 tramite Promise

Un altro modo per registrare il callback è utilizzare la promessa restituita dalla chiamata google.charts.load. Per farlo, aggiungi una chiamata al metodo then() con un codice simile al seguente. 

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

Un vantaggio dell'utilizzo di Promise è che puoi disegnare facilmente più grafici semplicemente concatenando 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 dei grafici di Google utilizzavano 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 codice di caricamento della libreria precedente con quello nuovo. Tuttavia, tieni presente le limitazioni relative al caricamento delle librerie descritte sopra.