Activar eventos

Tu visualización puede activar eventos que una página host puede registrar para recibir. Los eventos pueden activarse mediante acciones del usuario, como un clic en un gráfico, o pueden ser internas, por ejemplo, pueden activar un evento cada 10 segundos. Puedes registrar un método de JavaScript para que se llame cuando se activen determinados eventos, tal vez con datos específicos de ese evento.

Cada visualización define sus propios eventos, y la documentación de esa visualización debe describir cuándo se activa cada evento, qué significa y qué información envía al controlador de eventos (por ejemplo, consulta la visualización del gráfico de organización). En esta página, se describe cómo un creador de visualización puede activar eventos. A fin de obtener más información sobre cómo los clientes pueden registrarse para recibir eventos, consulta la página Administra eventos.

Hay un evento que cualquier visualización seleccionable debe activar. Sin embargo, el comportamiento y el significado de este evento se definen por cada visualización.

Si una visualización no está lista para la interacción inmediatamente después de que el método draw le muestre el control al usuario, se debe activar la visualización: el evento Ready. El comportamiento y el significado exactos de este evento se definen en la sección El evento preparado.

Es importante tener en cuenta que los eventos de la API de visualización son independientes y distintos de los eventos estándares del DOM.

Contenido

  1. Activación de un evento
  2. El evento de Select
  3. El evento Ready
  4. Más información

Cómo activar un evento

Para activar un evento de tu visualización, llama a la función google.visualization.events.trigger(). La función espera los siguientes parámetros:

  1. Visualización de la fuente (por lo general, es el valor this)
  2. Nombre del evento (string).
  3. Detalles del evento (objeto). Un mapa opcional (nombre/valor) de los detalles específicos del evento.

En el siguiente ejemplo, se muestra cómo una visualización genera el evento seleccionado: 

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', {});
};

Las páginas de hosting pueden registrarse para recibir tus eventos llamando a google.visualization.events.addListener() o google.visualization.events.addOneTimeListener(). Asegúrate de documentar exhaustivamente cualquier evento que actives.

El evento Select

El evento de selección es un evento estándar que producen muchas visualizaciones en respuesta a un clic del usuario del mouse. Si decides activar un evento en respuesta a los clics del mouse, debes implementar el evento de selección de la manera estándar descrita aquí:

  1. Activar un evento con el nombre "seleccionar" cuando el usuario selecciona algunos datos dentro de la visualización El evento no envía argumentos a las funciones de escucha.
  2. Expón el método getSelection() como se describe en la sección del documento vinculado. Este método debe mostrar los índices de los elementos de data que seleccionó el usuario.
  3. Expón un método setSelection() como se describe en la sección referencia. Además, consulta la página sobre el control de eventos para obtener información sobre cómo controlarlos.

El evento Ready

Cualquier visualización debe activar un evento "listo" que funcione de manera estándar para informar al desarrollador cuando la visualización está lista para procesar los métodos llamados. (Sin embargo, no hay un requisito absoluto que una visualización se comporte de esta manera; revisa la documentación para tu visualización).

En general, las visualizaciones que exponen el evento "listo" están diseñadas con las siguientes especificaciones:

  • El evento de preparación no pasa ninguna propiedad al controlador (el controlador de la función no debe esperar que se le pase ningún parámetro).
  • La visualización debe activar el evento de preparación cuando la visualización está lista para la interacción. Si el dibujo de la visualización es asíncrono, es importante que el evento se active cuando se pueda llamar a los métodos de interacción, no solo cuando finalice el método draw.
  • Debes agregar un objeto de escucha a este evento antes de llamar al método draw, ya que, de lo contrario, el evento podría activarse antes de que se configure el objeto de escucha y no lo detectarías.
  • Si llamas a los métodos de interacción antes de que se active el evento listo, corres el riesgo de que estos métodos no funcionen de forma correcta.

La convención es que las visualizaciones que no activan un evento "listo" están listas para la interacción inmediatamente después de que finaliza el método draw y muestra el control al usuario.

Más información