UIEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface UIEvent extends Event

Beschreibung

UIEvent erweitert Event um Informationen, die mit der Benutzeroberfläche zusammenhängen. Vor allem ist es die gemeinsame Basisklasse vieler spezialisierter Ereignistypen: MouseEvent, KeyboardEvent, FocusEvent, InputEvent, WheelEvent, TouchEvent, PointerEvent (über MouseEvent) und CompositionEvent.

Wichtige Eigenschaften sind:

view – das WindowProxy, in dem das Ereignis entstanden ist (oder null).
detail – eine Zahl mit ereignisabhängiger Zusatzinformation, z. B. die Klickanzahl bei click/dblclick (1, 2, 3 …).
sourceCapabilities – (experimentell, nur Chromium) ein InputDeviceCapabilities-Objekt, das angibt, ob das auslösende Gerät Touch-Events erzeugt.

Direkt als UIEvent (ohne Unterklasse) werden im Browser heute vor allem load/unload auf dem Fenster sowie teils resize und scroll ausgelöst. Selbst erzeugen kann man UIEvent-Objekte über den Konstruktor new UIEvent(type, options), etwa für Tests oder eigene UI-Komponenten.

In der Praxis prüft man mit event instanceof UIEvent, ob ein Ereignis aus einer Benutzerinteraktion stammt, oder nutzt detail, um Mehrfachklicks zu unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"resize"` oder ein eigener Name wie `"panel-open"`.
$options	UIEventInit	{}	Optionales Objekt. Enthält alle Felder von `EventInit` (`bubbles`, `cancelable`, `composed`) sowie `view` (`Window \| null`, Standard `null`) und `detail` (`number`, Standard `0`).

Rückgabewert

Typ

UIEvent

Beschreibung

Beim Konstruktoraufruf ein neues UIEvent-Objekt; es wird erst durch dispatchEvent() tatsächlich ausgelöst.

Beispiele

UIEvent erzeugen und auslösen

const panel = document.createElement('div');
document.body.append(panel);

panel.addEventListener('panel-open', (event) => {
  console.log(event instanceof UIEvent); // true
  console.log(event.detail, event.view === window);
});

const evt = new UIEvent('panel-open', {
  bubbles: true,
  cancelable: true,
  view: window,
  detail: 1
});
panel.dispatchEvent(evt);

true 1 true

Einfach-, Doppel- und Dreifachklick über detail unterscheiden

const text = document.querySelector('p');

text.addEventListener('click', (event) => {
  // MouseEvent erbt detail von UIEvent
  switch (event.detail) {
    case 1: console.log('Einfachklick'); break;
    case 2: console.log('Doppelklick – Wort markieren'); break;
    case 3: console.log('Dreifachklick – Absatz markieren'); break;
    default: console.log(`Klick Nr. ${event.detail}`);
  }
});

Einfachklick Doppelklick – Wort markieren Dreifachklick – Absatz markieren

Vererbungskette prüfen

const handler = (event) => {
  console.log(event.type,
    'UIEvent:', event instanceof UIEvent,
    'MouseEvent:', event instanceof MouseEvent,
    'KeyboardEvent:', event instanceof KeyboardEvent);
};

document.addEventListener('click', handler);
document.addEventListener('keydown', handler);

// Später wieder entfernen
setTimeout(() => {
  document.removeEventListener('click', handler);
  document.removeEventListener('keydown', handler);
}, 10000);

click UIEvent: true MouseEvent: true KeyboardEvent: false keydown UIEvent: true MouseEvent: false KeyboardEvent: true

// Wichtig · Fallstricke

Per dispatchEvent() erzeugte Ereignisse haben event.isTrusted === false. Browser lösen dadurch keine Standardaktionen aus (z. B. öffnet ein synthetischer Klick keine Popups mit Nutzeraktivierung).
Die Eigenschaft which sowie die Methode initUIEvent() sind veraltet. Stattdessen den Konstruktor new UIEvent() bzw. KeyboardEvent.key und MouseEvent.button verwenden.
Bei pointerdown/pointerup ist detail laut Spezifikation 0; die Klickanzahl steht zuverlässig nur bei click, dblclick, mousedown und mouseup zur Verfügung.
sourceCapabilities ist experimentell und nur in Chromium-Browsern verfügbar – vor Nutzung auf Existenz prüfen.
Für eigene Ereignisse mit strukturierten Daten ist CustomEvent meist die bessere Wahl, da UIEvent.detail nur eine Zahl sein darf (Werte werden zu long konvertiert).
Kompatibilität: Konstruktor in allen modernen Browsern verfügbar; im Internet Explorer nicht (dort nur document.createEvent('UIEvent')).

Siehe auch

Event MouseEvent KeyboardEvent FocusEvent InputEvent CustomEvent EventTarget.dispatchEvent() EventTarget.addEventListener()