Carica le librerie

Questa pagina mostra come caricare le librerie di Google Chart.

Caricamento di base della libreria

Con poche eccezioni, tutte le pagine web con i grafici Google 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 solo una volta, indipendentemente dal numero di grafici che intendi disegnare. Dopo aver caricato il caricatore, puoi chiamare la funzione google.charts.load una o più volte per caricare i pacchetti per particolari tipi di grafico.

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 release, usa invece 'upcoming'. In generale, ci saranno pochissime differenze tra i due tipi e saranno completamente identici, tranne quando è in corso una nuova release. Un motivo comune per usare upcoming è che vuoi testare un nuovo tipo di grafico o una nuova funzionalità che Google sta per rilasciare nei prossimi due mesi. Annunciamo le prossime uscite nel forum e ti consigliamo di provarle una volta annunciate per assicurarti che le modifiche ai grafici siano accettabili.

Per l'esempio precedente si presuppone che tu voglia visualizzare un corechart (barra, colonna, linea, area, area con passi, bolla, torta, ciambella, combinazione, candeliere, istogramma, dispersione). Se vuoi un tipo di grafico diverso o aggiuntivo, sostituisci o aggiungi il nome del pacchetto appropriato per corechart sopra (ad esempio, {packages: ['corechart', 'table', 'sankey']}. Puoi trovare il nome del pacchetto nella sezione "Caricamento" di ogni grafico nella pagina della documentazione.

Anche questo esempio presuppone che tu abbia una funzione JavaScript denominata drawChart definita da qualche parte nella tua pagina web. Puoi assegnare il nome alla funzione 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 Classifiche Google utilizzavano codice che differisce da quello 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 disegno di un grafico a torta con 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>

Caricamento dei dettagli

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

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

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

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

Ora puoi utilizzare il precedente parametro URL autoload JSAPI, ma il valore di questo parametro deve utilizzare una 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 le versioni precedenti alla v45, esistono alcune limitazioni minori ma importanti relative alla modalità di caricamento dei grafici Google:

  1. Puoi chiamare google.charts.load una sola volta. Tuttavia, puoi elencare tutti i pacchetti necessari per una chiamata, quindi non è necessario effettuare chiamate separate.
  2. Se utilizzi ChartWrapper, devi caricare esplicitamente tutti i pacchetti necessari, invece di fare affidamento su ChartWrapper, in modo da caricarli automaticamente.
  3. Per Grafico geografico e Grafico di mappa, devi caricare sia il precedente caricatore della libreria sia quello nuovo. Anche in questo caso, l'operazione è solo per le versioni precedenti alla v45 e non dovrai eseguire questa operazione per le versioni successive.
    <script src="https://www.gstatic.com/charts/loader.js"></script>
    <script src="https://www.google.com/jsapi"></script>

Caricare il nome o il numero di versione

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

current
Questa versione riguarda l'ultima release ufficiale che cambia ogni volta che ne estendiamo una nuova. Questa versione è idealmente testata e priva di bug, ma ti consigliamo di specificare una determinata versione bloccata quando ritieni che funzioni.
(In programma)
Questa è la prossima release, che è ancora in fase di test e prima che diventi la release ufficiale ufficiale. Testa regolarmente questa versione per sapere appena possibile se ci sono problemi da risolvere prima che la versione diventi ufficiale.

Quando vengono rilasciate nuove versioni di Google Classifiche, alcune delle modifiche più importanti, come i tipi di grafici completamente nuovi, Altre modifiche sono di piccola entità, ad esempio miglioramenti all'aspetto o al comportamento dei grafici esistenti.

Molti creator di classifiche Google ottimizzano l'aspetto dei grafici per renderli esattamente ciò che vogliono. Alcuni creator potrebbero sentirsi più a loro agio con l'idea che i loro grafici non cambieranno mai, a prescindere dai miglioramenti che faremo in futuro. Per questi utenti, supportiamo i grafici Google bloccati.

Le versioni dei grafici bloccati sono identificate da un numero e sono descritte nelle nostre versioni ufficiali. Per caricare una versione bloccata, sostituisci current o upcoming nella chiamata a 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 ritirarle per qualsiasi problema di sicurezza. In genere, non forniamo assistenza per le versioni bloccate, con l'eccezione di non suggerire inutilmente l'upgrade a una versione più recente.

Carica impostazioni

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

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 che devi caricare sono elencati nella documentazione per ciascun tipo di grafico. Puoi evitare di specificare pacchetti qualsiasi se utilizzi un ChartWrapper per caricare automaticamente ciò che sarà richiesto.
language
Il codice per la lingua o la lingua che dovrebbe essere personalizzato per il testo che potrebbe far parte del grafico. Per ulteriori dettagli, consulta la pagina Locales.
callback
Una funzione che verrà chiamata dopo il caricamento dei pacchetti. In alternativa, puoi specificare questa funzione chiamando google.charts.setOnLoadCallback come mostrato nell'esempio sopra. Consulta Callback per ulteriori dettagli.
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
MapsApiKey
(v45) Questa impostazione consente di specificare una chiave che potresti utilizzare con grafico geografico e grafico mappa. Ti consigliamo di eseguire questa operazione anziché utilizzare il comportamento predefinito che potrebbe causare limitazioni occasionali del servizio per gli utenti. Scopri come configurare la tua chiave per l'utilizzo del 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 viene impostato su true, tutti i grafici e le descrizioni comando che generano HTML dai dati forniti dall'utente lo saniteranno eliminando gli elementi e gli 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 "corrente":
  google.charts.safeLoad({ packages: ['corechart'] });

Lingue

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

Per impostazione predefinita, i grafici di Google cambiare sono con l'impostazione "en". Puoi sostituire questo valore predefinito specificando esplicitamente un'impostazione internazionale nelle impostazioni di caricamento.

Per caricare un grafico formattato per un'area geografica 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 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 setOnLoadCallback passare una funzione come argomento oppure utilizza la promessa restituita dalla chiamata google.charts.load.

Tieni presente che, in tutti questi modi, devi fornire una definizione della funzione, anziché chiamare la funzione. La definizione di funzione che fornisci può essere una funzione con nome (per cui ti basta dare il nome) o una funzione anonima. Al termine del caricamento dei pacchetti, questa funzione di callback verrà richiamata senza argomenti. Inoltre, il caricatore attende che il caricamento del documento termini 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 una sola 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();
      });

Richiamata tramite Promise

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

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

Uno dei vantaggi di Promise è che puoi disegnare facilmente più grafici concatenando più chiamate .then(anotherFunction). L'utilizzo di Promise associa anche il callback ai pacchetti specifici richiesti per tale callback, che è importante se vuoi caricare altri pacchetti con un'altra chiamata 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 vecchio codice di caricamento della libreria rispetto al nuovo.

Codice caricatore di 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 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 del caricatore precedente con quello nuovo. Tuttavia, tieni presente le limitazioni di caricamento delle librerie descritte sopra.