Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

CustomEvent: dati con detail e fase di risalita con bubbles

Usa `detail` per trasmettere dati in un evento personalizzato e `bubbles` per consentire ai listener degli antenati non registrati per la cattura di riceverlo dopo la fase sul bersaglio.

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

Sintassi

new CustomEvent(type)
new CustomEvent(type, { detail: payload, bubbles: true })
event.detail
event.bubbles
target.dispatchEvent(event)

new CustomEvent(type, options) crea un evento DOM. type è il nome dell’evento e distingue maiuscole e minuscole; options è facoltativo. La creazione non invia l’evento: chiama target.dispatchEvent(event) per invocare i listener interessati in modo sincrono, prima che la chiamata termini.

detail e bubbles hanno funzioni indipendenti. detail contiene i dati e vale null per impostazione predefinita. I listener li leggono attraverso la proprietà di sola lettura event.detail. Puoi passare un valore primitivo o un oggetto. L’oggetto non viene né copiato né congelato: i listener ricevono lo stesso oggetto e possono cambiarne le proprietà modificabili.

L’opzione bubbles vale false per impostazione predefinita. bubbles: true abilita la fase di risalita: dopo la fase sul bersaglio, l’evento può raggiungere i listener sugli antenati, a meno che la propagazione non sia stata interrotta. La proprietà di sola lettura event.bubbles è ereditata da Event. Il valore false non disattiva i listener sul bersaglio né quelli di cattura (capture: true) sugli antenati.

stopPropagation() interrompe l’ulteriore propagazione; separatamente, cancelable stabilisce se preventDefault() può annullare l’evento. Per consentire a un evento inviato all’interno di un albero shadow DOM di risalire oltre tale albero, imposta anche composed: true (valore predefinito: false). Un evento inviato da uno script ha isTrusted uguale a false: non usarlo come prova di un’azione dell’utente. CustomEvent è un’API del DOM, non fa parte di ECMAScript 2024. La disponibilità dipende dall’ambiente di esecuzione.

Esempi

{
  const hasDOM = typeof document !== "undefined";
  const parent = hasDOM ? document.createElement("div") : new EventTarget();
  const child = hasDOM ? document.createElement("div") : new EventTarget();
  if (hasDOM) parent.appendChild(child);

  const type = "score-change";
  const lines = [];
  child.addEventListener(type, (event) => {
    lines.push(`child: ${event.detail.score}, bubbles=${event.bubbles}`);
  });
  parent.addEventListener(type, (event) => {
    lines.push(`parent: ${event.detail.score}, bubbles=${event.bubbles}`);
  });

  function dispatchFromChild(event) {
    child.dispatchEvent(event);
    // Without a DOM tree, model just the bubbling step to one parent.
    if (!hasDOM && event.bubbles && !event.cancelBubble) {
      parent.dispatchEvent(event);
    }
  }

  dispatchFromChild(new CustomEvent(type, { detail: { score: 1 } }));
  dispatchFromChild(new CustomEvent(type, {
    detail: { score: 2 },
    bubbles: true,
  }));

  console.log(lines.join("\n"));
}

Risultato

child: 1, bubbles=false
child: 2, bubbles=true
parent: 2, bubbles=true

Esegui il blocco in Node.js 24 o nella console del browser. Nel browser gli elementi non sono collegati al documento, ma `child` ha comunque un genitore e si applica la risalita nativa del DOM. In Node.js il codice inoltra esplicitamente l’evento a `parent` per simulare quel singolo passaggio della risalita. In entrambi gli ambienti, `child` riceve entrambi gli eventi; il listener su `parent` non registrato per la cattura riceve solo il secondo, con `score: 2`.

Lezioni correlate

  • JavaScript · Lezione 43 · Avanzato · Versione: 4

Fonti