Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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

Fontes