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

CKTIS / JavaScript

Listeners de eventos de utilização única com `once`

Usa `{ once: true }` para chamar a função no máximo uma vez por registo. O registo é removido antes de a função ser chamada.

Versão: Current web platform; runtime support varies

Sintaxe

target.addEventListener(type, listener);
target.addEventListener(type, listener, { once: true });
target.addEventListener(type, listener, useCapture);

A opção once de EventTarget.addEventListener faz parte do objeto de opções passado como terceiro argumento. Com { once: true }, a função de escuta pode ser chamada no máximo uma vez por aquele registo. Se omitires once, o valor é false. Passar true diretamente como terceiro argumento ativa capture, não once.

A API remove o registo imediatamente antes de chamar a função. Assim, uma chamada aninhada a dispatchEvent() com um novo evento do mesmo tipo não pode executar a função através do mesmo registo. Se a função lançar uma exceção, o registo não é reposto. Se nenhum evento chegar à função, once por si só não remove o registo.

No mesmo alvo, voltar a chamar addEventListener() com o mesmo tipo de evento, a mesma função e o mesmo valor de capture deixa o registo existente inalterado, mesmo que o valor de once seja diferente. Para alterar a opção, usa primeiro removeEventListener() com o tipo, a função e o valor de capture correspondentes e, depois, regista novamente a função.

EventTarget é uma API do DOM disponibilizada pelo ambiente anfitrião, não faz parte de ECMAScript 2024. Confirma se o ambiente de execução pretendido suporta a opção.

Exemplos

{
  const target = new EventTarget();
  let calls = 0;

  target.addEventListener("ready", () => {
    calls += 1;
    if (calls === 1) target.dispatchEvent(new Event("ready"));
  }, { once: true });

  target.dispatchEvent(new Event("ready"));
  target.dispatchEvent(new Event("ready"));
  console.log(`calls: ${calls}`);
}

Resultado

calls: 1

A primeira chamada a `dispatchEvent()` executa a função. Nem a chamada aninhada nem a chamada seguinte a voltam a executar. Saída esperada: `calls: 1`.

Lições relacionadas

  • JavaScript · Lição 39 · Avançado · Versão: 4

Fontes