Charger les bibliothèques

Cette page explique comment charger les bibliothèques Google Charts.

Chargement de bibliothèque de base

À quelques exceptions près, toutes les pages Web comportant des graphiques Google doivent inclure les lignes suivantes dans la section <head> de la page Web:

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

La première ligne de cet exemple charge le chargeur lui-même. Vous ne pouvez charger le chargeur qu'une seule fois, quel que soit le nombre de graphiques que vous prévoyez de dessiner. Après avoir chargé le chargeur, vous pouvez appeler la fonction google.charts.load une ou plusieurs fois pour charger des packages pour des types de graphiques particuliers.

Le premier argument de google.charts.load est le nom ou le numéro de la version, sous forme de chaîne. Si vous spécifiez 'current', la dernière version officielle de Google Charts est chargée. Si vous souhaitez essayer la version candidate de la prochaine version, utilisez plutôt 'upcoming'. En général, il y a très peu de différence entre les deux et ils sont complètement identiques, sauf lorsqu'une nouvelle version est en cours de lancement. Une raison courante d'utiliser upcoming est que vous souhaitez tester un nouveau type de graphique ou une nouvelle fonctionnalité que Google est sur le point de lancer dans les mois à venir. (Nous annonçons les versions à venir sur notre forum et nous vous recommandons de les essayer une fois annoncées, pour vous assurer que toutes les modifications apportées à vos graphiques sont acceptables.)

L'exemple ci-dessus suppose que vous souhaitez afficher un corechart (barre, colonne, courbe, zone, zone en escalier, bulle, secteur, anneau, combiné, chandelier, histogramme, nuage de points). Si vous souhaitez utiliser un type de graphique différent ou supplémentaire, remplacez ou ajoutez le nom de package approprié à la place de corechart ci-dessus (par exemple, {packages: ['corechart', 'table', 'sankey']}. Vous trouverez le nom du package dans la section "Chargement" de la page de documentation de chaque graphique.

Cet exemple suppose également que vous avez défini une fonction JavaScript nommée drawChart quelque part sur votre page Web. Vous pouvez nommer cette fonction comme vous le souhaitez, mais assurez-vous qu'elle est unique et définie avant de la référencer dans votre appel à google.charts.setOnLoadCallback.

Remarque:Les versions précédentes de Google Charts utilisaient un code différent de celui indiqué ci-dessus pour charger les bibliothèques. Pour mettre à jour vos graphiques existants afin qu'ils utilisent le nouveau code, consultez Mettre à jour le code du chargeur de bibliothèque.

Voici un exemple complet de dessin d'un graphique à secteurs à l'aide de la technique de chargement de 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>

Chargement des informations

Vous devez d'abord charger le chargeur lui-même, ce qui se fait dans une balise script distincte avec src="https://www.gstatic.com/charts/loader.js". Cette balise peut se trouver dans le head ou le body du document, ou elle peut être insérée de manière dynamique dans le document pendant le chargement ou après le chargement. 

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

Une fois le chargeur chargé, vous pouvez appeler google.charts.load. Vous pouvez l'appeler dans une balise script dans le head ou le body du document, et vous pouvez l'appeler pendant le chargement du document ou à tout moment après la fin du chargement.

À partir de la version 45, vous pouvez appeler google.charts.load plusieurs fois pour charger des packages supplémentaires, mais il est préférable de ne pas le faire. Vous devez fournir le même numéro de version et les mêmes paramètres de langue à chaque fois.

Vous pouvez désormais utiliser l'ancien paramètre d'URL autoload JSAPI, mais sa valeur doit utiliser une mise en forme JSON et un encodage d'URL stricts. En JavaScript, vous pouvez encoder jsonObject à l'aide du code suivant : encodeURIComponent(JSON.stringify(jsonObject)).

Limites

