Cómo administrar eventos

En esta página, se describe cómo escuchar y controlar los eventos activados por un gráfico.

Contenido

Descripción general

Los gráficos de Google pueden activar eventos que puedes escuchar. Los eventos pueden activarse mediante acciones de los usuarios, como cuando un usuario hace clic en un gráfico. Puedes registrar un método de JavaScript para que se llame cuando se activan determinados eventos, tal vez con datos específicos de ese evento.

Cada gráfico define sus propios eventos, y la documentación para ese gráfico debe describir cuándo se activa cada evento, qué significa y cómo obtener cualquier información asociada con el evento. En esta página, se describe cómo registrarse para recibir eventos de un gráfico y cómo controlarlos.

Hay un evento que cualquier gráfico seleccionable debe activar. Sin embargo, el comportamiento y el significado de este evento están definidos por cada gráfico.

Es importante tener en cuenta que los eventos del gráfico son independientes y distintos de los eventos estándares del DOM.

Cómo registrarse y administrar un evento

Para registrar los controladores de eventos, llama a google.visualization.events.addListener() o addOneTimeListener() con el nombre del gráfico que expone el evento, el nombre de string del evento que se escuchará y el nombre de la función a la que se llamará cuando se active el evento. Tu función debe aceptar un solo parámetro, que es el evento que se activó. Este evento puede tener información personalizada sobre el evento, como se describe en la documentación del gráfico.

Importante: Si tu gráfico expone un evento listo, siempre debes esperar a que se active antes de intentar enviar métodos o recibir eventos del gráfico. Estos gráficos pueden funcionar antes de que generen un evento listo, pero ese comportamiento no está garantizado.

En el siguiente fragmento de código, se muestra un cuadro de alerta cada vez que el usuario hace clic en una fila de la tabla:

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

Ten en cuenta que esto solo se registrará para detectar eventos de este objeto de tabla específico; solo puedes registrarte para recibir eventos de un objeto específico.

También puedes pasar una definición de función, como se muestra aquí:

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

Cómo recuperar la información del evento

Por lo general, los eventos exponen información de dos maneras: pasando información a la función del controlador como un parámetro o agregando información a un objeto global. Si se debe describir cómo se expone la información, y cómo se lo realiza, se debe describir en la documentación de ese gráfico. A continuación, se indica cómo recuperar ambos tipos de información:

Información del evento que se envía al controlador

Si el gráfico pasa datos como parámetros a tu función de control, puedes recuperarlos como se muestra a continuación:

// 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']);
}

El parámetro que se pasa al controlador tendrá una propiedad que se debe documentar para el gráfico. Para ver un ejemplo de un gráfico que expone la información del evento de esta manera, consulta el evento de página del gráfico Tabla.

Información del evento que se pasa a un objeto global

En cambio, algunos eventos cambian la propiedad de un objeto global, que luego puedes solicitar. Un ejemplo común de esto es el evento de "selección", que se activa cuando un usuario selecciona una parte de un gráfico. En este caso, el código debe llamar a getSelection() en el gráfico para obtener información sobre la selección actual. Se proporciona más información sobre el evento de selección a continuación.

// 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.');
  

El evento select

Como se mencionó anteriormente, todos los gráficos que se pueden seleccionar deben activar un evento “select” que funcione de manera estándar para permitirte recuperar los valores del elemento seleccionado en el gráfico. (Sin embargo, no hay requisitos absolutos que un gráfico se comporte de esta manera; consulta la documentación para tu gráfico).

En general, los gráficos que exponen el evento de "selección" están diseñados con las siguientes especificaciones:

  • El evento de selección no pasa ninguna propiedad ni objeto al controlador (el controlador de la función no debe esperar que se le pase ningún parámetro).
  • El gráfico debe exponer el método getSelection(), que muestra un arreglo de objetos que describen los elementos de datos seleccionados. Estos objetos tienen las propiedades row y column. row y column son los índices de fila y columna del elemento seleccionado en DataTable. (Los eventos de selección describen los datos subyacentes del gráfico, no los elementos HTML del gráfico). Para obtener los datos del elemento seleccionado, deberás llamar a DataTable.getValue() o getFormattedValue().
    Si se especifican row y column, el elemento seleccionado es una celda. Si solo se especifica row, el elemento seleccionado es una fila. Si solo se especifica column, el elemento seleccionado es una columna.
  • El gráfico debe exponer el método setSelection(selection) para cambiar la selección en la tabla subyacente y seleccionar los datos correspondientes en el gráfico. El parámetro selection, que es un arreglo similar al arreglo getSelection(), en el que cada elemento es un objeto con propiedades row y column. La propiedad row define el índice de la fila seleccionada en DataTable, y la propiedad column define el índice de la columna seleccionada en DataTable. Cuando se llama a este método, el gráfico debe indicar visualmente cuál es la nueva selección. La implementación de setSelection() no debe activar un evento de selección.
    Si se especifican row y column, el elemento seleccionado es una celda. Si solo se especifica row, el elemento seleccionado es una fila. Si solo se especifica column, el elemento seleccionado es una columna.

Algunas advertencias:

  • Es posible que el gráfico ignore parte de la selección. Por ejemplo, una tabla en la que solo se pueden mostrar las filas seleccionadas puede ignorar los elementos de celda o de columna en su implementación de setSelection).
  • Es posible que algunos gráficos no activen un evento de “selección” y que algunos solo admitan la selección de filas o columnas enteras. En la documentación de cada gráfico, se definen los eventos y métodos que admite.
  • La selección múltiple se maneja de manera diferente en gráficos diferentes (algunos ni siquiera lo permiten).
  • Para leer los datos seleccionados, deberás llamar a DataTable.getValue() en tu controlador; la manera más sencilla de hacerlo es hacer que el objeto DataTable sea global.

En el siguiente ejemplo, aparece un cuadro de alerta con los elementos de tabla seleccionados, cuando se selecciona un elemento de un gráfico de tabla:

Ten en cuenta que el gráfico de tabla solo activa eventos de selección de fila; sin embargo, el código es genérico y se puede usar para eventos de selección de fila, columna y celda.

Este es el código del controlador para ese ejemplo:

// 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);
}

El evento listo

La mayoría de los gráficos se renderizan de forma asíncrona; todos los gráficos de Google muestran un evento listo después de que llamas a draw() en ellos, lo que indica que el gráfico se renderizó y está listo para mostrar propiedades o controlar más llamadas a métodos. Siempre debes escuchar el evento listo antes de intentar llamar a los métodos en él después de llamar a draw().

En general, los gráficos que exponen el evento "listo" están diseñados 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).
  • El gráfico debe activar el evento de preparación cuando el gráfico esté listo para la interacción. Si el dibujo del gráfico es asíncrono, es importante que el evento se active cuando se pueda llamar a los métodos de interacción, y 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 los gráficos que no activan un evento "listo" están listos para interactuar de inmediato después de que finaliza el método draw y muestra el control al usuario. Si el gráfico activa un evento listo, debes esperar a que se muestre antes de llamar a los métodos, como se muestra aquí:

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

Sintaxis del controlador de eventos listo

function myReadyHandler(){...}

El controlador de evento Ready no recibe ningún parámetro.

El evento error

Los gráficos deberían mostrar un evento de error cuando se encuentra algún tipo de error, para que puedas controlarlo correctamente. El controlador de eventos recibe una descripción del error, además de propiedades del evento personalizadas específicas de cada gráfico. Debes suscribirte a este evento inmediatamente después de crear una instancia del gráfico para atrapar cualquier error que pueda ocurrir en pasos posteriores.

Puedes usar las funciones auxiliares goog.visualization.errors para mostrar cualquier error al usuario de manera fluida.

Sintaxis del controlador de eventos de error

function myErrorHandler(err){...}

El controlador de evento de error debe pasar un objeto con los siguientes miembros:

  • id [obligatorio]: ID del elemento DOM que contiene el gráfico o un mensaje de error en lugar del gráfico si no se puede renderizar.
  • mensaje [obligatorio]: Es una string de mensaje breve que describe el error.
  • detailedMessage [opcional]: una explicación detallada del error.
  • options [Opcional]: Un objeto que contiene parámetros personalizados adecuados para este error y este tipo de gráfico.

Ejemplo de control de eventos

En el siguiente ejemplo, se muestra getSelection() y setSelection(). Sincroniza la selección entre dos gráficos que usan la misma tabla de datos. Haz clic en cualquiera de los gráficos para sincronizar la selección en el otro gráfico.

// 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());
});

Haz clic en los gráficos a continuación en las filas de la tabla o en los elementos del gráfico para ver la selección en acción: