Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Écouteurs d’événements à usage unique avec `once`

Utilisez `{ once: true }` pour appeler la fonction de rappel au plus une fois par inscription. L’inscription est supprimée avant l’appel de la fonction.

Version : Current web platform; runtime support varies

Syntaxe

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

L’option once de EventTarget.addEventListener se place dans l’objet d’options passé en troisième argument. Avec { once: true }, la fonction de rappel est appelée au plus une fois pour cette inscription. Si once est omis, sa valeur est false. Passer directement true en troisième argument règle capture, pas once.

L’API supprime l’inscription juste avant d’appeler la fonction de rappel. Un appel imbriqué à dispatchEvent() avec un nouvel événement du même type ne peut donc pas rappeler cette fonction via la même inscription. Une exception levée ne rétablit pas l’inscription. Si aucun événement n’atteint la fonction de rappel, once ne supprime pas à lui seul l’inscription.

Sur la même cible, rappeler addEventListener() avec le même type d’événement, la même fonction de rappel et la même valeur de capture laisse l’inscription existante inchangée, même si once diffère. Pour changer ce réglage, passez d’abord le type, la fonction et la valeur de capture correspondants à removeEventListener(), puis inscrivez de nouveau la fonction.

EventTarget est une API du DOM fournie par l’environnement hôte, et non une fonctionnalité d’ECMAScript 2024. Vérifiez que l’environnement d’exécution visé prend en charge cette option.

Exemples

{
  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}`);
}

Résultat

calls: 1

Le premier appel à `dispatchEvent()` exécute la fonction de rappel. Ni l’appel imbriqué ni l’appel suivant ne l’exécute de nouveau. Affichage attendu : `calls: 1`.

Leçons associées

  • JavaScript · Leçon 39 · Avancé · Version : 4

Sources