Si vous utilisez des versions antérieures à la version 45, il existe quelques limites mineures, mais importantes, concernant le chargement de Google Charts:

  1. Vous ne pouvez appeler google.charts.load qu'une seule fois. Toutefois, vous pouvez lister tous les packages dont vous aurez besoin en un seul appel, ce qui vous évite d'effectuer des appels distincts.
  2. Si vous utilisez un ChartWrapper, vous devez charger explicitement tous les packages dont vous avez besoin, plutôt que de vous fier au ChartWrapper pour les charger automatiquement à votre place.
  3. Pour Geochart et Map Chart, vous devez charger à la fois l'ancien chargeur de bibliothèque et le nouveau. Encore une fois, cette opération ne concerne que les versions antérieures à la version 45. Vous ne devez pas effectuer cette opération pour les versions ultérieures. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Nom ou numéro de la version de charge

Le premier argument de votre appel google.charts.load est le nom ou le numéro de la version. Il n'existe actuellement que deux noms de versions spéciales et plusieurs versions figées.

actuellement
Il s'agit de la dernière version officielle, qui change chaque fois que nous publions une nouvelle version. Idéalement, cette version doit être bien testée et exempte de bugs, mais vous pouvez spécifier une version congelée particulière une fois que vous êtes convaincu qu'elle fonctionne.
à venir
Cette version s'applique à la prochaine version, qui est toujours en cours de test et avant qu'elle ne devienne la version actuelle officielle. Veuillez tester cette version régulièrement afin de savoir dès que possible s'il existe des problèmes à résoudre avant que cette version ne devienne la version officielle.

Lorsque nous publions de nouvelles versions de Google Charts, certaines modifications sont importantes, comme de nouveaux types de graphiques. D'autres modifications sont mineures, comme l'amélioration de l'apparence ou du comportement des graphiques existants.

De nombreux créateurs de graphiques Google ajustent l'apparence de leurs graphiques jusqu'à ce qu'ils correspondent exactement à ce qu'ils souhaitent. Certains créateurs peuvent se sentir plus à l'aise en sachant que leurs classements ne changeront jamais, quelles que soient les améliorations que nous apporterons à l'avenir. Pour ces utilisateurs, nous prenons en charge les graphiques Google figés.

Les versions de graphiques figées sont identifiées par un numéro et décrites dans nos versions officielles. Pour charger une version figée, remplacez current ou upcoming dans votre appel de google.charts.load par le numéro de la version figée:

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

Nous nous attendons à ce que les versions congelées restent disponibles indéfiniment, bien que nous puissions abandonner les versions congelées présentant des problèmes de sécurité. Nous ne fournissons généralement pas d'assistance pour les versions figées, sauf pour vous suggérer inutilement une mise à niveau vers une version plus récente.

Charger les paramètres

Le deuxième paramètre de votre appel de google.charts.load est un objet permettant de spécifier des paramètres. Les propriétés suivantes sont prises en charge pour les paramètres.

colis
Tableau de zéro ou plusieurs packages. Chaque package chargé contient le code requis pour prendre en charge un ensemble de fonctionnalités, généralement un type de graphique. Le ou les packages que vous devez charger sont répertoriés dans la documentation de chaque type de graphique. Vous pouvez éviter de spécifier des packages si vous utilisez ChartWrapper pour charger automatiquement les éléments nécessaires.
language
Code de la langue ou des paramètres régionaux à utiliser pour personnaliser le texte pouvant faire partie du graphique. Pour en savoir plus, consultez la section Paramètres régionaux.
rappel
Fonction appelée une fois les packages chargés. Vous pouvez également spécifier cette fonction en appelant google.charts.setOnLoadCallback, comme illustré dans l'exemple ci-dessus. Pour en savoir plus, consultez la section Rappel. 
  google.charts.load('current', { packages: [ 'corechart'], callback: drawChart });
