Commandes et tableaux de bord

Sur cette page, vous découvrirez 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. En utilisant les API décrites sur cette page, vous n'avez plus besoin de raccorder les deux outils et de coordonner tous les 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 à visualiser, ainsi qu'à dessiner et à distribuer les données à tous les graphiques 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 fonctionnalités de saisie semi-automatique, etc.) avec lesquels vous interagissez pour gé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 conduites et des vannes de plomberie. Ils collectent les entrées utilisateur et utilisent ces informations pour décider quelles données gérées par le tableau de bord doivent être mises à la disposition des graphiques qui en font partie.

Examinez l'exemple suivant, dans lequel un sélecteur de catégorie et un curseur de plage sont utilisés pour générer les données visualisées par un graphique à secteurs.

Remarque:Le tableau de bord est interactif. Utilisez les commandes pour observer 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 chacune de ces étapes, suivies d'informations détaillées sur chacune d'elles.

  1. Créez un squelette HTML pour votre tableau de bord. Votre page doit comporter autant d'éléments HTML que nécessaire pour contenir chaque membre d'un tableau de bord. Cela inclut le tableau de bord lui-même ainsi que toutes les commandes et tous les graphiques qui en font partie. En règle générale, vous devez utiliser un tag <div> pour chaque balise.
  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 devez préparer les données à visualiser. Autrement dit, vous devez spécifier les données vous-même 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 commandes et de graphiques que nécessaire. Créez des instances google.visualization.ChartWrapper et google.visualization.ControlWrapper pour décrire chaque graphique et chaque commande gérés par le tableau de bord.
  6. Établissez les dépendances. Appelez bind() sur votre tableau de bord, et transmettez les instances de commande et de graphique pour que le tableau de bord sache ce qu'il doit gérer. Une fois qu'une commande et un graphique sont liés, le tableau de bord met à jour le graphique pour qu'il corresponde aux contraintes que la commande applique aux 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 le dessin. Une fois le dessin initial terminé, vous pouvez également programmer les commandes qui font partie du tableau de bord et lui demander de mettre à jour les graphiques en conséquence.

Voici un exemple simple de page créant un tableau de bord simple avec un curseur de plage qui pilote un graphique à secteurs. Le tableau de bord obtenu est affiché sous l'extrait de code. 

<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>) pour contenir à la fois le tableau de bord lui-même et toutes les commandes et tous les graphiques qu'il contient. Lorsque vous instanciez des instances de tableau de bord, de commande et de graphique, vous devez transmettre une référence à leur élément. Vous devez donc attribuer 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 vous le souhaitez pour votre tableau de bord.

2. Charger 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 jauge) et les charge à la volée, sans aucune autre intervention de votre part.

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 donc que toutes les classes et méthodes d'assistance requises sont prêtes pour que vous puissiez commencer à préparer vos données.

Les tableaux de bord acceptent les données d'un tableau de données, tout comme les graphiques.

4. Créer une instance de tableau de bord

Après avoir créé vos données, vous pouvez instancier l'objet de tableau de bord. Un constructeur de tableau de bord utilise un seul 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 présentés sous la forme d'une 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 lorsque 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. Pour en savoir plus, consultez les sections Gérer les événements de visualisation ou Afficher correctement les erreurs dans la section dédiée aux graphiques.

5. Créer des instances de graphique et de commande

Définissez le nombre d'instances dont vous avez besoin pour chaque commande et chaque graphique qui figureront dans le 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 eux 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.

Quelques conseils sur la configuration des commandes et des graphiques:

  • Vous devez attribuer à toutes les commandes un filterColumnIndex (ou filterColumnLabel) pour spécifier la colonne de la google.visualization.DataTable sur laquelle elles s'appliquent (dans l'exemple ci-dessus, le contrôle agit sur la colonne intitulée Donuts mangé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. Par exemple, utilisez ce paramètre pour fixer les positions initiales des curseurs d'une commande de 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 la même table de données sous-jacente que vous avez préparée à l'étape Préparer vos données. Toutefois, les graphiques nécessitent souvent une disposition 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é le tableau de bord ainsi que toutes les commandes et tous les graphiques qui en feront partie, utilisez la méthode bind() pour indiquer au tableau de bord les dépendances qui existent entre les commandes et les graphiques.

Une fois qu'une commande et un graphique sont liés, le tableau de bord met à jour le graphique pour qu'il corresponde aux contraintes que la commande applique aux données. Dans l'exemple de tableau de bord que vous créez, le curseur de plage et le graphique à secteurs sont liés. Par conséquent, chaque fois que vous interagissez avec le premier, le second se met à 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 des commandes et des graphiques dans de nombreuses configurations différentes: un à un, un à plusieurs, plusieurs à un et plusieurs à plusieurs. Chaque fois que plusieurs commandes sont liées à un graphique, le tableau de bord met à jour le graphique pour qu'il corresponde aux contraintes combinées appliquées par toutes les commandes liées. Une commande peut générer simultanément plusieurs graphiques. Pour spécifier plusieurs liaisons en même temps, transmettez des tableaux à la méthode bind() au lieu d'instances uniques. Vous pouvez également enchaîner 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 contrôles à d'autres contrôles pour é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 du tableau de bord pour afficher l'intégralité du tableau de bord. La méthode draw() n'accepte qu'un seul paramètre: le 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 des commandes ou des graphiques), ou lorsque vous modifiez le DataTable global qui l'utilise.

L'instance de tableau de bord déclenche un événement ready chaque fois que draw() met fin au dessin de toutes les commandes et tous les graphiques qui en font partie. Un événement error est déclenché si l'un des graphiques ou des commandes gérés ne s'affiche pas. Pour en savoir plus sur la gestion des événements, consultez la page Gérer les événements.

Remarque:Écoutez 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 tirage

Une fois que le tableau de bord aura terminé la draw() initiale, il sera en ligne et répondra automatiquement à toute action que vous y effectuerez (comme la modification de la plage sélectionnée d'un curseur de commande faisant partie du tableau de bord).

Si vous devez modifier l'état du tableau de bord par programmation, vous pouvez le faire en opérant directement sur les instances ControlWrapper et ChartWrapper qui en font partie. En règle générale, il convient d'effectuer toutes les modifications dont vous avez besoin directement sur l'instance ControlWrapper (ou ChartWrapper) spécifique. Par exemple, modifiez une option de commande ou un état via setOption() et setState() respectivement, puis appelez sa méthode draw() par la suite. Le tableau de bord sera ensuite mis à jour pour refléter les modifications demandées.

L'exemple suivant illustre ce cas de figure.
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 Tableaux de bord, ainsi que les méthodes standards exposées par tous les contrôles.

Tableau de bord

Représente un ensemble de commandes et de graphiques collaboratifs qui partagent les mêmes données sous-jacentes.

Constructeur

Dashboard(containerRef)
containerRef
Référence à un élément de 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.Dashboard

Lie une ou plusieurs commandes à un ou plusieurs autres participants du tableau de bord (graphiques ou autres). Ces dernières sont ainsi toutes redessinées chaque fois que l'une des premières 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 permettant de chaîner plusieurs appels bind().

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

Permet de dessiner le tableau de bord.
getSelection() Tableau d'objets

Renvoie un tableau des entités visuelles sélectionnées des graphiques dans le 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 vous permet d'utiliser une seule référence lorsque vous sélectionnez des graphiques.

Remarque:Les écouteurs d'événements de l'événement de sélection 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 qu'un événement ne soit généré.

Nom Description Propriétés
error Déclenché lorsqu'une erreur se produit lors de la tentative d'affichage du tableau de bord. Un ou plusieurs graphiques et commandes du tableau de bord ont peut-être échoué à s'afficher. ID, message
ready

Le dessin du tableau de bord est terminé et il est prêt à accepter des modifications. Toutes les commandes et tous les graphiques du tableau de bord sont prêts pour l'appel de méthode externe et les interactions de l'utilisateur. Si vous souhaitez modifier le tableau de bord (ou les données qu'il affiche) après l'avoir dessiné, 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:

  • après l'actualisation du tableau de bord déclenchée par un utilisateur ou une interaction programmatique avec l'une des commandes,
  • après un appel programmatique à la méthode draw() de n'importe quelle partie du graphique du tableau de bord.
Aucun

ControlWrapper

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 de tableau de bord, de la dessiner et de modifier son état par programmation.

Constructeur

ControlWrapper(opt_spec)
opt_spec
[Facultatif] : objet JSON définissant la commande, ou version de chaîne sérialisée de cet objet. Les propriétés acceptées de 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
controlType Chaîne Obligatoire none Nom de classe de la commande. Le nom de 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 votre page qui hébergera la commande.
options Objets Facultatif none Objet décrivant les options de la commande. Vous pouvez utiliser la notation littérale JavaScript ou fournir un handle vers l'objet. Exemple: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state Objets Facultatif none Objet décrivant l'état de la commande. L'état collecte toutes les variables que l'utilisateur qui exploite la commande de contrôle peut affecter. Par exemple, l'état d'un curseur de plage peut être décrit en fonction des positions occupées par le curseur bas et haut du curseur. Vous pouvez utiliser la 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() Aucun

Permet de dessiner la commande. Normalement, le tableau de bord contenant la commande se charge de le dessiner. Vous devez appeler draw() pour forcer le redessin programmatique de la commande après avoir modifié l'un de ses autres paramètres, comme les options ou l'état.

toJSON() Chaîne Renvoie une version sous forme 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'un contrôle Google, le nom ne sera pas qualifié avec google.visualization. Par exemple, s'il s'agissait d'une commande "CategoryFilter", elle renverrait "CategoryFilter" plutôt que "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 ce ControlWrapper. La valeur "null" est renvoyée jusqu'à ce que vous ayez appelé draw() sur l'objet ControlWrapper (ou sur le tableau de bord contenant celui-ci), et génère un événement "ready". L'objet renvoyé n'expose qu'une seule méthode: resetControl(), qui rétablit l'état du contrôle sur 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

Renvoie 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, elle est renvoyée.
getOptions() Objets Renvoie l'objet "options" pour cette commande.
getState() Objets Renvoie l'état de la commande.
setControlType(type) Aucun Définit le type de commande. Transmettez le nom de classe de la commande à instancier. S'il s'agit d'un contrôle Google, ne le qualifiez pas avec google.visualization. Ainsi, pour un curseur de plage sur une colonne numérique, transmettez "NumberRangeFilter".
setControlName(name) Aucun Définit un nom arbitraire pour la commande. Cette information n'apparaît nulle part sur la commande, mais elle est fournie à titre indicatif uniquement.
setContainerId(id) Aucun Définit l'ID de l'élément DOM conteneur pour la commande.
setOption(key, value) Aucun Définit une valeur d'option de contrôle unique, où key est le nom de l'option et value la valeur. Pour désactiver une option, transmettez la valeur null. Notez que key peut être un nom complet, tel que 'vAxis.title'.
setOptions(options_obj) Aucun Définit un objet "options" complet pour une commande.
setState(state_obj) Aucun Définit l'état du contrôle. L'état collecte toutes les variables que l'utilisateur qui exploite la commande de contrôle peut affecter. Par exemple, l'état d'un 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é lorsqu'une erreur se produit lors de la tentative d'affichage de la commande. ID, message
ready La commande est prête à accepter les interactions de l'utilisateur et pour les appels de méthode externes. Si vous souhaitez interagir avec la commande et appeler des méthodes après l'avoir dessinée, vous devez configurer un écouteur pour cet événement avant d'appeler la méthode draw, puis ne les appeler qu'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 commande et de contrôle d'appel uniquement après le déclenchement de l'événement. Aucun
statechange Déclenché lorsque l'utilisateur interagit avec la commande, ce qui a une incidence sur son état. Par exemple, un événement statechange se déclenche chaque fois que vous déplacez les pouces 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(). Aucun

ChartWrapper

Reportez-vous à la documentation de google.visualization.ChartWrapper dans la section de référence de l'API des visualisations.

Les remarques suivantes s'appliquent lorsque vous utilisez un ChartWrapper dans un tableau de bord:

  • Ne définissez pas les attributs dataTable, query, dataSourceUrl et refreshInterval de manière explicite. Le tableau de bord contenant le graphique s'occupe de lui fournir les données dont il a besoin.
  • Définissez son attribut view pour déclarer les colonnes pertinentes pour le graphique, parmi toutes celles présentes dans la dataTable fournie au tableau de bord, comme indiqué dans la section Créer des instances de commande 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 de graphique 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 permet de décrire les attributs d'objets imbriqués. Par exemple, une option nommée 'ui.label' doit être déclarée dans un objet options en tant que var options = {"ui": {"label": "someLabelValue"} };.

CategoryFilter

Un sélecteur pour choisir une ou plusieurs valeurs parmi un ensemble de valeurs définies.

État

Nom Type Par défaut Description
selectedValues Tableau d'objets ou de types primitifs none Ensemble de valeurs actuellement sélectionné. Les valeurs sélectionnées doivent être un ensemble de valeurs globales sélectionnables définis par l'option values (toutes 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
filterColumnIndex Nombre none Colonne du tableau de données sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnLabel. Si ces deux options sont présentes, cette option prévaut.
filterColumnLabel chaîne none Étiquette de la colonne sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnIndex. Si les deux sont présents, filterColumnIndex est prioritaire.
valeurs Tableau auto Liste de valeurs disponibles. Si un tableau d'objets est utilisé, ils doivent disposer d'une représentation toString() appropriée pour être présentée à l'utilisateur. Si la valeur est nulle ou non définie, la liste des valeurs sera automatiquement calculée à partir des valeurs présentes dans la colonne DataTable sur laquelle cette commande agit.
useFormattedValue boolean false Lorsque ce filtre remplit automatiquement la liste des valeurs sélectionnables à partir de la colonne DataTable, ce filtre s'applique selon qu'il doit utiliser les valeurs réelles des cellules ou leurs valeurs formatées.
ui Objets 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 littérale d'objet, comme indiqué ci-dessous : 
{label: 'Metric', labelSeparator: ':'}
ui.caption chaîne "Sélectionner une valeur..." Légende à afficher dans le widget de sélection de valeur lorsqu'aucun élément n'est sélectionné.
ui.sortValues boolean true Indique si les valeurs à choisir doivent être triées.
ui.selectedValuesLayout chaîne "à part" 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 de valeur.
  • 'below': les valeurs sélectionnées s'affichent sur une seule ligne de texte sous le widget.
  • 'belowWrapping': semblable à below, mais les entrées qui ne peuvent pas tenir dans le sélecteur sont renvoyées à la ligne.
  • 'belowStacked': les valeurs sélectionnées s'affichent dans une colonne sous le widget.
ui.allowNone boolean true Indique si l'utilisateur n'est pas autorisé à choisir une valeur. Si la valeur est false, l'utilisateur doit choisir au moins une valeur parmi celles disponibles. Lors de l'initialisation du contrôle, si l'option est définie sur false et qu'aucun état selectedValues n'est indiqué, la première valeur parmi les valeurs disponibles est automatiquement sélectionnée.
ui.allowMultiple boolean true Indique si plusieurs valeurs peuvent être sélectionnées plutôt qu'une seule.
ui.allowTyping boolean true Indique si l'utilisateur est autorisé ou non à saisir du texte dans un champ de texte pour affiner la liste des choix possibles (via une saisie semi-automatique).
ui.label chaîne auto Libellé à afficher à côté de l'outil de sélection des catégories. Si aucune valeur n'est spécifiée, l'étiquette de la colonne sur laquelle agit la commande sera utilisée.
ui.labelSeparator chaîne none Chaîne séparatrice ajoutée au libellé, pour séparer visuellement le libellé de l'outil de sélection de catégories.
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'.
ui.cssClass chaîne 'google-visualization-controls-categoryfilter' Classe CSS à attribuer à la commande pour obtenir un style personnalisé

ChartRangeFilter

Un curseur avec deux pouces superposés sur un graphique, permettant de sélectionner une plage de valeurs à partir de l'axe continu du graphique.

État

Nom Type Par défaut Description
range.start number, date, datetime ou timeofday (nombre, date, date et heure ou heure de la journée) Valeur de début de la plage Début de la plage sélectionnée, inclus.
range.end number, date, datetime ou timeofday (nombre, date, date et heure ou heure de la journée) Valeur de fin de la plage Fin de la plage sélectionnée, incluse.

Options

Nom Type Par défaut Description
filterColumnIndex Nombre none Index de la colonne de la table de données sur laquelle le filtre agit. Vous devez obligatoirement fournir cette option ou filterColumnLabel. Si les deux sont présents, cette option est prioritaire.

Notez qu'il n'est judicieux de spécifier que l'index d'une colonne domain incarnée dans l'axe continu du graphique dessiné dans la commande.

filterColumnLabel chaîne none Libellé de la colonne de la table de données sur laquelle le filtre s'applique. Vous devez obligatoirement fournir cette option ou filterColumnIndex. Si les deux sont présents, filterColumnIndex est prioritaire.

Notez qu'il n'est judicieux de spécifier que l'étiquette d'une colonne domain incarnée dans l'axe continu du graphique dessiné dans la commande.

ui Objets 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 littérale d'objet, comme indiqué ci-dessous : 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType chaîne ComboChart Type du graphique affiché dans la commande.
Les valeurs possibles sont "Graphique en aires", "Graphique en courbes", "Graphique combiné" ou "Graphique à nuage de points".
ui.chartOptions Objets 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
Options de configuration du graphique affiché 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é choisies avec soin pour une apparence optimale).

ui.chartView Objet ou chaîne (objet sérialisé) nul Spécification de la vue à appliquer à la table de données utilisée pour dessiner le graphique 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.setView(). Si aucune valeur n'est spécifiée, la table de données elle-même est utilisée 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 Nombre Différence de valeur de données interprétée comme 1 pixel Taille minimale de la plage sélectionnable (range.end - range.start), spécifiée en unités de valeur de données. Pour un axe numérique, il s'agit d'un nombre (pas nécessairement un entier). Pour un axe de date, date/heure ou heure de la journée, il s'agit d'un entier qui spécifie la différence en millisecondes.
ui.snapToData boolean false Si la valeur est "true", les pouces de la plage sont ancrés aux points de données les plus proches. Dans ce cas, les points de terminaison de la plage renvoyée par getState() sont nécessairement des valeurs dans la table de données.

Événements

Ajouts aux événements ControlWrapper:

Nom Description Propriétés
statechange Comme indiqué pour chaque ControlWrapper, elle ne comporte qu'une propriété booléenne supplémentaire, inProgress, qui spécifie si l'état est en cours de modification (l'un des curseurs ou la plage elle-même est en train d'être déplacée). inProgress

DateRangeFilter

Curseur à deux valeurs permettant de sélectionner des plages de dates.

Essayez de déplacer le curseur pour modifier les lignes affichées dans le tableau ci-dessous.

État

Nom Type Par défaut Description
lowValue Nombre none Partie inférieure de la plage sélectionnée (incluse).
highValue Nombre none Partie la plus élevée de la plage sélectionnée (incluse).
lowThumbAtMinimum boolean none Indique si le curseur inférieur est verrouillé sur la plage minimale autorisée. Si cette valeur est définie, elle remplace lowValue.
highThumbAtMaximum boolean none Indique si le curseur le plus haut est verrouillé sur la plage maximale autorisée. Si cette valeur est définie, elle remplace highValue.

Options

Nom Type Par défaut Description
filterColumnIndex Nombre none Colonne du tableau de données sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnLabel. Si ces deux options sont présentes, cette option prévaut. Doit pointer vers une colonne de type number.
filterColumnLabel chaîne none Étiquette de la colonne sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnIndex. Si les deux sont présents, filterColumnIndex est prioritaire. Doit pointer vers une colonne de type number.
minValue Date auto Valeur minimale autorisée pour l'étendue inférieure de la plage. 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 l'étendue supérieure de la plage. 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 Objets 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 littérale d'objet, comme indiqué ci-dessous : 
{label: 'Age', labelSeparator: ':'}
ui.format Objets none Comment représenter la date sous forme de chaîne. Accepte tout format de date valide.
ui.step chaîne jour La variation minimale possible lorsque vous faites glisser les curseurs: n'importe quelle unité de temps jusqu'à "jour". ("mois" et "année" ne sont pas encore acceptés).
ui.ticks Nombre auto Nombre de graduations (positions fixes dans la barre de plage) que les curseurs peuvent occuper.
ui.unitIncrement chaîne "1" Montant à incrémenter pour les incréments unitaires des étendues de la plage. Un incrément d'unité équivaut à utiliser les touches fléchées pour déplacer un curseur.
ui.blockIncrement Nombre 10 Montant à incrémenter pour les incréments de bloc de l'étendue de la plage. Un incrément de bloc équivaut à utiliser les touches pgPréc et pgSuiv pour déplacer les curseurs.
ui.showRangeValues boolean true Permet d'afficher ou non des libellés à côté du curseur affichant l'étendue 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 aucune valeur n'est spécifiée, l'étiquette de la colonne sur laquelle agit la commande sera utilisée.
ui.labelSeparator chaîne none Chaîne séparatrice ajoutée au libellé, pour séparer visuellement le libellé 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'.
ui.cssClass chaîne 'google-visualization-controls-rangefilter' Classe CSS à attribuer à la commande pour obtenir un style personnalisé

NumberRangeFilter

Curseur à double valeur permettant de sélectionner des plages de valeurs numériques.

État

Nom Type Par défaut Description
lowValue Nombre none Partie inférieure de la plage sélectionnée (incluse).
highValue Nombre none Partie la plus élevée de la plage sélectionnée (incluse).
lowThumbAtMinimum boolean none Indique si le curseur inférieur est verrouillé sur la plage minimale autorisée. Si cette valeur est définie, elle remplace lowValue.
highThumbAtMaximum boolean none Indique si le curseur le plus haut est verrouillé sur la plage maximale autorisée. Si cette valeur est définie, elle remplace highValue.

Options

Nom Type Par défaut Description
filterColumnIndex Nombre none Colonne du tableau de données sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnLabel. Si ces deux options sont présentes, cette option prévaut. Doit pointer vers une colonne de type number.
filterColumnLabel chaîne none Étiquette de la colonne sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnIndex. Si les deux sont présents, filterColumnIndex est prioritaire. Doit pointer vers une colonne de type number.
minValue Nombre auto Valeur minimale autorisée pour l'étendue inférieure de la plage. 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 Nombre auto Valeur maximale autorisée pour l'étendue supérieure de la plage. 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 Objets 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 littérale d'objet, comme indiqué ci-dessous : 
{label: 'Age', labelSeparator: ':'}
ui.format Objets none Comment représenter le nombre sous forme de chaîne. Accepte tout format numérique valide.
ui.step Nombre 1, ou calculé à partir de ticks si défini Variation minimale possible lorsque vous faites glisser les curseurs.
ui.ticks Nombre auto Nombre de graduations (positions fixes dans la barre de plage) que les curseurs peuvent occuper.
ui.unitIncrement Nombre 1 Montant à incrémenter pour les incréments unitaires des étendues de la plage. Un incrément d'unité équivaut à utiliser les touches fléchées pour déplacer un curseur.
ui.blockIncrement Nombre 10 Montant à incrémenter pour les incréments de bloc de l'étendue de la plage. Un incrément de bloc équivaut à utiliser les touches pgPréc et pgSuiv pour déplacer les curseurs.
ui.showRangeValues boolean true Permet d'afficher ou non des libellés à côté du curseur affichant l'étendue 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 aucune valeur n'est spécifiée, l'étiquette de la colonne sur laquelle agit la commande sera utilisée.
ui.labelSeparator chaîne none Chaîne séparatrice ajoutée au libellé, pour séparer visuellement le libellé 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'.
ui.cssClass chaîne 'google-visualization-controls-rangefilter' Classe CSS à attribuer à la commande pour obtenir un style personnalisé

StringFilter

Champ de saisie de texte simple qui vous permet de filtrer des données via la mise en correspondance de chaînes. Il est mis à jour après chaque touche: essayez de saisir j pour réduire la table ci-dessous à John et Jessica.

État

Nom Type Par défaut Description
valeur chaîne ou objet none Texte actuellement saisi dans le champ de saisie de la commande.

Options

Nom Type Par défaut Description
filterColumnIndex Nombre none Colonne du tableau de données sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnLabel. Si ces deux options sont présentes, cette option prévaut.
filterColumnLabel chaîne none Étiquette de la colonne sur laquelle le filtre doit fonctionner. Vous devez obligatoirement fournir cette option ou filterColumnIndex. Si les deux sont présents, filterColumnIndex est prioritaire.
matchType chaîne "préfixe" Indique si la commande doit correspondre uniquement à des valeurs exactes ('exact'), aux préfixes commençant par le début de la valeur ('prefix') ou à n'importe quelle sous-chaîne ('any').
caseSensitive boolean false Indique si la correspondance doit être sensible à la casse ou non.
useFormattedValue boolean false Indique si le contrôle doit correspondre à des valeurs au format de cellule ou renvoyer des valeurs réelles.
ui Objets 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 littérale d'objet, comme indiqué ci-dessous : 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true Indique si la commande doit correspondre à chaque fois que l'utilisateur appuie sur une touche ou uniquement lorsque le champ de saisie "change" (perte de la sélection ou appui sur la touche Entrée).
ui.label chaîne auto Libellé à afficher à côté du champ de saisie. Si aucune valeur n'est spécifiée, l'étiquette de la colonne sur laquelle agit la commande sera utilisée.
ui.labelSeparator chaîne none Chaîne séparatrice ajoutée au libellé, pour séparer visuellement le libellé du champ de saisie.
ui.labelStacking chaîne "horizontal" Indique si le libellé doit s'afficher au-dessus (empilement vertical) ou à côté (empilement horizontal) du champ de saisie. Utilisez 'vertical' ou 'horizontal'.
ui.cssClass chaîne 'google-visualization-controls-stringfilter' Classe CSS à attribuer à la commande pour obtenir un style personnalisé