KeyboardEvent.initKeyboardEvent() — Methode · JavaScript-Referenz

Signatur

KeyboardEvent.prototype.initKeyboardEvent(type, bubbles, cancelable, view, key, location, ctrlKey, altKey, shiftKey, metaKey)

Beschreibung

initKeyboardEvent() stammt aus der alten DOM-Level-3-Ereignis-API. Früher erzeugte man ein Ereignis mit document.createEvent("KeyboardEvent") und legte danach mit dieser Methode Typ, Bubbling-Verhalten, gedrückte Taste und Modifikatortasten fest. Anschließend konnte man es mit dispatchEvent() auf einem Element auslösen.

Heute gilt die Methode als veraltet. Der Konstruktor new KeyboardEvent(type, init) ist in allen modernen Browsern verfügbar, lässt sich besser lesen und kann mehr Eigenschaften setzen, zum Beispiel code, repeat oder isComposing. initKeyboardEvent() braucht man deshalb nur noch, wenn man alten Code pflegt oder sehr alte Browser unterstützen muss.

Man muss die Methode vor dem Auslösen aufrufen. Wird sie aufgerufen, während das Ereignis gerade ausgelöst wird, hat sie keine Wirkung. Ein so erzeugtes Ereignis ist immer nicht vertrauenswürdig (isTrusted === false). Es löst also keine Standardaktionen des Browsers aus und fügt zum Beispiel keinen Text in ein Eingabefeld ein.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Ereignistyp, z. B. `"keydown"`, `"keyup"` oder `"keypress"`.
$bubbles	boolean	false	Legt fest, ob das Ereignis im DOM-Baum nach oben weitergereicht wird (Bubbling).
$cancelable	boolean	false	Legt fest, ob sich das Ereignis mit `preventDefault()` abbrechen lässt.
$view	Window \| null	null	Das zugehörige `Window`-Objekt, meistens `window`.
$key	string	""	Wert für `event.key`, z. B. `"Enter"`, `"a"` oder `"Escape"`. In alten WebKit-Versionen stand hier stattdessen ein `keyIdentifier` wie `"U+0041"`.
$location	number	0	Position der Taste auf der Tastatur: `0` = Standard, `1` = links, `2` = rechts, `3` = Ziffernblock (siehe `KeyboardEvent.DOM_KEY_LOCATION_*`).
$ctrlKey	boolean	false	Gibt an, ob die Strg-Taste gedrückt ist.
$altKey	boolean	false	Gibt an, ob die Alt-Taste gedrückt ist.
$shiftKey	boolean	false	Gibt an, ob die Umschalttaste gedrückt ist.
$metaKey	boolean	false	Gibt an, ob die Meta-Taste gedrückt ist (⌘ unter macOS, Windows-Taste unter Windows).

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode verändert das bestehende Ereignisobjekt direkt.

Beispiele

Klassisch: Ereignis erzeugen, initialisieren und auslösen

const input = document.createElement('input');
document.body.append(input);

input.addEventListener('keydown', (e) => {
  console.log(`Taste: ${e.key}, Strg: ${e.ctrlKey}, vertrauenswürdig: ${e.isTrusted}`);
});

const evt = document.createEvent('KeyboardEvent');
evt.initKeyboardEvent(
  'keydown', // type
  true,      // bubbles
  true,      // cancelable
  window,    // view
  'Enter',   // key
  0,         // location (Standard)
  true,      // ctrlKey
  false,     // altKey
  false,     // shiftKey
  false      // metaKey
);

input.dispatchEvent(evt);

Taste: Enter, Strg: true, vertrauenswürdig: false

Moderner Ersatz: der KeyboardEvent-Konstruktor

const input = document.createElement('input');
document.body.append(input);

input.addEventListener('keydown', (e) => {
  console.log(e.key, e.code, e.ctrlKey);
});

const evt = new KeyboardEvent('keydown', {
  key: 'Enter',
  code: 'Enter',
  ctrlKey: true,
  bubbles: true,
  cancelable: true
});

input.dispatchEvent(evt);

Enter Enter true

Hilfsfunktion mit Rückfall für alte Umgebungen

const createKeyEvent = (type, key, opts = {}) => {
  const { ctrlKey = false, altKey = false, shiftKey = false, metaKey = false } = opts;
  try {
    return new KeyboardEvent(type, { key, ctrlKey, altKey, shiftKey, metaKey, bubbles: true, cancelable: true });
  } catch {
    // Rückfall für sehr alte Browser ohne Konstruktor
    const evt = document.createEvent('KeyboardEvent');
    evt.initKeyboardEvent(type, true, true, window, key, 0, ctrlKey, altKey, shiftKey, metaKey);
    return evt;
  }
};

document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') console.log('Dialog schließen');
});

document.dispatchEvent(createKeyEvent('keydown', 'Escape'));

Dialog schließen

// Wichtig · Fallstricke

Veraltet: In neuem Code sollte man immer new KeyboardEvent(type, init) verwenden. Der Konstruktor kann auch code, repeat und isComposing setzen. Diese Eigenschaften lassen sich mit initKeyboardEvent() nicht festlegen.
Unterschiedliche Signaturen: Ältere Chrome- und Safari-Versionen erwarteten als 5. Argument einen keyIdentifier (z. B. \"U+0041\") und ein zusätzliches 11. Argument altGraphKey. Alte Internet-Explorer-Versionen erwarteten statt der einzelnen Modifikator-Booleans einen Text wie \"Control Shift\". Firefox kennt die Methode erst seit Version 93. Davor gab es dort nur das nicht standardisierte initKeyEvent().
keyCode/charCode/which lassen sich mit dieser Methode nicht setzen und bleiben 0. Code, der diese veralteten Eigenschaften abfragt, reagiert also nicht auf die erzeugten Ereignisse.
Keine Standardaktionen: Selbst erzeugte Ereignisse haben isTrusted === false. Sie fügen keinen Text ein, verschieben nicht den Fokus und lösen keine Tastenkürzel des Browsers aus. Sie rufen nur die registrierten Listener auf. Echte Tastatureingaben lassen sich so nicht nachahmen, dafür braucht man Test-Werkzeuge wie WebDriver oder Playwright.
Ein Aufruf während das Ereignis gerade ausgelöst wird, hat keine Wirkung.

Siehe auch

KeyboardEvent.getModifierState() CustomEvent.initCustomEvent() MouseEvent.initMouseEvent() StorageEvent.initStorageEvent() TextEvent.initTextEvent()