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

CKTIS / JavaScript

debounce: executar após uma pausa

`debounce` agrupa várias chamadas rápidas numa só. Na variante apresentada, apenas a última chamada é executada, após uma pausa.

Versão: User-defined debounce helper using web timers; host timer behavior varies

Sintaxe

const debounced = debounce(fn, waitMs);
debounced(...args);
debounced.cancel();

debounce(fn, waitMs) devolve uma função que envolve fn. Passa a função fn, não o resultado de a chamar, e um atraso waitMs não negativo, em milissegundos. Cria a função envolvente uma vez por cada origem de chamadas e reutiliza-a, por exemplo para filtrar resultados quando alguém faz uma pausa a escrever.

Na variante de fim de sequência (trailing edge), cada chamada cancela o temporizador pendente e inicia outro. Quando o temporizador finalmente dispara, fn é executada uma vez com os argumentos e o valor de this da última chamada à função envolvente. Se as chamadas continuarem a chegar com rapidez suficiente, fn pode nunca ser executada. O throttling, por sua vez, limita a frequência de execução mesmo quando as chamadas continuam. A variante de início de sequência (leading edge) executa fn logo na primeira chamada; o exemplo não faz isso.

Cada função envolvente tem o seu temporizador. O método cancel() do exemplo anula uma execução pendente, mas não interrompe trabalho já iniciado. A função envolvente devolve logo undefined, não o resultado posterior de fn. Uma exceção lançada por fn na função de callback do temporizador não se propaga ao código que chamou anteriormente a função envolvente.

A função debounce e o seu método cancel() são definidos no exemplo, não pelo ECMAScript nem por uma norma Web. A indicação de versão diz respeito às normas em que o exemplo se baseia, não à própria função. O exemplo usa setTimeout e clearTimeout, fornecidos pelo ambiente anfitrião. Escolhe um valor de waitMs dentro do intervalo suportado pelos temporizadores desse ambiente: um valor demasiado alto pode ser interpretado como um atraso muito mais curto. O temporizador pode disparar mais tarde do que o pedido. Fora do navegador, verifica se o ambiente de execução disponibiliza temporizadores e como estes funcionam.

Exemplos

(() => {
  function debounce(fn, waitMs) {
    let timer;

    function cancel() {
      if (timer !== undefined) {
        clearTimeout(timer);
        timer = undefined;
      }
    }

    function debounced(...args) {
      cancel();
      timer = setTimeout(() => {
        timer = undefined;
        Reflect.apply(fn, this, args);
      }, waitMs);
    }

    debounced.cancel = cancel;
    return debounced;
  }

  const search = {
    prefix: 'Search: ',
    update: debounce(function (query) {
      console.log(this.prefix + query);
    }, 100),
  };

  search.update('c');
  search.update('ca');
  search.update('cat');
})();

Resultado

Search: cat

Executa todo o código de uma vez na consola do navegador. As três chamadas são síncronas, pelo que só a última leva à apresentação de `Search: cat`. Os 100 ms não garantem um instante exato de execução.

Lições relacionadas

  • JavaScript · Lição 21 · Básico · Versão: 4

Fontes