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

CKTIS / JavaScript

Animation.cancel(): cancelar uma animação

Animation.cancel() interrompe uma animação e remove o seu efeito no elemento, em vez de a manter no fotograma atual.

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

animation.cancel();

animation.cancel() é um método de Web Animations, não do próprio ECMAScript. Não recebe argumentos e devolve undefined. Define playState como idle e currentTime e startTime como null.

Remove o efeito da animação, incluindo com fill: 'both'; não guarda um fotograma nos estilos. Ao contrário de pause(), não preserva a posição atual; ao contrário de finish(), não avança até ao fim. O objeto pode ser reiniciado com play().

Se a animação não estiver no estado idle, o método substitui a promessa finished existente por uma nova e coloca um evento cancel na fila. A promessa anterior só é rejeitada com AbortError se ainda estiver pendente. Se já tiver sido cumprida, mantém-se nesse estado. Adiciona o tratamento da rejeição antes de cancelar. O exemplo requer um navegador; o Node 24 não comprova o suporte desta API.

Exemplos

(async () => {
  const box = document.createElement('div');
  document.body.append(box);
  const animation = box.animate(
    [{ opacity: 0 }, { opacity: 1 }],
    { duration: 1000, fill: 'both' }
  );
  const outcome = animation.finished.catch(error => error.name);
  animation.cancel();
  console.log(animation.playState);
  console.log(animation.currentTime === null);
  console.log(animation.startTime === null);
  console.log(await outcome);
  box.remove();
})();

Resultado

idle
true
true
AbortError

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