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

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.

Fontes