Eventos

La librería de Cordova incluye una serie de eventos JavaScript a los cuales podemos escuchar para lanzar determinadas acciones cuando se produzcan estos eventos. A continuación se incluye una tabla con la lista de los eventos incluidos por defecto en la librería y las plataformas que los soportan:

Android

Blackberry10

iOS

WP8

Windows

deviceready

pause

resume

backbutton

menubutton

searchbutton

startcallbutton

endcallbutton

volumedownbutton

volumeupbutton

activated

Además podemos instalar plugins que nos darán acceso a más tipos de eventos. Por ejemplo, si instalamos el plugin para el control de la batería (org.apache.cordova.battery-status) se añadirán los siguientes eventos (ver sección de plugins):

batterycritical
batterylow
batterystatus

O si instalamos el plugin para obtener información de la red (org.apache.cordova.network-information) se añadirán los siguientes eventos (ver sección de plugins):

online
offline

Uso de eventos

En general todos los eventos se utilizan de la misma forma: definiendo un listener en JavaScript que se lanzará cada vez que se produzca el evento. Sin embargo, para poder añadir este listener es importante que se haya terminado de cargar tanto el código web como la librería de Cordova, ya que en otro caso no funcionaría.

Por lo tanto, para poder utilizar los eventos primero vamos a ver cómo esperar a que se haya cargado todo lo necesario para poder utilizarlos. Como ya hemos dicho, en primer lugar tendremos que esperar a que haya terminado de cargar la propia web, para esto añadiremos el evento "onload" a la etiqueta HTML "<body>", de la forma: <body onload="onLoad()">. Esto producirá que se llame a la función JavaScript "onLoad" cuando haya finalizado la carga. Dentro de esta función "onLoad" tendremos que añadir un listener al evento "deviceready" para esperar que se haya terminado de cargar la librería de Cordova. El uso de este evento es esencial para cualquier aplicación con Cordova y lo tendremos que utilizar de forma inicial para asegurarnos de que la API se ha cargado completamente. A continuación se incluye un ejemplo de uso:

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">
      // Esperamos a que se cargue la API de Cordova
      function onLoad() {
          document.addEventListener("deviceready", onDeviceReady, false);
      }

      // La API de Cordova ya está disponible
      function onDeviceReady() {
          // ¡Ya podemos usar la librería de Cordova!
      }
    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

Al ejecutar el código anterior en primer lugar se llamaría a la función "onLoad" cuando se termine de cargar la propia Web. Dentro de esta función se define el listener al evento "deviceready", el cual se lanzará cuando se haya terminado de cargar la librería de Cordova, llamando a la función "onDeviceReady". Una vez se ha cargado la API de Cordova ya podremos añadir listeners a los eventos que queramos. Para suscribirnos a un evento utilizaremos el siguiente código:

document.addEventListener("nombre-evento", funcionCallback, false);

Donde:

nombre-evento: es el evento al que queremos escuchar, por ejemplo "pause", "resume", etc.
funcionCallback: es la función que se llamará cuando el evento se produzca.
false: el tercer parámetro (llamado useCapture) es opcional y recibe un valor booleano. Afecta al orden en el que se lanzará el evento con respecto a su posición en el DOM. Imaginemos que estamos respondiendo al evento click de un elemento que está dentro de otro (que sería su padre) que también está escuchando a este evento. Este atributo nos permite establecer qué evento se lanzará primero, si el del padre y después el del hijo (useCapture=true) o primero el del hijo y después el del padre (useCapture=false). Este último sería el comportamiento por defecto.

Ejemplos de uso de eventos

A continuación vamos a ver cómo tendríamos que utilizar algunos de los principales eventos de Cordova.

Evento pause

Este evento se produce cuando la aplicación pasa a segundo plano. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
  <head>
    <title>Pause Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">
      function onLoad() {
          document.addEventListener("deviceready", onDeviceReady, false);
      }

      // Añadimos el evento cuando la API esté lista
      function onDeviceReady() {
          document.addEventListener("pause", onPause, false);
      }

      // Se ha producido el evento pause!
      function onPause() {
      }
    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

En todos los eventos tendremos que esperar a que la API de Cordova termine de cargar.

Evento resume

Este evento se produce cuando la aplicación estaba en segundo plano y se vuelve a mostrar en primer plano. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
  <head>
    <title>Resume Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">
      function onLoad() {
          document.addEventListener("deviceready", onDeviceReady, false);
      }

      // Añadimos el evento cuando la API esté lista
      function onDeviceReady() {
          document.addEventListener("resume", onResume, false);
      }

      // Se ha producido el evento "resume"!
      function onResume() {
      }
    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

Evento backbutton

Este evento se produce cuando el usuario pulsa el botón atrás. A continuación se incluye un ejemplo completo de uso:

<!DOCTYPE html>
<html>
  <head>
    <title>Back Button Example</title>
    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8">
      function onLoad() {
          document.addEventListener("deviceready", onDeviceReady, false);
      }

      // Añadimos el evento cuando la API esté lista
      function onDeviceReady() {
          document.addEventListener("backbutton", onBackKeyDown, false);
      }

      // Se ha producido el evento "backbutton"!
      function onBackKeyDown() {
      }
    </script>
  </head>
  <body onload="onLoad()">
  </body>
</html>

Salir de la aplicación

Por defecto, al pulsar el botón back no se cerrará la aplicación. Si queremos que se cierre tendremos que hacer:

document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
   navigator.app.exitApp()
}

Hemos de tener cuidado con esta funcionalidad porque cerrará la aplicación siempre que se pulse dicha tecla. Si nuestra aplicación tiene varias páginas y queremos que se use el botón back para volver a la página anterior y además que en la primera página cierre la aplicación tendremos que distinguir entre las páginas y solo cerrar en la primera.

Evento menubutton

Este evento se produce cuando el usuario pulsa el botón menú. Para su utilización, igual que en el resto de casos, simplemente tendremos que hacer (ejemplo abreviado):

document.addEventListener("menubutton", onMenuKeyDown, false);

function onMenuKeyDown() {
   // Se ha producido el evento "menubutton"!
}

Evento volumedownbutton

Este evento se produce cuando el usuario pulsa el botón para bajar el volumen. A continuación se incluye un ejemplo abreviado de uso:

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);

function onVolumeDownKeyDown() {
    // Se ha producido el evento "volumedownbutton"!
}

Evento volumeupbutton

Este evento se lanza cuando se pulsa el botón para subir el volumen. Igual que en el resto de casos, para su utilización tenemos que hacer:

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);

function onVolumeUpKeyDown() {
    // Se ha producido el evento "volumeupbutton"!
}

AnteriorAlmacenamiento SiguientePlugins

Última actualización hace 4 años