Événements de déclenchement

Votre visualisation peut déclencher des événements qu'une page hôte peut enregistrer pour recevoir. Les événements peuvent être déclenchés par une action de l'utilisateur (par exemple, un utilisateur clique sur un graphique) ou peuvent être internes (par exemple, un événement toutes les 10 secondes). 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 visualisation définit ses propres événements, et la documentation associée doit décrire le moment où chaque événement est déclenché, sa signification et les informations qu'il envoie à votre gestionnaire d'événements (par exemple, la visualisation sous forme d'organigramme). Cette page décrit comment un créateur de visualisations peut déclencher des événements. Pour savoir comment les clients peuvent s'inscrire pour recevoir des événements, consultez la page Gérer les événements.

Il existe un événement que toute visualisation sélectionnable doit déclencher: l'événement select. Cependant, le comportement et la signification de cet événement sont définis par chaque visualisation.

Si une visualisation n'est pas prête à interagir immédiatement après que la méthode draw rend le contrôle à l'utilisateur, la visualisation doit se déclencher: l'événement "ready". Le comportement et la signification exacts de cet événement sont définis dans la section Événement prêt.

Il est important de noter que les événements de l'API Visualization sont distincts des événements standards du DOM.

Sommaire

  1. Déclencher un événement
  2. L'événement Sélectionner
  3. L'événement "Ready"
  4. En savoir plus

Déclencher un événement

Pour déclencher un événement à partir de votre visualisation, appelez la fonction google.visualization.events.trigger(). La fonction attend les paramètres suivants :

  1. Visualisation source (il s'agit généralement de la valeur this).
  2. Nom de l'événement (chaîne).
  3. Détails de l'événement (objet). Carte facultative (nom/valeur) des détails d'un événement spécifique.

L'exemple suivant montre comment une visualisation génère l'événement de sélection: 

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Fire a select event.
  google.visualization.events.trigger(this, 'select', {});
};

Les pages Hosting peuvent s'inscrire pour recevoir vos événements en appelant google.visualization.events.addListener() ou google.visualization.events.addOneTimeListener(). Veillez à documenter minutieusement tous les événements déclenchés.

Sélectionner un événement

L'événement "select" est un événement standard généré par de nombreuses visualisations en réponse à un clic de la souris d'un utilisateur. Si vous choisissez de déclencher un événement en réponse à des clics de souris, vous devez implémenter l'événement "select" en suivant la procédure standard décrite ci-dessous:

  1. Déclencher un événement nommé "select" lorsque l'utilisateur sélectionne des données dans la visualisation. L'événement n'envoie aucun argument aux fonctions d'écoute.
  2. Exposez la méthode getSelection() comme décrit dans la section du document associé. Cette méthode doit renvoyer les index des éléments data sélectionnés par l'utilisateur.
  3. Exposez une méthode setSelection() comme décrit dans la documentation de référence. Consultez également la page Gérer les événements pour découvrir comment gérer les événements.

Événement "Ready"

Toute visualisation doit déclencher un événement "prêt" qui fonctionne de manière standard pour indiquer au développeur quand la visualisation est prête à traiter les méthodes appelées. (Toutefois, il n'existe aucune exigence absolue qu'une visualisation se comporte de cette manière. Consultez la documentation de votre visualisation.)

En général, les visualisations qui exposent l'événement "ready" sont conçues 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).
  • La visualisation devrait déclencher l'événement "ready" lorsqu'elle est prête à interagir. Si le dessin de la visualisation 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.
  • En appelant des méthodes d'interaction avant le déclenchement de l'événement "ready", vous prenez le risque que ces méthodes ne fonctionnent pas correctement.

Par convention, les visualisations qui ne déclenchent pas d'événement "ready" sont prêtes à interagir immédiatement après la fin de la méthode draw et rend le contrôle à l'utilisateur.

Plus d'infos