El objeto Animation

Gestionar o manipular animaciones


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:

Propiedad Descripción
Información
startTime Hora (timestamp) en la que la animación ha empezado o empezará a reproducirse.
currentTime Número de ms en el que se encuentra la animación. Si está inactiva, null.
id Cadena de texto para identificar la animación.
playState Estado actual de la animación. Puede ser idle, running, paused o finished.
playbackRate Velocidad de reproducción de la animación. Por defecto, 1, velocidad normal.
replaceState Indica estado de animación. Puede ser active, persisted o removed.
Comprobaciones
ready Indica si la animación está lista.
finished Indica si la animación ha terminado.
pending Indica si la animación está pendiente y no está lista aún.

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.

Método Descripción Evento asociado
Métodos
play() Inicia o reanuda la animación.
pause() Detiene temporalmente la animación.
finish() Termina la animación. finish: Se dispara el evento al terminar la animación.
cancel() Aborta la animación. cancel: Se dispara el evento al abortar la animación.
remove: Se dispara el evento al eliminar la animación automáticamente.
persist() Indica que la animación sea persistente y no se elimine automáticamente al iniciar otra.
reverse() Invierte la dirección de reproducción.
updatePlaybackRate() Hace efectiva la velocidad de animación indicada en playbackRate.

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.

¿Quién soy yo?

Soy Manz, vivo en Tenerife (España) y soy streamer partner en Twitch y profesor. Me apasiona el universo de la programación web, el diseño y desarrollo web y la tecnología en general. Aunque soy full-stack, mi pasión es el front-end, la terminal y crear cosas divertidas y locas.

Puedes encontrar más sobre mi en Manz.dev