CKTIS / JavaScript
L’option `passive` de `EventTarget.addEventListener()`
Avec `passive: true`, un écouteur reçoit l’événement sans pouvoir annuler son action par défaut. Omettre l’option ne revient pas toujours à passer `false`.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
target.addEventListener(type, listener)
target.addEventListener(type, listener, useCapture)
target.addEventListener(type, listener, { passive: true })
target.addEventListener(type, listener, { passive: false })passive est une propriété booléenne facultative de l’objet passé en troisième argument de target.addEventListener(type, listener, options). Si le troisième argument est un booléen seul, il règle uniquement capture, et non passive. Cette API DOM relève de la plateforme web, pas du langage ECMAScript 2024 ; vérifiez sa prise en charge dans l’environnement cible.
Avec passive: true, l’écouteur s’exécute toujours, mais son appel à event.preventDefault() reste sans effet et peut déclencher un avertissement dans la console. La propagation de l’événement ne change pas. Avec passive: false, l’écouteur peut annuler l’action par défaut avec preventDefault(), mais uniquement si event.cancelable vaut true.
Sans indication de passive, le standard DOM prévoit false par défaut, sauf pour les événements wheel, mousewheel, touchstart et touchmove écoutés sur Window, Document, document.documentElement ou document.body : dans ces cas, il prévoit true. La prise en charge de l’option elle-même ne garantit pas l’application de ces valeurs par défaut : les cas où true s’appliquait par défaut ont varié selon le navigateur et sa version, notamment dans Safari. Indiquez explicitement false si vous devez annuler l’action. Utilisez true si vous observez seulement les entrées, pour que le navigateur puisse commencer à défiler sans attendre cet écouteur. L’événement scroll lui-même n’est pas annulable.
Réinscrire l’écouteur sur la même cible avec le même type, la même fonction de rappel et la même valeur de capture ne modifie pas passive. Retirez-le avec removeEventListener() en faisant correspondre le type, la fonction de rappel et capture, puis ajoutez-le de nouveau. passive ne sert ni à identifier l’écouteur lors du retrait ni à gérer sa durée de vie.
Exemples
{
const target = new EventTarget();
const type = "passive-demo";
const listener = (event) => event.preventDefault();
for (const passive of [true, false]) {
target.addEventListener(type, listener, { passive });
const event = new Event(type, { cancelable: true });
const result = target.dispatchEvent(event);
console.log(`passive=${passive}, defaultPrevented=${event.defaultPrevented}, dispatchEvent=${result}`);
target.removeEventListener(type, listener);
}
}Résultat
passive=true, defaultPrevented=false, dispatchEvent=true passive=false, defaultPrevented=true, dispatchEvent=false
Chaque itération distribue un nouvel événement synthétique annulable. `defaultPrevented` indique s’il a été annulé et `dispatchEvent()` renvoie `false` uniquement dans l’itération où l’annulation réussit. Le navigateur peut afficher un avertissement ; l’exemple ne mesure pas les performances du défilement.
Leçons associées
- JavaScript · Leçon 33 · Avancé · Version : 4
- JavaScript · Leçon 36 · Avancé · Version : 4
- JavaScript · Leçon 45 · Avancé · Version : 4