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

CKTIS / JavaScript

requestAnimationFrame — atualizações antes da apresentação

requestAnimationFrame solicita uma função de retorno de chamada executada uma única vez durante uma atualização da apresentação. Permite animar com base no tempo decorrido, em vez de pressupor um número fixo de fotogramas por segundo.

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 handle = window.requestAnimationFrame((timestamp) => { /* update visual state */ });
window.cancelAnimationFrame(handle);

window.requestAnimationFrame(callback) regista uma função de retorno de chamada executada uma única vez como parte de uma atualização da apresentação, antes de a imagem ser apresentada. Devolve um identificador numérico do pedido, não o resultado da função. Para continuar, é necessário pedir explicitamente outro fotograma; window.cancelAnimationFrame(handle) remove uma função de retorno de chamada pendente.

O argumento timestamp é uma marca temporal de alta resolução, em milissegundos e relativa à origem temporal do ambiente; não é uma data de calendário nem a duração de um fotograma. Calcula o tempo decorrido subtraindo marcas temporais. As funções de retorno de chamada invocadas no mesmo lote para o mesmo destino recebem a mesma marca temporal.

Não pressuponhas 60 fotogramas por segundo nem um atraso fixo. A frequência depende das oportunidades de apresentação; documentos invisíveis podem não receber atualizações. Mantém a função de retorno de chamada curta, pois trabalho demorado atrasa a apresentação. Alterações de posição baseadas no tempo evitam que a velocidade do movimento dependa do número de fotogramas.

Esta é uma API do padrão HTML, não uma funcionalidade de uma edição específica do ECMAScript. Os motores atuais dos navegadores suportam-na para Window; a presença do Node 24 num repositório não comprova esse suporte. O exemplo requer uma página visível com document.body existente. Anima um ponto e, na última execução da função de retorno de chamada, define o seu deslocamento como 100 píxeis, escreve done: 100px na consola e remove o ponto antes de o navegador o poder desenhar nessa posição. A duração prevista do movimento é de 1000 ms, mas a conclusão efetiva pode ocorrer mais tarde.

Exemplos

(() => {
  const dot = document.createElement('div');
  dot.textContent = '●';
  document.body.append(dot);
  let start;

  function frame(timestamp) {
    if (start === undefined) start = timestamp;
    const progress = Math.min((timestamp - start) / 1000, 1);
    dot.style.transform = `translateX(${100 * progress}px)`;

    if (progress < 1) {
      window.requestAnimationFrame(frame);
    } else {
      console.log('done: 100px');
      dot.remove();
    }
  }

  window.requestAnimationFrame(frame);
})();

Resultado

done: 100px

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