Gérer les événements

Cette page explique comment écouter et gérer les événements déclenchés par un graphique.

Sommaire

  1. Overview
  2. S'inscrire à un événement et gérer ce type d'événement
  3. Récupérer des informations sur un événement
  4. L'événement select
  5. L'événement ready
  6. L'événement error
  7. Exemple de gestion des événements

Présentation

Les graphiques Google peuvent déclencher des événements que vous pouvez écouter. Les événements peuvent être déclenchés par des actions de l'utilisateur, par exemple lorsqu'il clique sur un graphique. Vous pouvez enregistrer une méthode JavaScript à appeler chaque fois que certains événements sont déclenchés, éventuellement avec des données spécifiques à cet événement.

Chaque graphique définit ses propres événements, et sa documentation doit décrire quand chaque événement est déclenché, ce que cela signifie et comment récupérer les informations associées à l'événement. Cette page explique comment s'inscrire pour recevoir les événements d'un graphique et comment les gérer.

Tout graphique sélectionnable doit déclencher un événement: l'événement select. Cependant, le comportement et la signification de cet événement sont définis par chaque graphique.

Il est important de noter que les événements du graphique sont distincts des événements standards du DOM.

S'inscrire à un événement et gérer ce type d'événement

Pour enregistrer vos gestionnaires d'événements, appelez google.visualization.events.addListener() ou addOneTimeListener() avec le nom du graphique exposant l'événement, le nom de chaîne de l'événement à écouter et le nom de la fonction à appeler lorsque cet événement est déclenché. Votre fonction doit accepter un seul paramètre, à savoir l'événement déclenché. Cet événement peut contenir des informations personnalisées le concernant, comme décrit dans la documentation du graphique.

Important:Si votre graphique expose un événement prêt, vous devez toujours attendre que cet événement soit déclenché avant d'essayer d'envoyer des méthodes ou de recevoir des événements à partir du graphique. Ces graphiques peuvent fonctionner avant de générer un événement "prêt", mais ce comportement n'est pas garanti.

L'extrait de code suivant affiche une zone d'alerte chaque fois que l'utilisateur clique sur une ligne du tableau:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

Notez que cette action ne s'enregistrera que pour écouter les événements de cet objet de table spécifique. Vous ne pouvez vous inscrire que pour recevoir les événements d'un objet spécifique.

Vous pouvez également transmettre une définition de fonction, comme indiqué ci-dessous:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Récupérer des informations sur un événement

Les événements exposent généralement des informations de deux manières: en transmettant des informations à la fonction de gestionnaire en tant que paramètre ou en ajoutant des informations à un objet global. Le cas échéant et la manière dont l'événement expose des informations, consultez la documentation du graphique correspondant. Voici comment récupérer ces deux types d'informations:

Informations sur l'événement transmises à votre gestionnaire

Si le graphique transmet des données en tant que paramètre à votre fonction de traitement, vous les récupérez comme indiqué ci-dessous:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

Le paramètre transmis à votre gestionnaire possède une propriété qui doit être documentée pour le graphique. Pour obtenir un exemple de graphique exposant les informations sur les événements de cette manière, consultez l'événement de page du graphique Tableau.

Informations sur l'événement transmises à un objet global

À la place, certains événements modifient la propriété d'un objet global, que vous pouvez ensuite demander. L'événement "select", qui se déclenche lorsqu'un utilisateur sélectionne une partie d'un graphique, en est un exemple courant. Dans ce cas, le code doit appeler la méthode getSelection() sur le graphique pour connaître la sélection actuelle. Des informations supplémentaires sont données sur l'événement de sélection ci-dessous.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');

L'événement select

Comme indiqué précédemment, tout graphique pouvant être sélectionné doit déclencher un événement "select" qui fonctionne de manière standard pour vous permettre de récupérer les valeurs de l'élément sélectionné dans le graphique. Toutefois, il n'existe aucune exigence absolue pour qu'un graphique se comporte de cette manière. Consultez la documentation de votre graphique.

En général, les graphiques qui exposent l'événement "select" sont conçus avec les spécifications suivantes:

  • L'événement select ne transmet aucune propriété ni aucun objet au gestionnaire (votre gestionnaire de fonctions ne doit pas s'attendre à ce qu'aucun paramètre ne lui soit transmis).
  • Le graphique devrait exposer la méthode getSelection(), qui renvoie un tableau d'objets décrivant les éléments de données sélectionnés. Ces objets possèdent les propriétés row et column. row et column sont les index de ligne et de colonne de l'élément sélectionné dans DataTable. (Les événements de sélection décrivent les données sous-jacentes du graphique, et non les éléments HTML du graphique.) Pour obtenir les données de l'élément sélectionné, vous devez appeler DataTable.getValue() ou getFormattedValue().
    Si row et column sont tous les deux spécifiés, l'élément sélectionné est une cellule. Si seule row est spécifiée, l'élément sélectionné est une ligne. Si seule la valeur column est spécifiée, l'élément sélectionné est une colonne.
  • Le graphique devrait exposer la méthode setSelection(selection) pour modifier la sélection dans la table sous-jacente et sélectionner les données correspondantes dans le graphique. Le paramètre selection qui est un tableau semblable au tableau getSelection(), où chaque élément est un objet avec les propriétés row et column. La propriété row définit l'index de la ligne sélectionnée dans DataTable, tandis que la propriété column définit l'index de la colonne sélectionnée dans DataTable. Lorsque cette méthode est appelée, le graphique doit indiquer visuellement la nouvelle sélection. L'implémentation de setSelection() ne doit pas déclencher d'événement "select".
    Si row et column sont tous les deux spécifiés, l'élément sélectionné est une cellule. Si seule row est spécifiée, l'élément sélectionné est une ligne. Si seule la valeur column est spécifiée, l'élément sélectionné est une colonne.

Mises en garde:

  • Le graphique peut ignorer une partie de la sélection. Par exemple, une table qui ne peut afficher que les lignes sélectionnées peut ignorer les éléments de cellules ou de colonnes dans leur implémentation setSelection.)
  • Il est possible que certains graphiques ne déclenchent pas d'événement "select", et qu'ils ne soient compatibles qu'avec une sélection de lignes ou une sélection de colonnes entières. La documentation de chaque graphique définit les événements et les méthodes compatibles.
  • La sélection multiple est gérée différemment dans différents graphiques (certains ne l'autorisent même pas).
  • Pour lire les données sélectionnées, vous devez appeler DataTable.getValue() dans votre gestionnaire. Le moyen le plus simple d'activer cela est de rendre l'objet DataTable global.

L'exemple suivant affiche une zone d'alerte avec les éléments de tableau sélectionnés lorsqu'un élément d'un tableau est sélectionné:

Notez que le tableau ne déclenche que des événements de sélection de lignes. Toutefois, le code est générique et peut être utilisé pour les événements de sélection de lignes, de colonnes et de cellules.

Voici le code de gestionnaire pour cet exemple:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

L'événement ready

La plupart des graphiques sont affichés de manière asynchrone. Tous les graphiques Google génèrent un événement "ready" après avoir appelé draw() sur ceux-ci, ce qui indique qu'il est rendu et prêt à renvoyer des propriétés ou à gérer d'autres appels de méthode. Vous devez toujours écouter l'événement "ready" avant d'essayer d'appeler des méthodes sur celui-ci après avoir appelé draw().

En général, les graphiques qui exposent l'événement "ready" sont conçus avec les spécifications suivantes:

  • L'événement "ready" ne transmet aucune propriété au gestionnaire (votre gestionnaire de fonctions ne doit pas s'attendre à ce qu'aucun paramètre ne lui soit transmis).
  • Le graphique devrait déclencher l'événement "ready" une fois qu'il est prêt à interagir. Si le dessin du graphique est asynchrone, il est important que l'événement soit déclenché lorsque les méthodes d'interaction peuvent être appelées, et pas seulement à la fin de la méthode draw.
  • Vous devez ajouter un écouteur à cet événement avant d'appeler la méthode draw(), car sinon, l'événement pourrait être déclenché avant que l'écouteur ne soit configuré, et vous ne l'interceptez pas.
  • Si vous appelez des méthodes d'interaction avant le déclenchement de l'événement "ready", vous risquez que ces méthodes ne fonctionnent pas correctement.

Par convention, les graphiques qui ne déclenchent pas d'événement "ready" sont prêts à interagir immédiatement après la fin de la méthode draw et rend le contrôle à l'utilisateur. Si votre graphique déclenche un événement "ready", vous devez attendre qu'il soit généré avant d'appeler des méthodes sur celui-ci, comme indiqué ci-dessous:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Syntaxe du gestionnaire d'événements prêt

function myReadyHandler(){...}

Le gestionnaire d'événements "ready" n'a transmis aucun paramètre.

Événement error

Les graphiques doivent générer un événement d'erreur lorsqu'ils rencontrent une erreur, pour vous permettre de la gérer correctement. Le gestionnaire d'événements reçoit une description de l'erreur, ainsi que les propriétés d'événements personnalisés spécifiques à chaque graphique. Vous devez vous abonner à cet événement juste après avoir instancié le graphique pour piéger les erreurs qui pourraient survenir lors des étapes suivantes.

Vous pouvez utiliser les fonctions d'assistance goog.visualization.errors pour afficher facilement les erreurs.

Syntaxe du gestionnaire d'événements d'erreur

function myErrorHandler(err){...}

Un objet comportant les membres suivants doit être transmis au gestionnaire d'événements d'erreur:

  • L'attribut id [obligatoire] indique l'ID de l'élément DOM contenant le graphique, ou un message d'erreur affiché à la place du graphique s'il ne peut pas être affiché.
  • L'attribut message [obligatoire] est une courte chaîne de message décrivant l'erreur.
  • detailedMessage [facultatif] : explication détaillée de l'erreur.
  • L'attribut options [facultatif] : objet contenant les paramètres personnalisés adaptés à cette erreur et à ce type de graphique.

Exemple de gestion des événements

L'exemple suivant illustre les fonctions getSelection() et setSelection(). Il synchronise la sélection entre deux graphiques qui utilisent la même table de données. Cliquez sur l'un des graphiques pour synchroniser la sélection dans l'autre graphique.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

Cliquez sur les graphiques ci-dessous sur les lignes du tableau ou sur des éléments du graphique pour observer la sélection en action: