Cómo administrar eventos

Stay organized with collections Save and categorize content based on your preferences.

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

Contenido

Descripción general

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

Cada gráfico define sus propios eventos, y la documentación de ese gráfico debe describir cuándo se activa cada evento, qué significa y cómo recuperar toda la 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.

Un gráfico seleccionable debe activar un evento: el evento de selección. Sin embargo, el comportamiento y el significado de este evento se definen en cada gráfico.

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

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 detectará y el nombre de la función que se debe llamar cuando se activa. 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 el gráfico expone un evento listo, siempre debes esperar a que ese evento se active antes de intentar enviar métodos o recibir eventos del gráfico. Estos gráficos pueden funcionar antes de arrojar 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á a fin de detectar eventos para 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 de un evento

Por lo general, los eventos exponen información de dos maneras: pasando información a la función del controlador como parámetro o agregando información a un objeto global. Si la información se expone y cómo se debe exponer el evento, consulta 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 pasa al controlador

Si el gráfico pasa datos como un parámetro a tu función de control, los recuperarás 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 pase a tu controlador tendrá una propiedad que se debe documentar para el gráfico. Para ver un ejemplo de un gráfico que exponga la información de eventos de esta manera, consulta el evento de la página del gráfico Table.

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

En cambio, algunos eventos cambian una propiedad de un objeto global, que luego puedes solicitar. Un ejemplo común de esto es el evento "seleccionar", 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 saber cuál es la selección actual. A continuación, se proporciona más información sobre el evento seleccionado.

// 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, cualquier gráfico que se pueda seleccionar debe activar un evento "select" que funcione de manera estándar para que puedas recuperar los valores del elemento seleccionado en el gráfico. (Sin embargo, no hay un requisito absoluto que indique que un gráfico se comporte de esta manera; revisa la documentación de tu gráfico).

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

  • El evento de selección no pasa ningún objeto o propiedad al controlador (tu controlador de funciones no debe esperar que se le pase ningún parámetro).
  • El gráfico debería exponer el método getSelection(), que muestra un arreglo de objetos que describe 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 en el gráfico, no los elementos HTML en el 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 las 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 "select".
    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 que solo muestra las filas seleccionadas puede ignorar los elementos de celda o columna en su implementación de setSelection).
  • Es posible que algunos gráficos no activen un evento de “selección” y otros solo admitan la selección de filas o columnas. La documentación de cada gráfico define los eventos y métodos que admite.
  • La selección múltiple se controla de manera diferente en diferentes gráficos (algunos ni siquiera lo permiten).
  • Para leer los datos seleccionados, deberás llamar a DataTable.getValue() en tu controlador; la forma más simple de hacerlo es hacer que el objeto DataTable sea global.

En el siguiente ejemplo, se muestra 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 ready

La mayoría de los gráficos se procesan de forma asíncrona; todos los gráficos de Google muestran un evento listo después de que llamas a draw(), lo que indica que 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 listo 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 "Ready" después de que 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 el método draw finalice.
  • 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 correctamente.

La convención es que los gráficos que no activan un evento "listo" están listos para la interacción inmediatamente 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 Ready

function myReadyHandler(){...}

El controlador de eventos listo no recibe ningún parámetro.

El evento error

Los gráficos deben mostrar un evento de error cuando se encuentran con algún tipo de error, para que puedas manejarlo correctamente. El controlador de eventos recibe una descripción del error, así como propiedades de eventos personalizadas específicas de cada gráfico. Debes suscribirte a este evento inmediatamente después de crear una instancia del gráfico para interceptar 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 errores

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 tipo de gráfico.

Ejemplo de manejo 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: