CKTIS / JavaScript
WAAPI: array de fotogramas-chave e opções temporais
Passa um array de fotogramas-chave a `Element.animate()` e usa um objeto de opções separado para definir a duração, a progressão e o número de iterações.
Versão: Current web platform; runtime support varies
Sintaxe
element.animate(keyframes, { duration, easing, iterations })
element.animate(keyframes, duration)element.animate(keyframes, options) cria e inicia uma animação num elemento do DOM e devolve o objeto Animation. Este método e as suas opções temporais fazem parte da Web Animations API (WAAPI), não do ECMAScript 2024 nem de qualquer outra edição do ECMAScript. A sua disponibilidade depende do ambiente de execução.
Num array de fotogramas-chave, cada objeto indica valores de propriedades CSS animáveis, como opacity, num ponto da iteração. offset situa esse ponto entre 0 e 1, inclusive. Os valores explícitos de offset têm de estar por ordem não decrescente. As posições omitidas são distribuídas uniformemente: três fotogramas sem offset recebem 0, 0.5 e 1. Um único objeto com arrays de valores por propriedade, como { opacity: [0, 1] }, é outro formato aceite.
Nas opções, um duration numérico indica a duração de uma só iteração em milissegundos. Passar um número como segundo argumento é uma forma abreviada de definir apenas duration. iterations indica o número total de iterações: o valor predefinido é 1, 2.5 significa duas iterações completas e metade da terceira, e o valor numérico Infinity não impõe um limite finito. Com uma duração positiva e finita e um número finito de iterações, a duração ativa é duration * iterations, sem contar os atrasos.
Nas opções, easing é uma função de progressão CSS escrita como cadeia de caracteres; a predefinição é "linear". Altera a progressão ao longo de toda a iteração, não a sua duração. O easing de um fotograma-chave aplica-se desse fotograma até ao seguinte; as duas definições podem funcionar em conjunto.
Exemplos
<!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 o exemplo como ficheiro HTML, abre-o num navegador compatível com a WAAPI e consulta a consola de desenvolvimento. O elemento não é inserido na página: o exemplo apresenta as posições e os valores temporais calculados sem esperar e, depois, cancela a animação.
Lições relacionadas
- JavaScript · Lição 29 · Intermédio · Versão: 3