Charger les bibliothèques

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

Chargement de base de la bibliothèque

À 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 spécifiques.

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 sera chargée. Si vous souhaitez tester la version candidate pour 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. L'utilisation de upcoming est souvent utilisée pour tester un nouveau type de graphique ou une nouvelle fonctionnalité que Google s'apprête à publier dans le mois ou les deux prochains mois. (Nous annonçons les versions à venir sur notre forum et nous vous recommandons de les essayer lorsqu'elles seront 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, ligne, aire, zone en escalier, bulle, graphique à secteurs, beignet, combinaison, chandelier, histogramme, nuage de points). Si vous souhaitez un type de graphique différent ou supplémentaire, remplacez ou ajoutez le nom de package approprié pour 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 qu'une fonction JavaScript nommée drawChart est définie 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 d'utiliser le nouveau code, consultez Mettre à jour le code du composant Loader de la 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>

Détails du chargement

Vous devez d'abord charger le chargeur lui-même, via une balise script distincte avec src="https://www.gstatic.com/charts/loader.js". Ce tag peut se trouver dans la section head ou body du document, ou être inséré dynamiquement dans le document pendant 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 du head ou de l'élément body du document. Vous pouvez l'appeler pendant ou après le chargement du document.

À partir de la version 45, vous pouvez appeler google.charts.load plusieurs fois pour charger des packages supplémentaires. Cette méthode est toutefois plus sûre si vous pouvez éviter de 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 répertorier tous les packages dont vous aurez besoin dans un seul appel. Il n'est donc pas nécessaire 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 compter sur ChartWrapper qu'il les charge automatiquement pour vous.
  3. Pour Geochart et Map Chart, vous devez charger à la fois l'ancien chargeur de bibliothèque et le nouveau. Là encore, cette opération ne concerne que les versions antérieures à la v45. Vous ne devez pas le faire pour les versions ultérieures. 
    <script src="https://www.gstatic.com/charts/loader.js"></script>
<script src="https://www.google.com/jsapi"></script>

Charger le nom ou le numéro de version

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

en cours
Il s'agit de la dernière version officielle, qui change chaque fois que nous publions une nouvelle version. Cette version est idéalement testée et ne présente aucun bug. Toutefois, vous pouvez spécifier une version figée particulière à la place lorsque vous êtes satisfait de son bon fonctionnement.
à venir
Cette version s'applique à la prochaine version, qui est encore en cours de test et avant qu'elle ne devienne la version actuelle officielle. Veuillez tester cette version régulièrement afin d'identifier le plus rapidement possible les problèmes à résoudre avant qu'elle ne devienne la sortie 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 des améliorations de l'apparence ou du comportement des graphiques existants.

De nombreux créateurs de graphiques Google ajustent l'apparence de leurs classements jusqu'à ce qu'ils le souhaitent. Certains créateurs se sentiront peut-être plus à l'aise de savoir que leurs classements ne changeront jamais, quelles que soient les améliorations que nous apporterons à l'avenir. Pour ces utilisateurs, nous acceptons les graphiques Google figés.

Les versions des graphiques figés sont identifiées par leur 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>

Les versions figées devraient rester disponibles indéfiniment, même si nous pouvons être amenés à supprimer les versions figées qui présentent 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 contenant zéro, un ou plusieurs packages. Chaque package chargé contiendra 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 susceptible de figurer dans le graphique. Pour en savoir plus, consultez la section Paramètres régionaux.
rappel
Fonction qui sera 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é à utiliser avec Geochart et Map Chart. Nous vous recommandons de procéder ainsi plutôt que d'utiliser le comportement par défaut, ce qui peut entraîner une limitation occasionnelle 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 doit ressembler à ceci : 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
safeMode
(v47) Lorsque 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 les nettoient en supprimant les éléments et attributs dangereux. Il est également possible (version 49 ou ultérieure) de charger la bibliothèque en mode sans échec à l'aide d'un raccourci qui accepte les mêmes paramètres de chargement, mais charge toujours la version "actuelle" : 
  google.charts.safeLoad({ packages: ['corechart'] });

Paramètres régionaux

Les paramètres régionaux permettent de personnaliser le texte en fonction d'un pays ou d'une langue, ce qui affecte la mise en forme des 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 des paramètres régionaux dans les paramètres de chargement.

Pour charger un graphique mis en forme pour des paramètres régionaux spécifiques, utilisez le paramètre language comme suit: 

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

Cliquez sur ce lien pour consulter un exemple en ligne.

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. Il existe trois façons d'y parvenir. 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, quelle que soit la méthode employée, 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 (donc il vous suffit de donner son 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 la fin du chargement du document 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 en une seule fonction. Découvrez comment dessiner plusieurs graphiques sur une seule 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 Promise

Une autre façon d'enregistrer votre rappel consiste à utiliser la promesse renvoyée par l'appel google.charts.load. Pour ce faire, ajoutez un appel à la méthode then() avec un code semblable à ce qui suit. 

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

L'un des avantages de la promesse est que vous pouvez facilement dessiner d'autres graphiques en enchaînant plus d'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 du chargeur de bibliothèque 
<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. Gardez toutefois à l'esprit les limites de chargement des bibliothèques décrites ci-dessus.