new ToggleEvent() — Methode · JavaScript-Referenz

Signatur

new ToggleEvent(type, options)

Beschreibung

Mit dem Konstruktor ToggleEvent() erzeugst du ein Ereignisobjekt, wie es der Browser selbst bei den Ereignissen beforetoggle und toggle auslöst. Das passiert zum Beispiel, wenn ein Element mit dem Attribut popover ein- oder ausgeblendet wird, wenn ein <details>-Element auf- oder zuklappt oder wenn ein <dialog> geöffnet wird. Das Objekt enthält den alten Zustand (oldState) und den neuen Zustand (newState).

Selbst erzeugen musst du ein ToggleEvent vor allem in Unit-Tests, bei eigenen Web Components mit Auf-/Zuklapp-Logik und wenn du Ereignisse so nachbilden willst, dass bestehende Handler sie wie echte Browser-Ereignisse verarbeiten. Das Objekt löst noch nichts aus. Erst mit dispatchEvent() wird es an ein Element geschickt.

Wichtig: Ein selbst ausgelöstes ToggleEvent ändert nicht den tatsächlichen Zustand des Elements. Ein Popover wird dadurch weder angezeigt noch versteckt. Dafür gibt es showPopover(), hidePopover() und togglePopover(). Das Ereignis informiert nur die registrierten Handler.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, zum Beispiel `"toggle"` oder `"beforetoggle"`. Groß- und Kleinschreibung wird unterschieden.
$options	object	{}	Optionales Objekt. Es erbt alle Felder von `EventInit`: `oldState` (`string`, Standard `""`): vorheriger Zustand, üblich sind `"open"` oder `"closed"`. `newState` (`string`, Standard `""`): neuer Zustand, `"open"` oder `"closed"`. `bubbles` (`boolean`, Standard `false`): Das Ereignis steigt im DOM nach oben. `cancelable` (`boolean`, Standard `false`): `preventDefault()` ist wirksam. `composed` (`boolean`, Standard `false`): Das Ereignis überschreitet Shadow-DOM-Grenzen.

Rückgabewert

Typ

ToggleEvent

Beschreibung

Ein neues ToggleEvent-Objekt. Die Eigenschaften oldState und newState sind nur lesbar und werden aus options übernommen.

Beispiele

ToggleEvent erzeugen und Eigenschaften lesen

const event = new ToggleEvent('toggle', {
  oldState: 'closed',
  newState: 'open'
});

console.log(event.type);      // Ereignisname
console.log(event.oldState);  // alter Zustand
console.log(event.newState);  // neuer Zustand
console.log(event instanceof Event);

toggle closed open true

Handler eines Popovers im Test auslösen

// HTML: <div id="menu" popover>Menü</div>
const menu = document.getElementById('menu');

menu.addEventListener('toggle', (e) => {
  console.log(`Menü ist jetzt: ${e.newState}`);
  document.body.classList.toggle('menu-open', e.newState === 'open');
});

// Ereignis nachbilden – das Popover selbst bleibt unverändert!
menu.dispatchEvent(new ToggleEvent('toggle', {
  oldState: 'closed',
  newState: 'open'
}));

Menü ist jetzt: open

Eigene Web Component mit abbrechbarem beforetoggle

class CollapsiblePanel extends HTMLElement {
  #open = false;

  toggle() {
    const oldState = this.#open ? 'open' : 'closed';
    const newState = this.#open ? 'closed' : 'open';

    const before = new ToggleEvent('beforetoggle', {
      oldState, newState, cancelable: true, bubbles: true, composed: true
    });
    // Abbruch durch einen Handler berücksichtigen
    if (!this.dispatchEvent(before)) return;

    this.#open = !this.#open;
    this.toggleAttribute('open', this.#open);
    this.dispatchEvent(new ToggleEvent('toggle', { oldState, newState, bubbles: true }));
  }
}
customElements.define('collapsible-panel', CollapsiblePanel);

const panel = document.createElement('collapsible-panel');
document.body.append(panel);
panel.addEventListener('toggle', (e) => console.log(e.oldState, '→', e.newState));
panel.toggle();

closed → open

// Wichtig · Fallstricke

Kein Zustandswechsel: dispatchEvent(new ToggleEvent(...)) öffnet oder schließt kein Popover, <details> oder <dialog>. Dafür brauchst du showPopover(), hidePopover(), das Attribut open oder showModal().
isTrusted: Selbst erzeugte Ereignisse haben isTrusted === false. Code, der nur auf echte Nutzeraktionen reagieren soll, kann diesen Wert prüfen.
Nur beforetoggle ist abbrechbar: Beim echten beforetoggle vor dem Öffnen eines Popovers verhindert preventDefault() das Öffnen. Das echte toggle ist nicht abbrechbar und wird asynchron ausgelöst. Mehrere schnelle Wechsel werden dabei zusammengefasst.
Keine Prüfung der Werte: oldState und newState sind frei wählbare Zeichenketten. Der Browser prüft nicht, ob sie \"open\" oder \"closed\" lauten.
Kompatibilität: ToggleEvent gibt es seit 2024 in allen aktuellen Browsern. Ältere Browser lösen bei <details> ein einfaches Event ohne oldState/newState aus. Prüfe die Unterstützung vorab mit typeof ToggleEvent !== 'undefined'. Die neuere Eigenschaft source (das auslösende Element) wird noch nicht überall unterstützt.

Siehe auch

ToggleEvent ToggleEvent.newState ToggleEvent.oldState HTMLElement.togglePopover() EventTarget.dispatchEvent()