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.