Web Animations API - Aprender JavaScript

La Web Animations API

La Web Animations API (WAAPI) te permite crear y controlar animaciones directamente desde JavaScript, sin ninguna biblioteca externa. Ejecuta las animaciones en el compositor propio del navegador — el mismo motor que impulsa las animaciones CSS — por lo que obtienes un movimiento suave con aceleración de hardware, pero con el control programático de las animaciones JavaScript: puedes reproducir, pausar, invertir, acelerar, buscar y encadenar animaciones en tiempo de ejecución.

Esta página cubre las dos partes que necesitas: el método element.animate() que inicia una animación, y el objeto Animation que devuelve, el cual usas para controlar la reproducción y saber cuándo termina la animación.

`element.animate(keyframes, options)`

Toda animación WAAPI comienza con una sola llamada:

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

keyframes — los estados visuales por los que se transitará. Se aceptan dos formas:
- un array de objetos, donde cada objeto es un fotograma: [{ opacity: 0 }, { opacity: 1 }]
- un object de arrays, donde cada propiedad lista sus valores a lo largo de la línea de tiempo: { opacity: [0, 1] }
options — un número (la duración en milisegundos) o un objeto de temporización como { duration: 1000, easing: "ease-in-out", fill: "forwards" }.

La llamada devuelve un objeto Animation y comienza a reproducirse de inmediato. Los nombres de las propiedades usan la forma camelCase de CSS (backgroundColor, no background-color).

Animación básica con la Web Animations API

Crear una animación básica con la Web Animations API implica definir los fotogramas clave de la animación, especificar el elemento objetivo y configurar las opciones de animación. A continuación se muestra un ejemplo simplificado de cómo animar la opacidad de un elemento:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Simple Opacity Animation</title>
  </head>
  <body>
    <h1>Simple Opacity Animation</h1>
    <div
      class="animated-element"
      style="width: 100px; height: 100px; background-color: blue"
    ></div>
    <button style="margin-top: 15px" onclick="startAnimation()">
      Start Animation
    </button>
    <p id="message"></p>
    <script>
      let animation;

      function startAnimation() {
        const element = document.querySelector(".animated-element");
        const keyframes = [
          { opacity: 0, offset: 0 },
          { opacity: 1, offset: 1 },
        ];
        const options = {
          duration: 1000,
          easing: "ease-in-out",
          iterations: 1,
          fill: "forwards",
        };

        // Create and play the animation
        animation = element.animate(keyframes, options);

        // Handle animation events
        animation.onfinish = () => {
          document.getElementById("message").textContent =
            "Animation finished!";
        };

        animation.oncancel = () => {
          document.getElementById("message").textContent = "Animation reset.";
        };
      }

      // Resets the animation
      function resetAnimation() {
        if (animation) {
          animation.cancel();
        }
        startAnimation(); // Restart the animation
      }
    </script>
  </body>
</html>

Pruébalo tú mismo »

Este ejemplo muestra cómo animar la opacidad de un elemento usando la Web Animations API. Un botón activa la animación, que cambia suavemente la opacidad del elemento de invisible (0) a completamente visible (1). Una vez que la animación se completa, se muestra un mensaje al usuario. Esto ilustra el control básico de animaciones y el manejo de eventos.

Opciones de temporización

El segundo argumento de animate() controla cómo se ejecuta la animación a lo largo del tiempo. Las claves más útiles son:

Opción	Qué hace
`duration`	Duración de una iteración, en milisegundos (o una cadena de tiempo CSS como `"1s"`).
`iterations`	Cuántas veces repetir. Usa `Infinity` para repetir indefinidamente.
`easing`	La curva de aceleración: `"linear"`, `"ease"`, `"ease-in-out"`, o un `cubic-bezier(...)`.
`fill`	Qué estado mantener fuera del rango activo. `"forwards"` mantiene el último fotograma; `"backwards"` aplica el primer fotograma durante el `delay`; `"both"` hace ambas cosas.
`delay`	Milisegundos a esperar antes de comenzar.
`direction`	`"normal"`, `"reverse"`, o `"alternate"` (rebota hacia adelante y hacia atrás en cada iteración).

Sin fill: "forwards", un elemento vuelve de golpe a sus estilos originales en el instante en que termina la animación — una fuente habitual de confusión. Úsalo cuando el fotograma final deba permanecer.

El objeto `Animation`

element.animate() devuelve una instancia de Animation. Este es el manejador que usas después de que la animación haya comenzado:

Miembro	Propósito
`play()`	Inicia o reanuda la reproducción.
`pause()`	Congela en el punto actual.
`reverse()`	Ejecuta desde el punto actual de vuelta hacia el inicio.
`finish()`	Salta directamente al final (o al inicio, si está invertida).
`cancel()`	Detiene y elimina todos los efectos, borrando los estilos aplicados.
`finished`	Una Promise que se resuelve cuando la animación se completa — ideal para secuencias con `await`.
`playState`	`"running"`, `"paused"`, `"finished"`, o `"idle"`.
`playbackRate`	Multiplicador de velocidad; `2` es el doble de velocidad, `-1` reproduce al revés.

const anim = box.animate({ transform: ["translateX(0)", "translateX(200px)"] }, 1000);

anim.pause();          // hold in place
anim.playbackRate = 2; // play twice as fast when resumed
anim.play();

anim.finished.then(() => console.log(anim.playState)); // "finished"

