CKTIS / JavaScript
cancelAnimationFrame — cancelar uma chamada pendente
cancelAnimationFrame(handle) remove uma chamada pendente registada com requestAnimationFrame(). Usa o identificador devolvido no mesmo contexto; o método não interrompe código que já esteja a ser executado.
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
window.cancelAnimationFrame(handle);cancelAnimationFrame(handle) cancela uma única chamada pendente registada com requestAnimationFrame(). Passa o identificador devolvido handle, e não a própria função registada com requestAnimationFrame() (o callback), e usa o mesmo objeto que fornece a API. O método devolve undefined.
Um identificador que já não esteja entre as chamadas pendentes não altera nada. O cancelamento não interrompe uma chamada que já começou, nem reverte os seus efeitos. Num ciclo que agenda fotogramas seguintes, guarda o identificador mais recente e cancela esse; um identificador anterior não representa toda a animação.
Esta é uma Web API do HTML Living Standard, não uma função ECMAScript. É suportada pelos motores de navegador atuais para Window. A norma também a prevê em contextos DedicatedWorkerGlobalScope suportados; um contexto não suportado lança NotSupportedError. A versão de Node usada num repositório não confirma a disponibilidade desta API.
O exemplo cancela a primeira chamada e, em seguida, verifica o contador numa segunda chamada. O resultado esperado é calls: 0 e result: undefined. Essa verificação só acontece quando o navegador executa a segunda chamada.
Exemplos
(() => {
let calls = 0;
const handle = window.requestAnimationFrame(() => {
calls += 1;
});
const result = window.cancelAnimationFrame(handle);
window.requestAnimationFrame(() => {
console.log(`calls: ${calls}`);
console.log(`result: ${result}`);
});
})();Resultado
calls: 0 result: undefined
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.