Commandes et tableaux de bord

Sur cette page, vous verrez comment combiner plusieurs graphiques dans des tableaux de bord et permettre aux utilisateurs de contrôler les données qu'ils affichent.

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.

  1. 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.
  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.
  3. 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.
  4. 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.
  5. Créez autant d'instances de commande et de graphique que nécessaire. Créez des instances google.visualization.ChartWrapper et google.visualization.ControlWrapper pour décrire chaque graphique et commande contrôlé par le tableau de bord.
  6. É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.
  7. 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.
  8. 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 (ou filterColumnLabel) à toutes les commandes pour spécifier la colonne de google.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 instance ChartWrapper 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.

Page Web complète
<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 bind().

  • controls : une seule ou un tableau d'instances google.visualization.ControlWrapper définissant les contrôles à lier.
  • graphiques : une ou une série d'instances google.visualization.ChartWrapper définissant les graphiques qui seront pilotés par les commandes.
draw(dataTable) Aucune

Dessine le tableau de bord.

  • dataTable : l'un des éléments suivants : un objet DataTable ; un objet DataView ; une représentation JSON d'un objet DataTable ; ou un tableau suivant la syntaxe de google.visualization.arrayToDataTable().
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 getSelection() renvoie un agrégat de toutes les sélections effectuées sur tous les graphiques qu'il contient, ce qui permet d'utiliser une référence unique lorsque vous travaillez avec des sélections de graphiques.

Remarque:Les écouteurs d'événements pour l'événement sélectionné doivent toujours être associés à chaque graphique que vous souhaitez écouter.

Description étendue

É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 draw, puis appliquer vos modifications uniquement après le déclenchement de l'événement.

L'événement ready se déclenchera également:

  • à la fin de l'actualisation du tableau de bord déclenchée par une interaction utilisateur ou programmatique avec l'une des commandes ;
  • après un appel programmatique à la méthode draw() de n'importe quelle partie de graphique du tableau de bord.
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 draw() pour forcer la rediffusion programmatique du contrôle après avoir modifié ses autres paramètres, tels que les options ou l'état.

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

  • key : nom de l'option à récupérer. Il peut s'agir d'un nom complet, tel que 'vAxis.title'.
  • opt_default_value [facultatif] : si la valeur spécifiée n'est pas définie ou est nulle, cette valeur est renvoyé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 et refreshInterval. 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 le dataTable fourni au tableau de bord, sont pertinentes pour le graphique, comme indiqué dans Créer des instances de contrôle et de graphique.

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 :
  • 'aside' : les valeurs sélectionnées s'affichent sur une seule ligne de texte à côté du widget de sélection des valeurs.
  • 'below' : les valeurs sélectionnées s'affichent sur une seule ligne de texte sous le widget.
  • 'belowWrapping' est semblable à below, mais les entrées ne pouvant pas figurer dans le sélecteur encapsuleront sur une nouvelle ligne,
  • 'belowStacked' : les valeurs sélectionnées seront affichées dans une colonne sous le widget.
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.chartView en conséquence.

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é.