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

CKTIS / JavaScript

Debounce e throttle: controlar chamadas de funções

Debounce adia a execução até uma série de chamadas acalmar, enquanto throttle limita a frequência de execução durante essa série. Distingue as variantes leading e trailing: determinam se é mantida a primeira chamada, a última ou ambas.

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 debounced = debounce(fn, wait);
const throttled = throttle(fn, wait);
debounced(...args);
throttled(...args);

debounce / throttle são padrões de controlo de chamadas, não funções integradas no ECMAScript. O debounce trailing executa uma função após um período de inatividade de wait: cada nova chamada cancela o temporizador anterior e agenda outro. Mantém os argumentos mais recentes e this. É útil, por exemplo, para iniciar uma pesquisa após uma pausa na escrita; chamadas contínuas podem adiar a execução indefinidamente.

Throttle limita a frequência de execução mesmo quando continuam a chegar chamadas. A variante leading do exemplo executa imediatamente a primeira chamada e, depois, descarta as seguintes até um temporizador a desbloquear. Não executa a última chamada descartada. Pode servir para limitar a frequência de tratamento do deslocamento. Leading significa execução no início de uma janela; trailing significa execução adiada para o fim. As implementações podem oferecer ambas as variantes, pelo que deves definir explicitamente estas regras.

O exemplo usa sintaxe ECMAScript 2015 e setTimeout() e clearTimeout() do navegador, especificados por HTML e não pelo ECMAScript. Os temporizadores estão disponíveis em contextos window e worker; o suporte no Node 24 não comprova o suporte da API do navegador. No navegador, setTimeout() converte o atraso num inteiro de 32 bits com sinal. Por exemplo, 2147483648 ms torna-se um valor negativo, que é tratado como zero. Um atraso não garante uma hora exata de execução: outras tarefas podem adiá-la e os temporizadores suficientemente aninhados têm um mínimo de 4 ms. Não é um mecanismo de tempo real.

Cria o wrapper uma vez e reutiliza-o; recriá-lo para cada evento faz perder o estado partilhado. O exemplo pressupõe um fn válido e um valor inteiro de wait em milissegundos que satisfaça 0 <= wait && wait <= 2147483647. Não encaminha o valor devolvido pela função e não disponibiliza cancel(), flush() ou maxWait. Em produção, prevê o cancelamento do trabalho pendente ao remover um componente. Cancelar um temporizador não interrompe um pedido já iniciado nem protege contra respostas desatualizadas.

Exemplos

function debounce(fn, wait) {
  let timer;
  return function (...args) {
    clearTimeout(timer);
    timer = setTimeout(() => {
      timer = undefined;
      fn.apply(this, args);
    }, wait);
  };
}

function throttle(fn, wait) {
  let blocked = false;
  return function (...args) {
    if (blocked) return;
    blocked = true;
    setTimeout(() => { blocked = false; }, wait);
    fn.apply(this, args);
  };
}

const debounced = debounce(value => console.log('debounce:', value), 50);
const throttled = throttle(value => console.log('throttle:', value), 50);

for (const value of ['A', 'B', 'C']) {
  debounced(value);
  throttled(value);
}

Resultado

throttle: A
debounce: C

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