El objeto Animation

Si has creado alguna animación con WebAnimations, como las que hemos hecho en los ejemplos de los últimos artículos, habrás observado que el valor devuelto por el método .animate() lo estamos guardando en una constante animation.

Esta constante es un objeto Animation, mediante el cuál podemos gestionar ciertas acciones con la animación generada en cuestión:

const keyframes = [ /* ... */ ];
const options = { /* ... */ };

const animation = element.animate(keyframes, options);

Vamos a analizar que es exactamente ese objeto Animation y que podemos hacer con él.

El objeto Animation

Al ejecutar el método animate() y crear una WebAnimation, dicho método nos devuelve un objeto Animation que, entre otras cosas, podemos encontrar las siguientes propiedades:

Especialmente interesantes son las propiedades .ready y finished, que devuelven una promesa mediante la cuál podemos saber cuando una animación está lista para iniciarse o cuando ha terminado, y por ejemplo podemos encadenar con otra acción.

Por su parte, startTime nos devuelve el momento en el que empezó a reproducirse (o una fecha en el futuro para programar la animación), mientras que currentTime nos dice los segundos totales que han transcurrido de la animación:

const animation = element.animate(keyframes, options);

animation.ready.then(() => {
  console.log(`¡Animación preparada!`);
});

animation.finished.then(() => {
  console.log(`¡Animación terminada! Han pasado ${animation.currentTime}ms.`)
});

Métodos de Animation

Mediante algunos métodos como play(), pause(), finish() o cancel() podemos controlar las animaciones, terminarlas o cancelarlas. Observa también que tienen algunos eventos asociados para detectar cuando ocurre.

Observa que los navegadores por defecto, al tener animaciones encadenadas, al terminar una animación e iniciar otra, eliminan la anterior automáticamente. Cuando esto ocurre, se dispara un evento remove que podemos utilizar para gestionar tareas cuando ocurren estas eliminaciones. Además, con el método persist() podemos establecer que no se eliminen automáticamente.

El método getAnimations()

Algo interesante que también hay que mencionar, es que puede que necesitemos en algún momento saber si existe alguna animación funcionando para acceder a ella y realizar modificaciones.

Existe un método global del navegador que podemos ejecutar sobre el objeto document. Se trata de document.getAnimations(). Este método devuelve un array con todas las animaciones en ejecución en la página actual:

const currentAnimations = document.getAnimations();

// Devuelve:
//   [ CSSAnimation {…}, Animation {…} ]

En este caso, la primera posición del array es una instancia de CSSAnimation, o lo que es lo mismo, una animación creada desde CSS. Por otro lado, la segunda es una instancia de Animation, que es una animación de WebAnimation. Ambas se pueden controlar mediante la API de WebAnimation, si accedemos a ellas:

const [firstAnimation, secondAnimation] = document.getAnimations();

firstAnimation.cancel();    // Cancelamos la primera animación
secondAnimation.pause();    // Pausamos la segunda animación

El método getAnimations() si lo ejecutamos sobre document nos devolverá todas las animaciones utilizadas en la página, pero también podemos ejecutarlo en el elemento del DOM que nos interese para saber si hay alguna animación asociada a ese elemento en cuestión.