CKTIS / JavaScript
WAAPI: array de fotogramas clave y opciones de temporización
Pasa un array de fotogramas clave a `Element.animate()` y usa un objeto de opciones aparte para fijar la duración, la progresión y el número de iteraciones.
Versión: Current web platform; runtime support varies
Sintaxis
element.animate(keyframes, { duration, easing, iterations })
element.animate(keyframes, duration)element.animate(keyframes, options) crea y reproduce una animación en un elemento del DOM y devuelve el objeto Animation. El método y sus opciones de temporización pertenecen a la API de animaciones web (WAAPI), no a ECMAScript 2024 ni a ninguna otra edición de ECMAScript. Su disponibilidad depende del entorno de ejecución.
En un array de fotogramas clave, cada objeto fija valores de propiedades CSS animables, como opacity, en un punto de la iteración. offset sitúa ese punto entre 0 y 1, ambos incluidos. Los valores explícitos de offset deben estar en orden no decreciente. Las posiciones omitidas se reparten de manera uniforme: tres fotogramas sin offset reciben 0, 0.5 y 1. Un solo objeto con arrays de valores por propiedad, como { opacity: [0, 1] }, es otro formato admitido.
En las opciones, un duration numérico mide la duración de una sola iteración en milisegundos. Pasar un número como segundo argumento es una forma abreviada de establecer únicamente duration. iterations es el número total de iteraciones: el valor predeterminado es 1, 2.5 indica dos iteraciones completas y la mitad de una tercera, y el valor numérico Infinity no impone un límite finito. Con una duración positiva y finita y un número finito de iteraciones, la duración activa es duration * iterations, sin contar los retrasos.
En las opciones, easing es una función de progresión CSS escrita como cadena; el valor predeterminado es "linear". Cambia cómo avanza el progreso a lo largo de toda la iteración, no su duración. El easing de un fotograma clave se aplica desde ese fotograma hasta el siguiente; ambos ajustes pueden combinarse.
Ejemplos
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>WAAPI keyframes and timing</title>
<script>
(() => {
const element = document.createElement("div");
const keyframes = [
{ opacity: 0 },
{ opacity: 1, easing: "ease-in" },
{ opacity: 0 },
];
const animation = element.animate(keyframes, {
duration: 600,
easing: "ease-in-out",
iterations: 2.5,
});
const effect = animation.effect;
const { duration, easing, iterations, activeDuration } = effect.getComputedTiming();
const offsets = effect.getKeyframes().map(frame => frame.computedOffset);
console.log(`Offsets: ${offsets.join(", ")}`);
console.log(`${duration} ms × ${iterations} = ${activeDuration} ms; easing: ${easing}`);
animation.cancel();
})();
</script>
</html>Resultado
Offsets: 0, 0.5, 1 600 ms × 2.5 = 1500 ms; easing: ease-in-out
Guarda el ejemplo como archivo HTML, ábrelo en un navegador compatible con WAAPI y consulta la consola de desarrollo. El elemento no se añade a la página: el ejemplo muestra las posiciones y los valores de temporización calculados sin esperar y luego cancela la animación.
Lecciones relacionadas
- JavaScript · Lección 29 · Intermedio · Versión: 3