Présentation
Les tableaux de bord sont un moyen simple d'organiser et de gérer plusieurs graphiques partageant les mêmes données sous-jacentes. Grâce aux API décrites sur cette page, vous n'avez plus à vous soucier du câblage ni de la coordination des graphiques qui font partie d'un tableau de bord.
Les tableaux de bord sont définis à l'aide de classes google.visualization.Dashboard
.
Les instances Dashboard
reçoivent un DataTable
contenant les données pour visualiser et prendre en charge la distribution et l'affichage des données sur tous les graphiques qui font partie du tableau de bord.
Les commandes sont des widgets d'interface utilisateur (tels que des sélecteurs de catégorie, des curseurs de plage, des saisies semi-automatiques, etc.) avec lesquels vous interagissez pour générer les données gérées par un tableau de bord et les graphiques qui en font partie.
Les commandes sont définies à l'aide de classes google.visualization.ControlWrapper
.
Vous pouvez ajouter des instances ControlWrapper
à un tableau de bord, où elles se comportent comme des canalisations et des vannes dans un système de plomberie. Ils recueillent les entrées utilisateur et utilisent ces informations pour décider quelles données sont gérées par le tableau de bord dans les graphiques qui en font partie.
Examinons l'exemple suivant, où un sélecteur de catégorie et un curseur de plage permettent de générer les données visualisées par un graphique à secteurs.
Remarque : Le tableau de bord est interactif. Essayez d'utiliser les commandes et observez l'évolution du graphique en temps réel.
Utiliser des commandes et des tableaux de bord
Voici les principales étapes à suivre pour créer un tableau de bord et l'intégrer à votre page. Vous trouverez ci-dessous un extrait de code illustrant toutes ces étapes, ainsi que des informations détaillées sur chacune d'elles.
- Créer un squelette HTML pour votre tableau de bord Votre page doit comporter autant d'éléments HTML que nécessaire pour pouvoir contenir tous les membres d'un tableau de bord. Cela inclut le tableau de bord lui-même, ainsi que toutes les commandes et tous les graphiques qu'il contient. Généralement, vous devez utiliser un tag <div> pour chacun d'eux.
-
Chargez vos bibliothèques. Un tableau de bord ne nécessite que deux bibliothèques à inclure ou charger sur la page: l'API Google AJAX et le package
controls
de visualisation Google. - Préparez vos données. Vous devrez préparer les données à visualiser. Cela signifie que vous devez spécifier vous-même les données dans le code ou interroger un site distant pour obtenir des données.
- Créez une instance de tableau de bord. Instanciez votre tableau de bord en appelant son constructeur et en transmettant une référence à l'élément <div> qui le contiendra.
-
Créez autant d'instances de commande et de graphique que nécessaire.
Créez des instances
google.visualization.ChartWrapper
etgoogle.visualization.ControlWrapper
pour décrire chaque graphique et commande contrôlé par le tableau de bord. -
Établissez des dépendances. Appelez
bind()
sur votre tableau de bord et transmettez les instances de contrôle et de graphique pour indiquer au tableau de bord les éléments à gérer. Une fois qu'un contrôle et un graphique sont liés, le tableau de bord met à jour le graphique pour correspondre aux contraintes appliquées par le contrôle sur les données. -
Dessinez votre tableau de bord. Appelez
draw()
sur votre tableau de bord et transmettez vos données pour dessiner l'intégralité du tableau de bord sur la page. - Modifications programmatiques après tirage Une fois le tracé initial terminé, vous pouvez éventuellement piloter les commandes qui font partie du tableau de bord, et le tableau de bord doit alors mettre à jour les graphiques.
Voici un exemple simple de page créant un tableau de bord simple avec un curseur de plage qui génère un graphique à secteurs. Le tableau de bord obtenu est affiché sous l'extrait.
<html> <head> <!--Load the AJAX API--> <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script> <script type="text/javascript"> // Load the Visualization API and the controls package. google.charts.load('current', {'packages':['corechart', 'controls']}); // Set a callback to run when the Google Visualization API is loaded. google.charts.setOnLoadCallback(drawDashboard); // Callback that creates and populates a data table, // instantiates a dashboard, a range slider and a pie chart, // passes in the data and draws it. function drawDashboard() { // Create our data table. var data = google.visualization.arrayToDataTable([ ['Name', 'Donuts eaten'], ['Michael' , 5], ['Elisa', 7], ['Robert', 3], ['John', 2], ['Jessica', 6], ['Aaron', 1], ['Margareth', 8] ]); // Create a dashboard. var dashboard = new google.visualization.Dashboard( document.getElementById('dashboard_div')); // Create a range slider, passing some options var donutRangeSlider = new google.visualization.ControlWrapper({ 'controlType': 'NumberRangeFilter', 'containerId': 'filter_div', 'options': { 'filterColumnLabel': 'Donuts eaten' } }); // Create a pie chart, passing some options var pieChart = new google.visualization.ChartWrapper({ 'chartType': 'PieChart', 'containerId': 'chart_div', 'options': { 'width': 300, 'height': 300, 'pieSliceText': 'value', 'legend': 'right' } }); // Establish dependencies, declaring that 'filter' drives 'pieChart', // so that the pie chart will only display entries that are let through // given the chosen slider range. dashboard.bind(donutRangeSlider, pieChart); // Draw the dashboard. dashboard.draw(data); } </script> </head> <body> <!--Div that will hold the dashboard--> <div id="dashboard_div"> <!--Divs that will hold each control and chart--> <div id="filter_div"></div> <div id="chart_div"></div> </div> </body> </html>
Voici le tableau de bord créé par ce code.
1. Créer un squelette HTML pour votre tableau de bord
Votre page doit comporter autant d'éléments HTML (généralement des balises <div>) que le tableau de bord lui-même, ainsi que l'ensemble des commandes et des graphiques. Lorsque vous instanciez des instances de tableau de bord, de contrôle et de graphique, vous devez transmettre une référence à leur élément. Attribuez donc un ID à chaque élément HTML.
<!--Div that will hold the dashboard--> <div id="dashboard_div"> <!--Divs that will hold each control and chart--> <div id="filter_div"></div> <div id="chart_div"></div> </div>
Vous êtes libre de positionner chaque élément HTML comme bon vous semble.
2. Chargez vos bibliothèques
Un tableau de bord ne nécessite que deux bibliothèques à inclure ou charger sur la page: l'API Google AJAX et le package controls
de visualisation Google. L'API (en particulier google.visualization.ChartWrapper
) identifie automatiquement les autres packages nécessaires (par exemple, gauge
si vous utilisez un graphique Gauge) et les charge à la volée sans que vous ayez besoin d'intervenir.
Vous devez utiliser google.charts.load()
pour récupérer la bibliothèque de contrôle.
<!--Load the AJAX API--> <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script> <script type="text/javascript"> // Load the Visualization API and the controls package. // Packages for all the other charts you need will be loaded // automatically by the system. google.charts.load('current', {'packages':['corechart', 'controls']}); // Set a callback to run when the Google Visualization API is loaded. google.charts.setOnLoadCallback(drawDashboard); function drawDashboard() { // Everything is loaded. Assemble your dashboard... } </script>
3. Préparer vos données
Une fois l'API de visualisation chargée, google.charts.setOnLoadCallback()
appelle votre fonction de gestionnaire. Vous savez ainsi que toutes les méthodes et classes d'assistance requises sont prêtes pour que vous puissiez commencer à préparer vos données.
Les tableaux de bord acceptent les données dans un tableau de données, comme les graphiques.
4. Créer une instance de tableau de bord
Une fois les données créées, vous pouvez instancier l'objet de votre tableau de bord. Un constructeur de tableau de bord utilise un paramètre: une référence à l'élément DOM dans lequel dessiner le tableau de bord.
var dashboard = new google.visualization.Dashboard(document.getElementById('dashboard_div'));
Les tableaux de bord sont exposés en tant que classe JavaScript. Après avoir instancié votre tableau de bord, vous pouvez effectuer quelques étapes facultatives, telles que l'ajout d'écouteurs d'événements (par exemple, pour être averti une fois que le tableau de bord est "prêt"). Les tableaux de bord gèrent les événements de la même manière que les graphiques. Par conséquent, reportez-vous aux sections Gérer les événements de visualisation ou Afficher correctement les erreurs dans la section des graphiques pour en savoir plus.
5. Créer des instances de commande et de graphique
Définissez autant d'instances que nécessaire pour chaque commande et graphique qui fera partie du tableau de bord.
Utilisez
google.visualization.ChartWrapper
et
google.visualization.ControlWrapper
pour définir des graphiques et des commandes, respectivement.
// Create a range slider, passing some options var donutRangeSlider = new google.visualization.ControlWrapper({ 'controlType': 'NumberRangeFilter', 'containerId': 'filter_div', 'options': { 'filterColumnLabel': 'Donuts eaten' } }); // Create a pie chart, passing some options var pieChart = new google.visualization.ChartWrapper({ 'chartType': 'PieChart', 'containerId': 'chart_div', 'options': { 'width': 300, 'height': 300, 'pieSliceText': 'label' } });
Lorsque vous créez des instances ChartWrapper
et ControlWrapper
, ne spécifiez ni le paramètre dataTable
, ni le paramètre dataSourceUrl
. Le tableau de bord s'occupe de fournir à chacun d'entre elles les données appropriées. Toutefois, veillez à spécifier les paramètres requis: chartType
et containerId
pour les graphiques, controlType
et containerId
pour les commandes.
Voici quelques conseils concernant la configuration des commandes et des graphiques:
-
Vous devez attribuer le rôle
filterColumnIndex
(oufilterColumnLabel
) à toutes les commandes pour spécifier la colonne degoogle.visualization.DataTable
qui les concerne (dans l'exemple ci-dessus, la commande s'exécute sur la colonne Donuts absorbés). -
Utilisez l'option de configuration
state
sur les commandes pour les initialiser avec un état explicite lorsqu'elles sont dessinées pour la première fois. Utilisez par exemple ce paramètre pour corriger la position initiale des pouces d'un curseur de plage.var donutRangeSlider = new google.visualization.ControlWrapper({ 'controlType': 'NumberRangeFilter', 'containerId': 'filter_div', 'options': { 'filterColumnLabel': 'Donuts eaten', 'minValue': 1, 'maxValue': 10 }, // Explicitly positions the thumbs at position 3 and 8, // out of the possible range of 1 to 10. 'state': {'lowValue': 3, 'highValue': 8} });
-
Tous les graphiques d'un tableau de bord partagent le même tableau de données sous-jacent que vous avez préparé à l'étape Préparer vos données. Cependant, les graphiques nécessitent souvent un agencement spécifique des colonnes pour s'afficher correctement. Par exemple, un graphique à secteurs nécessite une colonne de chaîne pour l'étiquette, suivie d'une colonne numérique pour la valeur.
Utilisez l'option
view
lors de la configuration de chaque instanceChartWrapper
pour déclarer les colonnes pertinentes pour le graphique, comme dans l'exemple suivant.var data = google.visualization.arrayToDataTable([ ['Name', 'Gender', 'Age', 'Donuts eaten'], ['Michael' , 'Male', 12, 5], ['Elisa', 'Female', 20, 7], ['Robert', 'Male', 7, 3], ['John', 'Male', 54, 2], ['Jessica', 'Female', 22, 6], ['Aaron', 'Male', 3, 1], ['Margareth', 'Female', 42, 8] ]); var pieChart = new google.visualization.ChartWrapper({ 'chartType': 'PieChart', 'containerId': 'chart_div', 'options': { 'width': 300, 'height': 300, 'title': 'Donuts eaten per person' }, // The pie chart will use the columns 'Name' and 'Donuts eaten' // out of all the available ones. 'view': {'columns': [0, 3]} }); // The rest of dashboard configuration follows // ...
6. Établir des dépendances
Une fois que vous avez instancié à la fois le tableau de bord et tous les contrôles et graphiques qui en font partie, utilisez la méthode bind()
pour indiquer au tableau de bord les dépendances existantes entre les commandes et les graphiques.
Une fois qu'un contrôle et un graphique sont liés, le tableau de bord met à jour le graphique pour correspondre aux contraintes appliquées par le contrôle sur les données. Dans l'exemple de tableau de bord que vous créez, le curseur de plage et le graphique à secteurs sont liés. Ainsi, chaque fois que vous interagissez avec le premier, le deuxième est mis à jour pour n'afficher que les données correspondant à la plage sélectionnée.
// 'pieChart' will update whenever you interact with 'donutRangeSlider' // to match the selected range. dashboard.bind(donutRangeSlider, pieChart);
Vous pouvez lier les commandes et les graphiques dans de nombreuses configurations différentes: un à un, un à plusieurs, plusieurs à un et plusieurs à plusieurs. Lorsque plusieurs commandes sont liées à un graphique, le tableau de bord met à jour le graphique afin de correspondre aux contraintes combinées appliquées par toutes les commandes liées. Dans le même temps, une commande peut générer plusieurs graphiques simultanément. Pour spécifier plusieurs liaisons en même temps, transmettez des tableaux à la méthode bind()
au lieu d'utiliser des instances uniques. Vous pouvez également relier plusieurs appels bind()
. Voici quelques exemples.
// Many-to-one binding where 'ageSelector' and 'salarySelector' concurrently // participate in selecting which data 'ageVsSalaryScatterPlot' visualizes. dashboard.bind([agePicker, salaryPicker], ageVsSalaryScatterPlot); // One-to-many binding where 'ageSelector' drives two charts. dashboard.bind(agePicker, [ageVsSalaryScatterPlot, ageBarChart]); // bind() chaining where each control drives its own chart. dashboard.bind(agePicker, ageBarChart).bind(salaryRangePicker, salaryPieChart);
Pour les utilisations avancées, vous pouvez également lier des commandes à d'autres commandes afin d'établir des chaînes de dépendances .
dashboard.bind(countryPicker, regionPicker).bind(regionPicker, cityPicker);
7. Dessiner votre tableau de bord
Appelez la méthode draw()
sur l'instance de tableau de bord pour afficher l'intégralité du tableau de bord.
La méthode draw()
n'accepte qu'un seul paramètre: DataTable
(ou DataView
) qui alimente le tableau de bord.
Vous devez appeler draw()
chaque fois que vous modifiez la composition du tableau de bord (par exemple, en y ajoutant de nouvelles commandes ou de nouveaux graphiques), ou lorsque vous modifiez le DataTable
global qui l'alimente.
L'instance de tableau de bord déclenche un événement ready
chaque fois que draw()
arrête de dessiner toutes les commandes et tous les graphiques qui en font partie. Un événement error
est déclenché si l'une des commandes gérées ou un graphique ne parvient pas à dessiner. Pour en savoir plus sur la gestion des événements, consultez la section Gérer les événements.
Remarque : Vous devez écouter l'événement ready
avant d'essayer de modifier la composition du tableau de bord ou de le dessiner à nouveau.
8. Modifications programmatiques après le tirage au sort
Une fois que le tableau de bord a terminé le draw()
initial, il est actif et répond automatiquement à toute action que vous effectuez sur celui-ci (par exemple, modifier la plage sélectionnée d'un curseur de contrôle qui fait partie du tableau de bord).
Si vous devez modifier l'état du tableau de bord de manière programmatique, vous pouvez le faire directement sur les instances ControlWrapper
et ChartWrapper
qui en font partie.
La règle d'or consiste à effectuer toute modification dont vous avez besoin directement sur l'instance ControlWrapper
(ou ChartWrapper
) spécifique: par exemple, modifiez une option de contrôle ou un état via setOption()
et setState()
respectivement, puis appelez sa méthode draw()
. Le tableau de bord est ensuite mis à jour pour correspondre aux modifications demandées.
L'exemple suivant illustre ce type de cas.
<html> <head> <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script> <script type="text/javascript"> google.charts.load('current', {'packages':['corechart', 'controls']}); google.charts.setOnLoadCallback(drawStuff); function drawStuff() { var dashboard = new google.visualization.Dashboard( document.getElementById('programmatic_dashboard_div')); // We omit "var" so that programmaticSlider is visible to changeRange. var programmaticSlider = new google.visualization.ControlWrapper({ 'controlType': 'NumberRangeFilter', 'containerId': 'programmatic_control_div', 'options': { 'filterColumnLabel': 'Donuts eaten', 'ui': {'labelStacking': 'vertical'} } }); var programmaticChart = new google.visualization.ChartWrapper({ 'chartType': 'PieChart', 'containerId': 'programmatic_chart_div', 'options': { 'width': 300, 'height': 300, 'legend': 'none', 'chartArea': {'left': 15, 'top': 15, 'right': 0, 'bottom': 0}, 'pieSliceText': 'value' } }); var data = google.visualization.arrayToDataTable([ ['Name', 'Donuts eaten'], ['Michael' , 5], ['Elisa', 7], ['Robert', 3], ['John', 2], ['Jessica', 6], ['Aaron', 1], ['Margareth', 8] ]); dashboard.bind(programmaticSlider, programmaticChart); dashboard.draw(data); changeRange = function() { programmaticSlider.setState({'lowValue': 2, 'highValue': 5}); programmaticSlider.draw(); }; changeOptions = function() { programmaticChart.setOption('is3D', true); programmaticChart.draw(); }; } </script> </head> <body> <div id="programmatic_dashboard_div" style="border: 1px solid #ccc"> <table class="columns"> <tr> <td> <div id="programmatic_control_div" style="padding-left: 2em; min-width: 250px"></div> <div> <button style="margin: 1em 1em 1em 2em" onclick="changeRange();"> Select range [2, 5] </button><br /> <button style="margin: 1em 1em 1em 2em" onclick="changeOptions();"> Make the pie chart 3D </button> </div> </td> <td> <div id="programmatic_chart_div"></div> </td> </tr> </table> </div> </body> </html>
Documentation de référence de l'API
Cette section répertorie les objets exposés par l'API Controls and Dashboards, ainsi que les méthodes standards exposées par toutes les commandes.
Tableau de bord
Représente un ensemble de commandes et de graphiques de collaboration qui partagent les mêmes données sous-jacentes.
Constructeur
Dashboard(containerRef)
- containerRef
- Référence à un élément conteneur valide sur la page qui contiendra le contenu du tableau de bord.
Méthodes
Le tableau de bord expose les méthodes suivantes:
Méthode | Type renvoyé | Description |
---|---|---|
bind(controls, charts) |
google.visualization.tableau de bord |
Liez un ou plusieurs contrôles à un ou plusieurs autres participants au tableau de bord (graphiques ou autres), afin de tous les redessiner chaque fois que l'un d'eux collecte une interaction programmatique ou utilisateur qui affecte les données gérées par le tableau de bord. Renvoie l'instance de tableau de bord elle-même pour enchaîner plusieurs appels
|
draw(dataTable) |
Aucune | Dessine le tableau de bord.
|
getSelection() |
Tableau d'objets |
Affiche un tableau des entités visuelles sélectionnées dans les graphiques du tableau de bord. Lorsqu'elle est appelée sur le tableau de bord, la méthode Remarque:Les écouteurs d'événements pour l'événement sélectionné doivent toujours être associés à chaque graphique que vous souhaitez écouter. |
Événements
L'objet Dashboard génère les événements suivants. Notez que vous devez appeler Dashboard.draw()
avant que des événements ne soient générés.
Nom | Description | Propriétés |
---|---|---|
error |
Déclenché en cas d'erreur lors de l'affichage du tableau de bord Il est possible que l'affichage d'au moins un des contrôles et graphiques du tableau de bord ne fonctionne pas. | identifiant, message |
ready |
Le tableau de bord est terminé et vous pouvez accepter les modifications. L'ensemble des commandes et des graphiques figurant dans le tableau de bord sont prêts pour un appel de méthode externe et une interaction utilisateur. Si vous souhaitez modifier le tableau de bord (ou les données qu'il affiche) après l'avoir tracé, vous devez configurer un écouteur pour cet événement avant d'appeler la méthode L'événement
|
Aucune |
Wrapper de contrôle
Un objet ControlWrapper est un wrapper autour d'une représentation JSON d'une instance de contrôle configurée. La classe présente des méthodes pratiques permettant de définir une commande du tableau de bord, de la dessiner et de modifier automatiquement son état.
Constructeur
ControlWrapper(opt_spec)
- opt_spec.
- [Facultatif] : objet JSON définissant le contrôle ou version de chaîne sérialisée de cet objet. Les propriétés acceptées pour l'objet JSON sont présentées dans le tableau suivant. Si aucune valeur n'est spécifiée, vous devez définir toutes les propriétés appropriées à l'aide des méthodes set... exposées par ControlWrapper.
Propriété | Type | Obligatoire | Par défaut | Description |
---|---|---|---|---|
Type de contrôle | Chaîne | Obligatoire | none |
Nom de classe de la commande. Le nom du package google.visualization peut être omis pour les commandes Google. Exemples:CategoryFilter , NumberRangeFilter .
|
containerId | Chaîne | Obligatoire | none | ID de l'élément DOM de la page qui hébergera la commande. |
options | Objet | Facultative | none |
Objet décrivant les options de la commande. Vous pouvez utiliser une notation littérale JavaScript ou fournir un handle vers l'objet. Exemple :
"options": {"filterColumnLabel": "Age",
"minValue": 10, "maxValue": 80}
|
state | Objet | Facultative | none |
Objet décrivant l'état de la commande. L'état collecte toutes les variables pouvant être affectées par l'utilisateur qui gère la commande. Par exemple, un état du curseur de plage peut être décrit en termes de position occupée par le pouce bas et le pouce élevé du curseur. Vous pouvez utiliser une notation littérale JavaScript ou fournir un handle vers l'objet.Exemple : "state": {"lowValue": 20, "highValue": 50}
|
Méthodes
ControlWrapper expose les méthodes supplémentaires suivantes:
Méthode | Type renvoyé | Description |
---|---|---|
draw() |
Aucune |
Dessine la commande. Normalement, le tableau de bord contenant la commande se charge de la dessiner.
Vous devez appeler |
toJSON() |
Chaîne | Renvoie une version de chaîne de la représentation JSON de la commande. |
clone() |
ControlWrapper | Renvoie une copie complète du wrapper de contrôle. |
getControlType() |
Chaîne |
Nom de classe de la commande. S'il s'agit d'une commande Google, le nom ne pourra pas être google.visualization . Par exemple, s'il s'agissait d'une commande CategoryFilter, elle renverrait "CategoryFilter" au lieu de "google.visualization.CategoryFilter".
|
getControlName() |
Chaîne | Renvoie le nom de la commande attribué par setControlName() . |
getControl() |
Documentation de référence sur les objets de contrôle |
Renvoie une référence à la commande créée par cet objet Wrapper de contrôle. La requête renvoie la valeur "null" jusqu'à ce que vous ayez appelé draw() sur l'objet ControlWrapper (ou sur le tableau de bord contenant l'objet), et elle renvoie un événement prêt. L'objet renvoyé n'expose qu'une seule méthode: resetControl() , qui rétablit l'état de contrôle avec celui avec lequel il a été initialisé (comme la réinitialisation d'un élément de formulaire HTML).
|
getContainerId() |
Chaîne | ID de l'élément de conteneur DOM de la commande. |
getOption(key, opt_default_val) |
Tous les types | Affiche la valeur de l'option de commande spécifiée
|
getOptions() |
Objet | Renvoie l'objet options pour cette commande. |
getState() |
Objet | Renvoie l'état de la commande. |
setControlType(type) |
Aucune |
Définit le type de commande. Transmettez le nom de classe de la commande à instancier. S'il s'agit d'une commande Google, ne l'utilisez pas avec google.visualization .
Par exemple, pour un curseur de plage sur une colonne numérique, transmettez "NumberRangeFilter".
|
setControlName(name) |
Aucune | Définit un nom arbitraire pour la commande. Cette information n'apparaît nulle part sur la commande, mais est fournie à titre indicatif uniquement. |
setContainerId(id) |
Aucune | Définit l'ID de l'élément DOM conteneur pour la commande. |
setOption(key, value) |
Aucune |
Définit une valeur d'option de commande unique, où key est le nom de l'option et value est la valeur. Pour annuler la définition d'une option, transmettez la valeur null. Notez que key peut être un nom complet, tel que 'vAxis.title' .
|
setOptions(options_obj) |
Aucune | Définit un objet d'options complet pour une commande. |
setState(state_obj) |
Aucune | Définit l'état de la commande. L'état collecte toutes les variables pouvant être affectées par l'utilisateur qui gère la commande. Par exemple, un état du curseur de plage peut être décrit en fonction des positions occupées par le curseur bas et haut du curseur. |
Événements
L'objet ControlWrapper génère les événements suivants. Notez que vous devez appeler ControlWrapper.draw()
(ou dessiner le tableau de bord contenant la commande) avant que des événements ne soient générés.
Nom | Description | Propriétés |
---|---|---|
error |
Déclenché en cas d'erreur lors de la tentative d'affichage de la commande. | identifiant, message |
ready |
La commande est prête à accepter l'interaction de l'utilisateur et à appeler des méthodes externes. Si vous souhaitez interagir avec la commande et appeler des méthodes après l'avoir tracée, vous devez configurer un écouteur pour cet événement avant d'appeler la méthode draw et les appeler uniquement après le déclenchement de l'événement. Vous pouvez également écouter un événement ready sur le tableau de bord contenant les méthodes de contrôle et de contrôle des appels uniquement après le déclenchement de l'événement.
|
Aucune |
statechange |
Déclenché lorsque l'utilisateur interagit avec la commande, ce qui affecte son état. Par exemple, un événement statechange se déclenche chaque fois que vous déplacez le curseur d'une commande de curseur de plage. Pour récupérer un état de contrôle mis à jour après le déclenchement de l'événement, appelez ControlWrapper.getState() .
|
Aucune |
ChartWrapper
Reportez-vous à la documentation sur google.visualization.ChartWrapper
dans la section de référence de l'API des visualisations.
Les remarques suivantes s'appliquent lorsque vous utilisez ChartWrapper
dans un tableau de bord:
-
Ne définissez pas explicitement les attributs
dataTable
,query
,dataSourceUrl
etrefreshInterval
. Le tableau de bord contenant le graphique se charge de lui fournir les données dont il a besoin. -
Définissez son attribut
view
pour déclarer quelles colonnes, parmi toutes celles présentes dans ledataTable
fourni au tableau de bord, sont pertinentes pour le graphique, comme indiqué dans Créer des instances de contrôle et de graphique.
Galerie des commandes
Les filtres sont des éléments graphiques que les utilisateurs peuvent utiliser pour sélectionner de manière interactive les données à afficher dans votre graphique. Cette section décrit les filtres des graphiques Google: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter et StringFilter.
Vous pouvez utiliser n'importe lequel d'entre eux comme paramètre pour ControlWrapper.setControlType()
.
Remarque:Dans la description des options, la notation par points est utilisée pour décrire les attributs d'objet imbriqué. Par exemple, une option nommée 'ui.label'
doit être déclarée dans un objet d'options sous la forme var options = {"ui": {"label": "someLabelValue"} };
.
CatégorieFilter
Sélecteur pour choisir une ou plusieurs valeurs parmi un ensemble de valeurs définies.
State
Nom | Type | Par défaut | Description |
---|---|---|---|
Valeurs sélectionnées | Tableau d'objets ou de types primitifs | none |
Ensemble de valeurs actuellement sélectionnées. Les valeurs sélectionnées doivent être un ensemble de valeurs sélectionnables globales définies par l'option values (les valeurs superflues seront ignorées). Si CategoryFilter n'autorise pas les choix multiples, seule la première valeur du tableau est conservée.
|
Options
Nom | Type | Par défaut | Description |
---|---|---|---|
Indice de colonne de filtre | number (nombre) | none |
Colonne du tableau de données sur lequel le filtre doit être exécuté. Vous devez obligatoirement fournir cette option ou filterColumnLabel . Si les deux sont présents, cette option est prioritaire.
|
Libellé de colonne de filtre | chaîne | none |
Libellé de la colonne sur laquelle le filtre doit être appliqué. Vous devez obligatoirement fournir cette option ou filterColumnIndex . Si les deux sont présents, filterColumnIndex est prioritaire.
|
valeurs | Array | auto |
Liste des valeurs disponibles. Si un tableau d'objets est utilisé, ils doivent avoir une représentation toString() adaptée à l'utilisateur. Si la valeur est "null" ou n'est pas définie, la liste des valeurs sera calculée automatiquement à partir des valeurs présentes dans la colonne "DataTable" sur laquelle cette commande est appliquée.
|
useFormattedValue | booléen | false | Lors du remplissage automatique de la liste de valeurs sélectionnables à partir de la colonne DataTable, ce filtre fonctionne, que les valeurs de cellule réelles ou leurs valeurs formatées soient utilisées. |
ui | Objet | nul |
Objet avec des membres permettant de configurer divers aspects de l'interface utilisateur de la commande.
Pour spécifier les propriétés de cet objet, vous pouvez utiliser la notation de littéral d'objet, comme illustré ci-dessous : {label: 'Metric', labelSeparator: ':'} |
sous-titres | chaîne | "Choisissez une valeur..." | Légende à afficher dans le widget de sélection de valeur lorsqu'aucun élément n'est sélectionné. |
ui.sortValues | booléen | true | Indique si les valeurs proposées doivent être triées. |
ui.selectedValuesLayout | chaîne | "de côté" | Découvrez comment afficher les valeurs sélectionnées lorsque la sélection multiple est autorisée. Les valeurs possibles du champ sont les suivantes :
|
ui.allowNone | booléen | true |
Indique si l'utilisateur est autorisé à ne choisir aucune valeur. Si la valeur est false , l'utilisateur doit choisir au moins une valeur parmi les valeurs disponibles. Lors de l'initialisation du contrôle, si l'option est définie sur false et qu'aucun état selectedValues n'est spécifié, la première valeur de ceux disponibles est automatiquement sélectionnée.
|
ui.allowMultiple | booléen | true | Indique si plusieurs valeurs peuvent être sélectionnées, plutôt qu'une seule. |
ui.allowTyping | booléen | true | Indique si l'utilisateur est autorisé à saisir un champ de texte pour affiner la liste des choix possibles (via une saisie semi-automatique) ou non. |
ui.label | chaîne | auto | Libellé à afficher à côté du sélecteur de catégorie. Si ce paramètre n'est pas spécifié, le libellé de la colonne sur laquelle le contrôle est appliqué sera utilisé. |
ui.labelSeparator | chaîne | none | Chaîne de séparateur ajoutée au libellé, pour séparer visuellement ce dernier du sélecteur de catégorie. |
ui.labelStacking | chaîne | 'horizontal' |
Indique si le libellé doit s'afficher au-dessus (empilement vertical) ou à côté (empilement horizontal) du sélecteur de catégorie. Utilisez 'vertical' ou 'horizontal' .
|
Classe ui.css | chaîne | 'google-visualization-controls-categoryfilter' | Classe CSS à attribuer à la commande pour le style personnalisé. |
FiltreRangeRange
Curseur avec deux pouces superposées sur un graphique, pour sélectionner une plage de valeurs dans l'axe continu du graphique.
State
Nom | Type | Par défaut | Description |
---|---|---|---|
plage.début | nombre, date, date/heure ou heure | Valeur de début de la plage | Début de la plage sélectionnée (inclus). |
plage.end | nombre, date, date/heure ou heure | Valeur de fin de la plage | Fin de la plage sélectionnée, inclus. |
Options
Nom | Type | Par défaut | Description |
---|---|---|---|
Indice de colonne de filtre | number (nombre) | none |
Index de la colonne du tableau de données sur lequel le filtre fonctionne.
Vous devez obligatoirement fournir cette option ou filterColumnLabel . Si les deux sont présents, cette option est prioritaire.
Notez qu'il n'est judicieux que de spécifier un index d'une colonne domain qui est incorporé dans l'axe continu du graphique dessiné à l'intérieur de la commande. |
Libellé de colonne de filtre | chaîne | none |
Libellé de la colonne du tableau de données sur lequel le filtre fonctionne. Vous devez obligatoirement fournir cette option ou filterColumnIndex . Si les deux sont présents, filterColumnIndex est prioritaire.
Notez que le choix d'un libellé de colonne de domaine n'est logique que sous l'axe continu du graphique dessiné dans la commande. |
ui | Objet | nul |
Objet avec des membres permettant de configurer divers aspects de l'interface utilisateur de la commande.
Pour spécifier les propriétés de cet objet, vous pouvez utiliser la notation de littéral d'objet, comme illustré ci-dessous : {chartType: 'ScatterChart', chartOptions: {pointSize: 10}} |
ui.chartType | chaîne | ComboChart |
Type de graphique dessiné dans la commande. Peut prendre l'une des valeurs suivantes : "AreaChart", "LineChart", "ComboChart" ou "ScatterChart". |
Options de graphique | Objet |
{ 'enableInteractivity': false, 'chartArea': {'height': '100%'}, 'legend': {'position': 'none'}, 'hAxis': {'textPosition': 'in'}, 'vAxis': { 'textPosition': 'none', 'gridlines': {'color': 'none'} } } |
Options de configuration du graphique dessiné dans la commande.
Permet le même niveau de configuration que n'importe quel graphique du tableau de bord, et respecte le même format que celui accepté par ChartWrapper.setOptions().
Vous pouvez spécifier des options supplémentaires ou remplacer celles par défaut (notez toutefois que les valeurs par défaut ont été soigneusement choisies pour un affichage optimal). |
ui.chartView | Objet ou chaîne (objet sérialisé) | nul |
Spécification de la vue à appliquer au tableau de données utilisé pour dessiner le graphique à l'intérieur de la commande. Permet le même niveau de configuration que n'importe quel graphique du tableau de bord, et respecte le même format que celui accepté par ChartWrapper.setView(). S'il n'est pas spécifié, le tableau de données lui-même est utilisé pour dessiner le graphique.
Notez que l'axe horizontal du graphique dessiné doit être continu. Veillez donc à spécifier |
ui.minRangeSize | number (nombre) | Différence de valeur des données interprétée comme étant de 1 pixel |
Taille minimale de la plage sélectionnable (range.end - range.start ), spécifiée en unités de valeur des données. Pour un axe numérique, il s'agit d'un nombre (pas nécessairement un entier).
Pour un axe de date, de date et d'heure ou d'heure de la journée, il s'agit d'un nombre entier qui indique la différence en millisecondes.
|
ui.snapToData | booléen | false |
Si la valeur est "true", les pouces de la plage sont alignées sur les points de données les plus proches.
Dans ce cas, les points de la plage renvoyés par getState() sont nécessairement des valeurs de la table de données.
|
Événements
Ajouts aux événements ControlWrapper:
Nom | Description | Propriétés |
---|---|---|
statechange |
Comme expliqué pour chaque objet wrapper wrapper, ne possède qu'une propriété booléenne supplémentaire, inProgress , qui indique si l'état est en cours de modification (l'un des pouces ou la plage elle-même est déplacée).
|
en cours |
Filtre de plage de dates
Curseur à deux valeurs pour sélectionner des plages de dates.
Essayez de déplacer le curseur pour modifier les lignes à afficher dans le tableau ci-dessous.
State
Nom | Type | Par défaut | Description |
---|---|---|---|
valeur faible | number (nombre) | none | Étendue inférieure de la plage sélectionnée (incluse). |
Valeur élevée | number (nombre) | none | Étendue supérieure à la plage sélectionnée, inclus. |
minimumPouce minimum | booléen | none |
Indique si le curseur inférieur du curseur est verrouillé sur la plage minimale autorisée. Si ce champ est défini, il remplace lowValue .
|
MiniatureÉlevée | booléen | none |
Indique si le curseur supérieur du curseur est verrouillé sur la plage maximale autorisée. Si ce champ est défini, il remplace highValue .
|
Options
Nom | Type | Par défaut | Description |
---|---|---|---|
Indice de colonne de filtre | number (nombre) | none |
Colonne du tableau de données sur lequel le filtre doit être exécuté. Vous devez obligatoirement fournir cette option ou filterColumnLabel . Si les deux sont présents, cette option est prioritaire.
Doit pointer vers une colonne de type number .
|
Libellé de colonne de filtre | chaîne | none |
Libellé de la colonne sur laquelle le filtre doit être appliqué. Vous devez obligatoirement fournir cette option ou filterColumnIndex . Si les deux sont présents, filterColumnIndex est prioritaire. Elle doit pointer vers une colonne de type number .
|
minValue | Date | auto | Valeur minimale autorisée pour la plage inférieure. Si elle n'est pas définie, la valeur sera déduite du contenu de la table de données gérée par la commande. |
maxValue | Date | auto | Valeur maximale autorisée pour la plage supérieure. Si elle n'est pas définie, la valeur sera déduite du contenu de la table de données gérée par la commande. |
ui | Objet | nul |
Objet avec des membres permettant de configurer divers aspects de l'interface utilisateur de la commande.
Pour spécifier les propriétés de cet objet, vous pouvez utiliser la notation de littéral d'objet, comme illustré ci-dessous : {label: 'Age', labelSeparator: ':'} |
format.ui | Objet | none | Comment représenter la date sous forme de chaîne ? Accepte tout format de date valide. |
ui.step | chaîne | jour | Changement minimal possible lorsque l'utilisateur déplace le curseur "pouce" : il peut s'agir de n'importe quelle unité de temps jusqu'à "jour". ("month" et "year" ne sont pas encore acceptés). |
ui.ticks | number (nombre) | auto | Nombre de graduations (positions fixes dans la barre de plage) que les curseurs du curseur peuvent occuper. |
ui.unitIncrement | chaîne | "1" | Montant à incrémenter pour les incréments d'unités des étendues. Un incrément d'unité équivaut à utiliser les touches fléchées pour déplacer un curseur. |
ui.blockIncrement | number (nombre) | 10 | Montant à incrémenter pour les incréments de bloc des étendues de plage. Un incrément de volume revient à utiliser les touches pg Haut et pg Bas pour déplacer le curseur. |
ui.showRangeValues | booléen | true | Indique si des libellés doivent s'afficher à côté du curseur pour afficher les étendues de la plage sélectionnée. |
ui.orientation | chaîne | 'horizontal' | Orientation du curseur. 'horizontal' ou 'vertical' . |
ui.label | chaîne | auto | Libellé à afficher à côté du curseur. Si ce paramètre n'est pas spécifié, l'étiquette de la colonne sur laquelle le contrôle est appliqué sera utilisé. |
ui.labelSeparator | chaîne | none | Chaîne de séparateur ajoutée au libellé, pour séparer visuellement ce dernier du curseur. |
ui.labelStacking | chaîne | 'horizontal' |
Indique si le libellé doit s'afficher au-dessus (empilement vertical) ou à côté (empilement horizontal) du curseur. Utilisez 'vertical' ou 'horizontal' .
|
Classe ui.css | chaîne | 'google-visualization-controls-rangefilter' | Classe CSS à attribuer à la commande pour le style personnalisé. |
FiltrePlageNombre
Curseur à deux valeurs pour la sélection de plages de valeurs numériques.
State
Nom | Type | Par défaut | Description |
---|---|---|---|
valeur faible | number (nombre) | none | Étendue inférieure de la plage sélectionnée (incluse). |
Valeur élevée | number (nombre) | none | Étendue supérieure à la plage sélectionnée, inclus. |
minimumPouce minimum | booléen | none |
Indique si le curseur inférieur du curseur est verrouillé sur la plage minimale autorisée. Si ce champ est défini, il remplace lowValue .
|
MiniatureÉlevée | booléen | none |
Indique si le curseur supérieur du curseur est verrouillé sur la plage maximale autorisée. Si ce champ est défini, il remplace highValue .
|
Options
Nom | Type | Par défaut | Description |
---|---|---|---|
Indice de colonne de filtre | number (nombre) | none |
Colonne du tableau de données sur lequel le filtre doit être exécuté. Vous devez obligatoirement fournir cette option ou filterColumnLabel . Si les deux sont présents, cette option est prioritaire.
Doit pointer vers une colonne de type number .
|
Libellé de colonne de filtre | chaîne | none |
Libellé de la colonne sur laquelle le filtre doit être appliqué. Vous devez obligatoirement fournir cette option ou filterColumnIndex . Si les deux sont présents, filterColumnIndex est prioritaire. Elle doit pointer vers une colonne de type number .
|
minValue | number (nombre) | auto | Valeur minimale autorisée pour la plage inférieure. Si elle n'est pas définie, la valeur sera déduite du contenu de la table de données gérée par la commande. |
maxValue | number (nombre) | auto | Valeur maximale autorisée pour la plage supérieure. Si elle n'est pas définie, la valeur sera déduite du contenu de la table de données gérée par la commande. |
ui | Objet | nul |
Objet avec des membres permettant de configurer divers aspects de l'interface utilisateur de la commande.
Pour spécifier les propriétés de cet objet, vous pouvez utiliser la notation de littéral d'objet, comme illustré ci-dessous : {label: 'Age', labelSeparator: ':'} |
format.ui | Objet | none | Représentation du nombre par une chaîne. Accepte tous les formats numériques valides. |
ui.step | number (nombre) | 1, ou calculé à partir de ticks si défini |
Changement minimal possible lorsque vous faites glisser le curseur vers le bas. |
ui.ticks | number (nombre) | auto | Nombre de graduations (positions fixes dans la barre de plage) que les curseurs du curseur peuvent occuper. |
ui.unitIncrement | number (nombre) | 1 | Montant à incrémenter pour les incréments d'unités des étendues. Un incrément d'unité équivaut à utiliser les touches fléchées pour déplacer un curseur. |
ui.blockIncrement | number (nombre) | 10 | Montant à incrémenter pour les incréments de bloc des étendues de plage. Un incrément de volume revient à utiliser les touches pg Haut et pg Bas pour déplacer le curseur. |
ui.showRangeValues | booléen | true | Indique si des libellés doivent s'afficher à côté du curseur pour afficher les étendues de la plage sélectionnée. |
ui.orientation | chaîne | 'horizontal' | Orientation du curseur. 'horizontal' ou 'vertical' . |
ui.label | chaîne | auto | Libellé à afficher à côté du curseur. Si ce paramètre n'est pas spécifié, l'étiquette de la colonne sur laquelle le contrôle est appliqué sera utilisé. |
ui.labelSeparator | chaîne | none | Chaîne de séparateur ajoutée au libellé, pour séparer visuellement ce dernier du curseur. |
ui.labelStacking | chaîne | 'horizontal' |
Indique si le libellé doit s'afficher au-dessus (empilement vertical) ou à côté (empilement horizontal) du curseur. Utilisez 'vertical' ou 'horizontal' .
|
Classe ui.css | chaîne | 'google-visualization-controls-rangefilter' | Classe CSS à attribuer à la commande pour le style personnalisé. |
Chaîne de filtrage
Champ de saisie de texte simple qui vous permet de filtrer les données via la mise en correspondance de chaînes. Elle est mise à jour après chaque touche: essayez de saisir j
pour limiter la table ci-dessous à John et Jessica.
State
Nom | Type | Par défaut | Description |
---|---|---|---|
valeur | chaîne ou objet | none | Texte saisi dans le champ de saisie de commande. |
Options
Nom | Type | Par défaut | Description |
---|---|---|---|
Indice de colonne de filtre | number (nombre) | none |
Colonne du tableau de données sur lequel le filtre doit être exécuté. Vous devez obligatoirement fournir cette option ou filterColumnLabel . Si les deux sont présents, cette option est prioritaire.
|
Libellé de colonne de filtre | chaîne | none |
Libellé de la colonne sur laquelle le filtre doit être appliqué. Vous devez obligatoirement fournir cette option ou filterColumnIndex . Si les deux sont présents, filterColumnIndex est prioritaire.
|
Type de correspondance | chaîne | 'préfixe' |
Indique si la commande doit correspondre uniquement aux valeurs exactes ('exact' ), aux préfixes à partir du début de la valeur ('prefix' ) ou à une sous-chaîne ('any' ).
|
sensible à la casse | booléen | false | Indique si la correspondance doit être sensible à la casse ou non. |
useFormattedValue | booléen | false | Indique si la commande doit correspondre à des valeurs au format de la cellule ou à des valeurs réelles. |
ui | Objet | nul |
Objet avec des membres permettant de configurer divers aspects de l'interface utilisateur de la commande.
Pour spécifier les propriétés de cet objet, vous pouvez utiliser la notation de littéral d'objet, comme illustré ci-dessous : {label: 'Name', labelSeparator: ':'} |
ui.realtimeTrigger | booléen | true | Indique si la commande doit correspondre lorsqu'un utilisateur appuie sur une touche ou uniquement lorsque le champ de saisie est "modifié" (mise au point ou appui sur la touche Entrée). |
ui.label | chaîne | auto | Libellé à afficher à côté du champ de saisie. Si ce paramètre n'est pas spécifié, le libellé de la colonne sur laquelle le contrôle est appliqué sera utilisé. |
ui.labelSeparator | chaîne | none | Chaîne de séparateur ajoutée au libellé, pour séparer visuellement ce dernier du champ de saisie. |
ui.labelStacking | chaîne | 'horizontal' |
Indique si le libellé doit s'afficher au-dessus (empilage vertical) ou à côté (empilement horizontal) du champ de saisie. Utilisez 'vertical' ou 'horizontal' .
|
Classe ui.css | chaîne | 'google-visualization-controls-stringfilter' | Classe CSS à attribuer à la commande pour le style personnalisé. |