mapsApiKey
(v45) Ce paramètre vous permet de spécifier une clé que vous pouvez utiliser avec Geochart et Map Chart. Vous pouvez choisir de procéder ainsi plutôt que d'utiliser le comportement par défaut, qui peut entraîner un débit limité occasionnel du service pour vos utilisateurs. Découvrez comment configurer votre propre clé pour utiliser le service "API Google Maps JavaScript" : Obtenir une clé/Authentification. Votre code se présentera comme suit: 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Si cette valeur est définie sur "true", tous les graphiques et les info-bulles qui génèrent du code HTML à partir de données fournies par l'utilisateur le nettoient en supprimant les éléments et attributs dangereux. Vous pouvez également (version 49 et versions ultérieures) charger la bibliothèque en mode sans échec à l'aide d'un raccourci qui accepte les mêmes paramètres de chargement, mais qui charge toujours la version "actuelle" : 
  google.charts.safeLoad({ packages: ['corechart'] });

Paramètres régionaux

Les paramètres régionaux permettent de personnaliser le texte pour un pays ou une langue, ce qui affecte la mise en forme de valeurs telles que les devises, les dates et les nombres.

Par défaut, Google Charts est chargé avec les paramètres régionaux "en". Vous pouvez remplacer cette valeur par défaut en spécifiant explicitement une langue dans les paramètres de chargement.

Pour charger un graphique formaté pour une langue spécifique, utilisez le paramètre language comme suit: 

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

Suivez ce lien pour voir un exemple en direct.

Rappel

Avant de pouvoir utiliser l'un des packages chargés par google.charts.load, vous devez attendre la fin du chargement. Il ne suffit pas d'attendre la fin du chargement du document. Comme ce chargement peut prendre un certain temps, vous devez enregistrer une fonction de rappel. Vous pouvez le faire de trois manières. Spécifiez un paramètre callback dans votre appel google.charts.load, appelez setOnLoadCallback en transmettant une fonction en tant qu'argument, ou utilisez la promesse renvoyée par l'appel de google.charts.load.

Notez que, malgré toutes ces méthodes, vous devez fournir une définition de fonction, plutôt que de l'appeler. La définition de fonction que vous fournissez peut être une fonction nommée (vous n'avez donc qu'à lui donner un nom) ou une fonction anonyme. Une fois le chargement des packages terminé, cette fonction de rappel est appelée sans argument. Le chargeur attend également que le document soit entièrement chargé avant d'appeler le rappel.

Si vous souhaitez dessiner plusieurs graphiques, vous pouvez enregistrer plusieurs fonctions de rappel à l'aide de setOnLoadCallback ou les combiner dans une seule fonction. Découvrez comment dessiner plusieurs graphiques sur une même page. 

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

Rappel via une promesse

Vous pouvez également enregistrer votre rappel à l'aide de la promesse renvoyée par l'appel google.charts.load. Pour ce faire, ajoutez un appel à la méthode then() avec un code semblable au suivant. 

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

L'un des avantages de l'utilisation de la promesse est que vous pouvez facilement dessiner d'autres graphiques en enchaînant simplement d'autres appels .then(anotherFunction). L'utilisation de la promesse lie également le rappel aux packages spécifiques requis pour ce rappel, ce qui est important si vous souhaitez charger d'autres packages avec un autre appel de google.charts.load().

Mettre à jour le code du chargeur de bibliothèque

Les versions précédentes de Google Charts utilisaient un code différent pour charger les bibliothèques. Le tableau ci-dessous compare l'ancien code du chargeur de bibliothèque au nouveau.

Ancien code du chargeur de bibliothèque 
<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>
Nouveau code Library Loader 
<script src="https://www.gstatic.com/charts/loader.js"></script>
<script>
  google.charts.load('current', {packages: ['corechart']});
  google.charts.setOnLoadCallback(drawChart);
</script>

Pour mettre à jour vos graphiques existants, vous pouvez remplacer l'ancien code du chargeur de bibliothèque par le nouveau. Toutefois, gardez à l'esprit les limites concernant le chargement des bibliothèques décrites ci-dessus.