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