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 contenant des graphiques Google doivent inclure les lignes suivantes dans le <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 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 le candidat pour la prochaine version, utilisez plutôt 'upcoming'. En général, il y aura très peu de différence entre les deux, et ils seront complètement identiques, sauf lorsqu'une nouvelle version est en cours. L'une des raisons courantes d'utiliser upcoming est que vous souhaitez tester un nouveau type de graphique ou une nouvelle fonctionnalité que Google est sur le point de publier dans un ou deux mois. (Nous annonçons les prochaines versions sur notre forum et nous vous recommandons de les tester lorsqu'elles sont annoncées, afin de 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, zone, zone en escalier, bulle, tarte, donut, combinaison, bouchon, 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é 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 que vous disposez d'une fonction JavaScript nommée drawChart 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 du code différent de ce qui précède pour charger les bibliothèques. Pour mettre à jour vos graphiques existants afin qu'ils utilisent le nouveau code, consultez la page Mettre à jour le code du chargeur de bibliothèque.

Voici un exemple complet de dessin de graphique à secteurs avec 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

Tout d'abord, vous devez charger le chargeur lui-même, dans une balise script distincte avec src="https://www.gstatic.com/charts/loader.js". Cette balise peut se trouver dans la section head ou body du document, ou être insérée de manière dynamique lors de son chargement ou une fois celui-ci terminé. 

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

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

Depuis la version 45, vous pouvez appeler google.charts.load plusieurs fois pour charger des packages supplémentaires, mais il est plus sûr 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 maintenant utiliser l'ancien paramètre d'URL autoload JSAPI, mais sa valeur doit respecter un format JSON et un encodage d'URL stricts. En JavaScript, vous pouvez effectuer l'encodage de jsonObject avec le code suivant : encodeURIComponent(JSON.stringify(jsonObject)).

Limites

Si vous utilisez des versions antérieures à la version 44, le chargement de Google Charts présente des limitations mineures, mais importantes:

  1. Vous ne pouvez appeler google.charts.load qu'une seule fois. Cependant, vous pouvez lister tous les packages dont vous aurez besoin en un seul appel. Vous n'avez donc pas besoin d'effectuer des appels distincts.
  2. Si vous utilisez un ChartWrapper, vous devez charger explicitement tous les packages dont vous avez besoin, au lieu de compter sur l'outil ChartWrapper pour qu'il les charge automatiquement pour vous.
  3. Pour Geochart et Map Chart, vous devez charger à la fois l'ancien outil de chargement des bibliothèques et le nouveau. Encore une fois, il s'agit uniquement des versions antérieures à la v45, et 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 version. Il n'existe actuellement que deux noms de version spéciaux 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. Dans l'idéal, cette version doit être testée correctement et ne doit pas présenter de bugs. Toutefois, nous vous conseillons de spécifier une version bloquée spécifique lorsque vous serez satisfait du résultat.
à venir
Il s'agit de la version suivante, alors qu'elle est encore en phase de test et qu'elle devient la version officielle. Veuillez tester régulièrement cette version pour savoir dès que possible s'il y a des problèmes à résoudre avant qu'elle ne soit publiée.

Lorsque nous lançons de nouvelles versions de Google Charts, nous apportons certaines modifications importantes, comme de nouveaux types de graphiques. D'autres changements sont minimes, comme des améliorations de l'apparence ou du comportement des graphiques existants.

De nombreux créateurs Google Charts peaufinent l'apparence de leurs graphiques jusqu'à ce qu'ils répondent exactement à leurs besoins. Certains créateurs seront plus à l'aise avec l'idée que leurs charts ne seront jamais modifiés, quelles que soient les améliorations que nous apporterons à l'avenir. Pour ces utilisateurs, nous prenons en charge les graphiques Google gelés.

Les versions des graphiques figés sont identifiées par leur numéro et sont décrites dans nos versions officielles. Pour charger une version bloquée, remplacez current ou upcoming dans votre appel de google.charts.load par le numéro de la version bloqué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 supprimer les versions figées qui présentent des problèmes de sécurité. En général, nous ne proposons pas d'assistance pour les versions figées, sauf pour vous suggérer accidentellement de passer à 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 acceptées pour les paramètres.

colis
Tableau de zéro, un ou plusieurs packages. Chaque package chargé dispose du code nécessaire pour accepter 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 ce qui sera nécessaire.
language
Code de la langue ou des paramètres régionaux qui doivent servir à personnaliser le texte qui pourrait faire partie du graphique. Pour en savoir plus, consultez 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 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. Nous vous recommandons d'utiliser cette fonctionnalité plutôt que le comportement par défaut, qui peut entraîner une limitation occasionnelle du service pour vos utilisateurs. Découvrez comment configurer votre propre clé pour l'utilisation du service "API Google Maps JavaScript" : Obtenir une clé/authentification. Votre code doit se présenter comme suit : 
  var myMapsApiKey = 'SomeMagicToSetThis';
  google.charts.load('45', { packages: [ 'geochart'], mapsApiKey: myMapsApiKey  });
mode sans échec
(v47) Lorsque ce paramètre est défini sur "true", tous les graphiques et les info-bulles qui génèrent du code HTML à partir de données fournies par les utilisateurs les nettoient en supprimant les éléments et les attributs dangereux. Vous pouvez également charger la bibliothèque en mode sans échec (à partir de la version 49) à 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 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, les charts Google sont chargés 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 mis en forme pour un paramètre régional spécifique, 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 voir un exemple en direct.

Callback

Avant de pouvoir utiliser les 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. Étant donné que le chargement peut prendre un certain temps, vous devez enregistrer une fonction de rappel. Vous pouvez procéder de trois manières. Spécifiez un paramètre callback dans votre appel google.charts.load ou 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 pour toutes ces méthodes, vous devez fournir une définition de fonction plutôt que d'appeler la fonction. La définition de fonction que vous fournissez peut être soit une fonction nommée (il vous suffit donc de donner son nom), soit 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 à celui-ci : 

  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 plus de 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 et le 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 de 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 code. Toutefois, tenez compte des limites de chargement des bibliothèques décrites ci-dessus.