new UIEvent() — Methode · JavaScript-Referenz

Signatur

new UIEvent(type, options)

Beschreibung

Der Konstruktor new UIEvent() erzeugt ein Ereignis vom Typ UIEvent. Dieses Interface erbt von Event und ist die Basis für MouseEvent, KeyboardEvent, FocusEvent, InputEvent, WheelEvent und TouchEvent. Gegenüber Event kommen die Eigenschaften view (das zugehörige Window) und detail (eine vom Ereignistyp abhängige Zahl) hinzu.

Man verwendet den Konstruktor vor allem in Tests oder für eigene Komponenten, die ein UI-nahes Ereignis wie resize, scroll, load oder select simulieren wollen. Das erzeugte Objekt wird mit EventTarget.dispatchEvent() an ein Element, das document oder das window geschickt.

Wichtig: Künstlich erzeugte Ereignisse sind nicht vertrauenswürdig. event.isTrusted ist dann false, und der Browser führt keine Standardaktion aus. Ein gesendetes UIEvent scrollt also nichts und ändert auch keine Fenstergröße, es ruft nur die registrierten Listener auf. Für Maus- oder Tastaturereignisse sollten Sie die passenderen Konstruktoren MouseEvent() bzw. KeyboardEvent() nehmen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"resize"`, `"scroll"` oder ein eigener Name. Groß- und Kleinschreibung wird beachtet.
$options	UIEventInit	{}	Optionales Objekt. Es enthält alle Felder von `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standard `false`) sowie `view`, `detail` und das veraltete `which`.
$options.view	Window \| null	null	Das `Window`, mit dem das Ereignis verbunden ist, meist `window`.
$options.detail	number	0	Zusatzinformation, deren Bedeutung vom Ereignistyp abhängt. Bei Klicks ist das z. B. die Anzahl der Klicks.
$options.bubbles	boolean	false	Legt fest, ob das Ereignis im DOM nach oben weitergereicht wird.
$options.cancelable	boolean	false	Legt fest, ob `preventDefault()` Wirkung hat.
$options.composed	boolean	false	Legt fest, ob das Ereignis die Grenze eines Shadow DOM überschreitet.

Rückgabewert

Typ

UIEvent

Beschreibung

Ein neues UIEvent-Objekt. Es kann mit dispatchEvent() ausgelöst werden.

Beispiele

UIEvent erzeugen und Eigenschaften lesen

const evt = new UIEvent('select', {
  bubbles: true,
  cancelable: false,
  view: window,
  detail: 1
});

console.log(evt.type);      // Ereignisname
console.log(evt.detail);    // Zusatzwert
console.log(evt.view === window);
console.log(evt.isTrusted); // künstlich erzeugt
console.log(evt instanceof Event);

select 1 true false true

resize-Ereignis in einem Test simulieren

const updateLayout = () => {
  console.log(`Layout neu berechnet für Breite ${window.innerWidth}px`);
};

window.addEventListener('resize', updateLayout);

// Resize auslösen, ohne die Fenstergröße zu ändern
window.dispatchEvent(new UIEvent('resize', { view: window }));

window.removeEventListener('resize', updateLayout);

Layout neu berechnet für Breite 1280px (Wert hängt vom Fenster ab)

Eigenes UI-Ereignis mit Bubbling in einer Komponente

const list = document.createElement('ul');
const item = document.createElement('li');
item.textContent = 'Eintrag 1';
list.append(item);
document.body.append(list);

// Der Listener auf der Liste empfängt Ereignisse der Kinder
list.addEventListener('itemactivate', (e) => {
  console.log(`Aktiviert: ${e.target.textContent}, detail=${e.detail}`);
});

item.addEventListener('dblclick', () => {
  item.dispatchEvent(new UIEvent('itemactivate', {
    bubbles: true,
    view: window,
    detail: 2
  }));
});

// Zum Testen direkt auslösen
item.dispatchEvent(new UIEvent('itemactivate', { bubbles: true, view: window, detail: 2 }));

Aktiviert: Eintrag 1, detail=2

// Wichtig · Fallstricke

Keine Standardaktion: Mit dem Konstruktor erzeugte Ereignisse haben isTrusted === false. Der Browser scrollt nicht, fokussiert nichts und öffnet keine Popups. Aktionen, die eine echte Benutzeraktivierung verlangen (Vollbild, Zwischenablage, window.open), lassen sich damit nicht auslösen.
Standardwert von bubbles: Er ist false. Ohne bubbles: true erreicht das Ereignis keine Listener auf Elternelementen.
Wert von view: Er muss ein Window oder null sein, sonst wirft der Konstruktor einen TypeError.
Veraltete API: document.createEvent('UIEvent') zusammen mit initUIEvent() gilt als veraltet. Nutzen Sie stattdessen den Konstruktor.
Für eigene Daten ist CustomEvent mit einer beliebigen detail-Nutzlast meist besser geeignet, denn bei UIEvent ist detail immer eine Zahl.
Kompatibilität: Alle modernen Browser unterstützen den Konstruktor, der Internet Explorer nicht. In Node.js gibt es UIEvent nicht nativ, dort nur über jsdom und ähnliche Bibliotheken.

Siehe auch

new Event() new PushEvent() new BlobEvent() new Comment() new DragEvent()