Dado que finished es una Promise real, puedes usar await para ejecutar código solo después de que termine el movimiento, o para encadenar animaciones de forma limpia — como hace el siguiente ejemplo.

Animaciones complejas y secuencias

Para animaciones más complejas y secuencias, puedes encadenar múltiples animaciones usando promises y async/await. A continuación se muestra un ejemplo de cómo encadenar animaciones:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Animation Sequence</title>
  </head>
  <body>
    <h1>Animation Sequence</h1>
    <div
      class="animated-element"
      style="width: 100px; height: 100px; background-color: red"
    ></div>
    <button style="margin-top: 15px" onclick="animateSequence()">
      Start Animation
    </button>
    <p id="message"></p>
    <script>
      async function animateSequence() {
        document.getElementById("message").textContent = ""; // Clear message
        const element = document.querySelector(".animated-element");
        const animation1 = element.animate(
          { opacity: [0, 1], transform: ["scale(0)", "scale(1)"] },
          { duration: 1000, easing: "ease-in-out" }
        );

        await animation1.finished;

        const animation2 = element.animate(
          { opacity: [1, 0], transform: ["scale(1)", "scale(0)"] },
          { duration: 1000, easing: "ease-in-out" }
        );

        await animation2.finished;
        document.getElementById("message").textContent = "Sequence complete!";
      }
    </script>
  </body>
</html>

Pruébalo tú mismo »

En este ejemplo, la primera animación aumenta la opacidad del elemento y lo escala hacia arriba, y al completarse, la segunda animación desvanece el elemento y lo escala hacia abajo. Al final se muestra un mensaje de finalización, demostrando cómo encadenar animaciones de forma secuencial.

Control y gestión de animaciones

La Web Animations API también proporciona métodos para controlar y gestionar animaciones. Por ejemplo, puedes pausar, reanudar o cancelar una animación. A continuación se muestra un ejemplo de cómo pausar y reanudar una animación:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Toggle Animation Play/Pause</title>
  </head>
  <body>
    <h1>Toggle Play/Pause Animation</h1>
    <div
      class="animated-element"
      style="width: 100px; height: 100px; background-color: green"
    ></div>
    <button style="margin-top: 15px" onclick="togglePlayPause()">Toggle Play/Pause</button>
    <p id="message"></p>
    <script>
      let animation;

      document.addEventListener("DOMContentLoaded", function () {
        const element = document.querySelector(".animated-element");
        animation = element.animate(
          { opacity: [0, 1] },
          { 
            duration: 1000, 
            easing: "ease-in-out", 
            iterations: Infinity, 
            direction: "alternate" 
          }
        );
        animation.pause(); // Start paused

        animation.onfinish = () => {
          document.getElementById("message").textContent =
            "Animation finished!";
        };
      });

      function togglePlayPause() {
        if (animation.playState === "running") {
          animation.pause();
          document.getElementById("message").textContent = "Animation paused";
        } else {
          animation.play();
          document.getElementById("message").textContent = "Animation playing";
        }
      }
    </script>
  </body>
</html>

Pruébalo tú mismo »

Este ejemplo muestra cómo alternar entre los estados de reproducción y pausa de una animación con un clic. La animación inicial hace que un elemento aparezca y desaparezca de forma continua. Al hacer clic en un botón, el usuario puede pausar la animación si está en ejecución, o reproducirla si está pausada. Los mensajes indican el estado actual de la animación, mejorando la interacción del usuario y el control sobre los estados de animación.

Web Animations API vs animaciones CSS

Ambas se ejecutan en el mismo compositor, por lo que el rendimiento es comparable. La diferencia es el control:

Opta por las animaciones CSS cuando el movimiento es declarativo y estático — un efecto hover, un indicador de carga, una transición de entrada que puedes definir completamente en una hoja de estilos.
Opta por la Web Animations API cuando la animación depende de datos en tiempo de ejecución o de la entrada del usuario: valores de fotogramas clave dinámicos, pausar y reanudar bajo demanda, secuenciar varias animaciones, o reaccionar cuando una termina mediante la promise finished.

Un punto intermedio muy útil es mantener el estilo en clases — consulta Estilos y clases — y usar WAAPI solo para las transiciones que necesitan control mediante scripts.

Conclusión

La Web Animation API permite a los desarrolladores web crear animaciones cautivadoras e interactivas que mejoran la experiencia del usuario en sitios web y aplicaciones web. Al dominar esta API, puedes crear animaciones que van desde simples transiciones hasta secuencias complejas, añadiendo una dimensión dinámica y atractiva a tus diseños web. Ya sea que estés animando interfaces de usuario, añadiendo efectos visuales o creando elementos de narración interactiva, la Web Animations API proporciona las herramientas que necesitas para dar vida a tus ideas creativas en la web.

Práctica

¿Qué funcionalidades ofrece la JavaScript Animation API?

Permite crear animaciones en la web.Ayuda a resolver ecuaciones matemáticas.La API se utiliza para crear animaciones basadas en JavaScript en HTML.Permite realizar llamadas telefónicas usando JavaScript.Solo admite animaciones basadas en CSS.

La Web Animations API

element.animate(keyframes, options)

Animación básica con la Web Animations API

Opciones de temporización

El objeto Animation

Animaciones complejas y secuencias

Control y gestión de animaciones

Web Animations API vs animaciones CSS

Conclusión

Práctica

`element.animate(keyframes, options)`

El objeto `Animation`