Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

L’opzione `passive` di `EventTarget.addEventListener()`

Con `passive: true` il listener riceve l’evento, ma non può annullarne l’azione predefinita. Omettere l’opzione non equivale sempre a passare `false`.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

target.addEventListener(type, listener)
target.addEventListener(type, listener, useCapture)
target.addEventListener(type, listener, { passive: true })
target.addEventListener(type, listener, { passive: false })

passive è una proprietà booleana facoltativa dell’oggetto passato come terzo argomento a target.addEventListener(type, listener, options). Se il terzo argomento è un semplice booleano, imposta solo capture, non passive. È un’API DOM della piattaforma web, non una funzionalità del linguaggio ECMAScript 2024; verifica il supporto nell’ambiente di esecuzione di destinazione.

Con passive: true, il listener viene comunque eseguito, ma se chiama event.preventDefault(), la chiamata non ha effetto e può generare un avviso nella console. Questo non modifica la propagazione dell’evento. Con passive: false, il listener può annullare l’azione predefinita con preventDefault(), ma solo se event.cancelable è true.

Se ometti passive, lo standard DOM specifica false come valore predefinito, tranne per gli eventi wheel, mousewheel, touchstart e touchmove quando il listener è registrato su Window, Document, document.documentElement o document.body: in questi casi specifica true. Il supporto dell’opzione non garantisce l’applicazione di questi valori predefiniti: i casi in cui si è usato true come valore predefinito sono variati a seconda del browser e della versione, anche in Safari. Imposta esplicitamente false se devi annullare l’azione. Usa true se vuoi solo osservare l’input, così il browser può iniziare lo scorrimento senza attendere il listener. L’evento scroll in sé non è annullabile.

Registrare di nuovo il listener sullo stesso oggetto con lo stesso tipo, la stessa callback e lo stesso valore di capture non cambia passive. Rimuovilo con removeEventListener() usando il tipo, la callback e il valore di capture corrispondenti, poi aggiungilo di nuovo. passive non serve a individuare il listener da rimuovere e non ne controlla la durata.

Esempi

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

Risultato

passive=true, defaultPrevented=false, dispatchEvent=true
passive=false, defaultPrevented=true, dispatchEvent=false

Ogni iterazione invia un nuovo evento sintetico annullabile. `defaultPrevented` indica se è stato annullato e `dispatchEvent()` restituisce `false` solo nell’iterazione in cui l’annullamento riesce. Il browser può mostrare un avviso; l’esempio non misura le prestazioni dello scorrimento.

Lezioni correlate

  • JavaScript · Lezione 33 · Avanzato · Versione: 4
  • JavaScript · Lezione 36 · Avanzato · Versione: 4
  • JavaScript · Lezione 45 · Avanzato · Versione: 4

Fonti