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

CKTIS / JavaScript

KeyframeEffect — um efeito de animação de fotogramas-chave

KeyframeEffect descreve o alvo, os fotogramas-chave e os parâmetros temporais de um efeito. Um objeto Animation separado controla a reprodução.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

new KeyframeEffect(target, keyframes, options)
new KeyframeEffect(source)

KeyframeEffect é uma interface de Web Animations, não faz parte de ECMAScript. Herda de AnimationEffect e descreve alterações às propriedades CSS. A sua criação, por si só, não inicia a reprodução: atribua o efeito a um objeto Animation, cujo método play() inicia a reprodução. O atalho Element.animate() cria o efeito e a animação e inicia a reprodução.

target é um elemento ou null. keyframes aceita um array de fotogramas-chave ou um objeto com valores de propriedades. options é a duração de uma iteração em milissegundos ou um objeto com opções como duration, delay, iterations, easing e fill. Os valores explícitos de offset têm de pertencer a [0, 1] e estar por ordem não decrescente. new KeyframeEffect(source) copia a definição do efeito, não o estado de reprodução da animação.

getKeyframes() devolve fotogramas-chave com deslocamentos calculados e setKeyframes() substitui o conjunto. O método herdado updateTiming() altera os parâmetros temporais, enquanto getComputedTiming() disponibiliza o progresso calculado. No exemplo, currentTime = 500 seleciona o ponto intermédio de uma única iteração de 1000 ms sem iniciar a reprodução.

Esta é uma API Window; o Node 24 no repositório não comprova a sua disponibilidade no navegador. Verifique a disponibilidade no ambiente de destino; o exemplo verifica os construtores, mas não comprova o suporte de todas as opções.

Exemplos

(() => {
  if (typeof KeyframeEffect !== "function" || typeof Animation !== "function") {
    throw new Error("Web Animations API required");
  }
  const target = document.createElement("div");
  const effect = new KeyframeEffect(
    target,
    [{ opacity: 0 }, { opacity: 1 }],
    { duration: 1000, easing: "linear" }
  );
  const animation = new Animation(effect, document.timeline);
  animation.currentTime = 500;
  console.log(effect.getKeyframes().length);
  console.log(effect.getComputedTiming().progress);
  animation.cancel();
})();

Resultado

2
0.5

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes