Chargement des bibliothèques
Cette page montre comment charger les bibliothèques de Google Chart.
Chargement de base des bibliothèques
À quelques exceptions près, toutes les pages Web avec Google Charts devraient 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: }); 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', cela entraîne le chargement de la dernière version officielle de Google Charts. Si vous voulez essayer la version candidate de 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 quand une nouvelle version est en cours. Une raison courante d’utiliser upcoming est que vous voulez tester un nouveau type de graphique ou une nouvelle fonctionnalité que Google est sur le point de publier dans un mois ou deux. (Nous annonçons les prochaines versions sur notre forum et nous vous recommandons de les essayer dès qu’elles sont annoncées, afin de vous assurer que 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, beignet, combo,chandelier, histogramme, dispersion). Si vous souhaitez un type de graphique différent ou supplémentaire, remplacez ou ajoutez le nom du package approprié pour corechart ci-dessus (par exemple, {packages: }. Vous pouvez trouver le nom du package dans la section « Chargement » de la page de documentation de chaque graphique.
Cet exemple suppose également que vous avez une fonction JavaScript nommée drawChart définie quelque part dans votre page Web. Vous pouvez nommer cette fonction comme vous le souhaitez, mais assurez-vous qu’elle est unique au niveau mondial et qu’elle est définie avant de la référencer dans votre appel àgoogle.charts.setOnLoadCallback.
Note : les versions précédentes de Google Charts utilisaient un code différent de celui présenté ci-dessus pour charger les bibliothèques. Pour mettre à jour vos graphiques existants en utilisant le nouveau code, consultez la section Mise à jour du code du chargeur de bibliothèque.
Voici un exemple complet de dessin d’un graphique circulaire utilisant la technique de chargement de base:
<head> <script src="https://www.gstatic.com/charts/loader.js"></script> <script> google.charts.load('current', {packages: }); 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(, , ]); // 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/></body>
Détails du chargement
Tout d’abord, vous devez charger le chargeur lui-même, ce qui est fait dans une balise script séparée avec src="https://www.gstatic.com/charts/loader.js". Cette balise peut être soit dans le head ou le body du document, soit être insérée dynamiquement dans le document pendant qu’il est chargé ou après que le chargement soit terminé.
<script src="https://www.gstatic.com/charts/loader.js"></script>
Une fois le chargeur chargé, vous êtes libre d’appeler google.charts.load. L’endroit où vous l’appelez peut être dans une balise script dans le head ou le body du document, et vous pourriez l’appeler soit pendant que le document est encore en train de se charger, soit n’importe quand après la fin du chargement.
À partir de la version 45, vous pouvez appeler google.charts.load plus d’une fois afin de charger des paquets supplémentaires, bien qu’il soit plus sûr 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 maintenant utiliser l’ancien paramètre URL JSAPI autoload, mais la valeur de ce paramètre doit utiliser un formatage JSON et un encodage URL stricts. En JavaScript, vous pouvez faire l’encodage de jsonObject avec ce code : encodeURIComponent(JSON.stringify(jsonObject)).
Limitations
Si vous utilisez des versions antérieures à la v45, il y a quelques limitations mineures mais importantes avec la façon dont vous chargez Google Charts :
- Vous ne pouvez appeler
google.charts.loadqu’une seule fois. Mais vous pouvez énumérer tous les paquets dont vous aurez besoin en un seul appel, il n’est donc pas nécessaire de faire des appels séparés. - Si vous utilisez un ChartWrapper, vous devez explicitement charger tous les paquets dont vous aurez besoin, plutôt que de compter sur le ChartWrapper pour les charger automatiquement pour vous.
- Pour Geochart et Map Chart, vous devez charger à la fois l’ancien chargeur de bibliothèque et le nouveau chargeur de bibliothèque. Encore une fois, cela ne concerne que les 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 la version
Le premier argument de votre appel google.charts.load est le nom ou le numéro de la version. Il n’y a que deux noms de version spéciaux pour le moment, et plusieurs versions gelées.
current C’est pour la dernière version officielle qui change à chaque fois que nous poussons une nouvelle version. Cette version est idéalement bien testée et sans bogue, mais vous pouvez vouloir spécifier une version gelée particulière à la place une fois que vous êtes satisfait qu’elle fonctionne. upcoming C’est pour la prochaine version, pendant qu’elle est encore en cours de test et avant qu’elle ne devienne la version officielle courante. Veuillez tester cette version régulièrement afin de savoir le plus rapidement possible s’il y a des problèmes à résoudre avant que cette version ne devienne la version officielle.
Lorsque nous publions de nouvelles versions de Google Charts, certains changements sont importants, comme des types de graphiques entièrement nouveaux. D’autres changements sont mineurs, comme des améliorations de l’apparence ou du comportement des graphiques existants.
De nombreux créateurs de Google Chart peaufinent l’apparence et la convivialité de leurs graphiques jusqu’à ce qu’ils correspondent exactement à ce qu’ils souhaitent. Certains créateurs pourraient se sentir plus à l’aise en sachant que leurscharts ne changeront jamais,quelles que soient les améliorations que nous apporterons à l’avenir. Pour ces utilisateurs, nous prenons en charge les cartes Google gelées.
Les versions gelées des cartes sont identifiées par un numéro et sont décrites dans nos versions officielles.Pour charger une version gelée, remplacez current ou upcoming dans votre appel de google.charts.load par le numéro de la version gelée :
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('43', {packages: }); google.charts.setOnLoadCallback(drawChart); ...</script>
Nous prévoyons que les versions gelées resteront disponibles indéfiniment,bien que nous puissions retirer les versions gelées qui présentent des problèmes de sécurité. Nous ne fournirons généralement pas de support pour les versions gelées, sauf pour vous suggérer utilement 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 pour spécifier les paramètres. Les propriétés suivantes sont prises en charge pour les paramètres.
paquets Un tableau de zéro ou plusieurs paquets. Chaque package qui est chargé aura le code requis pour supporter un ensemble de fonctionnalités, typiquement un type de graphique. Le ou les packages que vous devez charger sont listés dans la documentation de chaque type de graphique. Vous pouvez éviter de spécifier des packages si vous utilisez un ChartWrapper pour charger automatiquement ce qui sera nécessaire. language Le code de la langue ou de la locale à utiliser pour personnaliser le texte qui pourrait faire partie du graphique. Voir Locales pour plus de détails. callback Une fonction qui sera appelée une fois que les paquets auront été chargés. Alternativement, vous pouvez spécifier cette fonction en appelant
google.charts.setOnLoadCallbackcomme démontré dans l’exemple ci-dessus. Voir Callback pour plus de détails.
google.charts.load('current', { packages: , 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 vouloir faire cela plutôt que d’utiliser le comportement par défaut qui peut entraîner un étranglement occasionnel du service pour vos utilisateurs. Découvrez comment configurer votre propre clé pour utiliser le service « Google Maps JavaScript API » ici : Obtenir une clé/authentification. Votre code ressemblera à quelque chose comme ceci:
var myMapsApiKey = 'SomeMagicToSetThis'; google.charts.load('45', { packages: , mapsApiKey: myMapsApiKey });
safeMode (v47) Lorsqu’il est défini sur true, tous les graphiques et infobulles qui génèrent du HTML à partir de données fournies par l’utilisateur l’aseptiseront en supprimant les éléments et attributs non sûrs. Alternativement (v49+), la bibliothèque peut être chargée en mode sécurisé à l’aide d’un raccourci qui accepte les mêmes paramètres de chargement, mais charge toujours la version « actuelle » :
google.charts.safeLoad({ packages: });
Locales
Les locales sont utilisées pour personnaliser le texte pour un pays ou une langue, affectant le formatage de valeurs telles que les devises, les dates et les nombres.
Par défaut, les graphiques Google sont chargés avec la locale « en ». Vous pouvez remplacer cette valeur par défaut en spécifiant explicitement une locale dans les paramètres de chargement.
Pour charger un graphique formaté pour une locale spécifique, utilisez le paramètre language comme suit :
// Load Google Charts for the Japanese locale. google.charts.load('current', {'packages':, 'language': 'ja'});
Suivez ce lien pour un exemple vivant.
Callback
Avant de pouvoir utiliser l’un des paquets chargés par google.charts.load, vous devez attendre que le chargement se termine. Il ne suffit pas d’attendre la fin du chargement du document. Comme cela peut prendre un certain temps avant que ce chargement ne soit terminé, vous devez enregistrer une fonction de rappel. Il y a trois façons de procéder. Soit spécifier un paramètre callback dans votre appel google.charts.load, soit appeler setOnLoadCallback en passant une fonction comme argument, soit utiliser la Promise qui est retournée par l’appel de google.charts.load.
Notez que pour toutes ces façons, 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 suffit donc de donner son nom), soit une fonction anonyme. Lorsque le chargement des paquets est terminé, cette fonction de rappel est appelée sans argument. Le chargeur attendra également que le document ait fini de se charger avant d’appeler la fonction de rappel.
Si vous voulez dessiner plus d’un graphique, vous pouvez soit enregistrer plus d’une fonction de rappel en utilisant setOnLoadCallback, soit les combiner en une seule fonction. En savoir plus sur la façon de dessiner plusieurs graphiques sur une 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 est d’utiliser la Promise qui est retournée par l’appel google.charts.load. Vous le faites en ajoutant un appel à la méthode then() avec un code qui ressemble à ce qui suit .
google.charts.load('upcoming', {packages: }).then(drawChart);
Un avantage de l’utilisation de la Promesse est qu’alors vous pouvez facilement dessiner plus de graphiques simplement en enchaînant plus d’appels .then(anotherFunction). L’utilisation de la Promise lie également le callback aux paquets spécifiques requis pour ce callback, ce qui est important si vous voulez charger plus de paquets avec un autre appel de google.charts.load().
Mise à jour du code de chargement des bibliothèques
Les versions précédentes de Google Charts utilisaient un code différent pour charger les bibliothèques. Le tableau ci-dessous montre l’ancien code de chargeur de bibliothèque par rapport au nouveau.
<script type="text/javascript" src="https://www.google.com/jsapi"></script><script type="text/javascript"> google.load("visualization", "1", {packages:}); google.setOnLoadCallback(drawChart);</script>
<script src="https://www.gstatic.com/charts/loader.js"></script><script> google.charts.load('current', {packages: }); google.charts.setOnLoadCallback(drawChart);</script>
Pour mettre à jour vos graphiques existants, vous pouvez remplacer l’ancien code de chargeur de bibliothèque par le nouveau code.Cependant, gardez à l’esprit leslimitations sur le chargement des bibliothèques décrites ci-dessus.
Leave a Reply