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

CKTIS / JavaScript

Animation.finished — a promise de conclusão da animação

Animation.finished permite aguardar com await pela conclusão de uma animação, tendo em conta um eventual cancelamento.

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

const completedAnimation = await animation.finished;

Animation.finished é uma propriedade só de leitura que devolve uma Promise<Animation>. Quando a animação atinge o estado finished, inclusive através de finish(), a promise pode ser cumprida com o objeto da animação. Não é um valor booleano nem um método.

Quando a animação sai do estado finished, a promise atual só é substituída se já tiver sido cumprida. Se a animação sair desse estado antes de a notificação de conclusão colocada em fila resolver a promise, a mesma promise pode continuar pendente. Volta a ler a propriedade para outra reprodução. Se a animação não estiver no estado idle, cancel() rejeita a promise finished atual com uma DOMException chamada AbortError, desde que a promise ainda esteja pendente. Usa try/catch para tratar essa rejeição. Se a animação já estiver no estado idle, cancel() deixa a promise finished pendente, caso já estivesse pendente. A execução pode assim continuar suspensa em await sem entrar no bloco catch. ready indica que a reprodução ou a pausa está pronta, não que a animação terminou.

Isto faz parte de Web Animations, não de ECMAScript. É necessário suporte do navegador; a presença do Node 24 no repositório não o comprova.

Exemplos

(async () => {
  const element = document.createElement('div');
  element.textContent = 'Animation.finished';
  document.body.append(element);

  const animation = element.animate(
    [{ opacity: 0 }, { opacity: 1 }],
    { duration: 1000, fill: 'forwards' }
  );

  try {
    const completion = animation.finished;
    animation.finish();
    const result = await completion;
    console.log(result === animation);
    console.log(animation.playState);
  } catch (error) {
    console.log(error.name);
  } finally {
    animation.cancel();
    element.remove();
  }
})();

Resultado

true
finished

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