Signatur
Beschreibung
Mit new KeyboardEvent() erzeugst du ein KeyboardEvent-Objekt, etwa vom Typ keydown, keyup oder (veraltet) keypress. Das Objekt kannst du mit EventTarget.dispatchEvent() auf einem Element, auf document oder auf window auslösen. Alle dort registrierten Listener werden dann so aufgerufen, als hätte jemand eine Taste gedrückt.
Typische Einsatzzwecke sind automatisierte Tests (Unit- und Integrationstests von Tastenkürzeln), das Nachbilden von Tastaturbedienung in eigenen Komponenten (z. B. eine Bildschirmtastatur, die Tastenkürzel auslöst) und das Weiterreichen von Ereignissen zwischen Komponenten.
Wichtig: Ein synthetisches Ereignis ist nicht vertrauenswürdig (event.isTrusted === false). Es löst keine Standardaktionen des Browsers aus. Es wird also kein Text in ein <input> eingefügt, der Fokus wandert bei Tab nicht weiter und Browser-Kürzel wie Strg+C werden nicht ausgeführt. Es werden nur deine eigenen JavaScript-Listener aufgerufen.
Das Ereignis wird standardmäßig nicht im DOM nach oben weitergereicht (kein Bubbling) und ist nicht abbrechbar. Wenn Listener auf übergeordneten Elementen (Event-Delegation) reagieren sollen, musst du bubbles: true setzen. Soll preventDefault() wirken, brauchst du cancelable: true.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, z. B. "keydown", "keyup" oder "keypress" (veraltet). Groß- und Kleinschreibung zählt. |
|
| $options | KeyboardEventInit | {} | Optionales Objekt zum Initialisieren. Die wichtigsten Felder sind:
|
Rückgabewert
KeyboardEvent-Objekt. Es wird noch nicht ausgelöst, das geschieht erst mit dispatchEvent().Beispiele
Einfaches keydown-Ereignis erzeugen und untersuchen
const event = new KeyboardEvent('keydown', {
key: 'Enter',
code: 'Enter',
bubbles: true,
cancelable: true
});
console.log(event.type, event.key, event.code);
console.log('Vertrauenswürdig:', event.isTrusted);Tastenkürzel Strg+S im Test auslösen
// Anwendungscode: globales Speichern-Kürzel
document.addEventListener('keydown', (e) => {
if (e.ctrlKey && e.key === 's') {
e.preventDefault();
console.log('Dokument wird gespeichert …');
}
});
// Test: Kürzel synthetisch auslösen
const shortcut = new KeyboardEvent('keydown', {
key: 's',
code: 'KeyS',
ctrlKey: true,
bubbles: true,
cancelable: true
});
const notCancelled = document.dispatchEvent(shortcut);
console.log('Standardaktion erlaubt:', notCancelled);Pfeiltasten einer eigenen Listbox per Schaltfläche steuern
const list = document.createElement('ul');
list.tabIndex = 0;
let index = 0;
list.addEventListener('keydown', (e) => {
if (e.key === 'ArrowDown') index++;
if (e.key === 'ArrowUp') index = Math.max(0, index - 1);
console.log('Aktiver Eintrag:', index);
});
document.body.append(list);
// z. B. von einer Bildschirm-Schaltfläche aus aufgerufen
const pressKey = (key) =>
list.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
pressKey('ArrowDown');
pressKey('ArrowDown');
pressKey('ArrowUp');// Wichtig · Fallstricke
- Keine Standardaktion: Synthetische Tastatur-Ereignisse fügen keinen Text in Eingabefelder ein, verschieben keinen Fokus und lösen keine Browser-Kürzel aus. Um Texteingaben nachzubilden, setzt du
input.valuedirekt und löst danach eininput-Ereignis aus. Für echte Tastatureingaben nimmst du Testwerkzeuge wie Playwright, Puppeteer oder WebDriver. bubblesnicht vergessen: Ohnebubbles: trueerreicht das Ereignis keine Listener auf übergeordneten Elementen oder aufdocument. Für Shadow-DOM-Grenzen brauchst du zusätzlichcomposed: true.keyCode/whichsind veraltet: In einigen Browsern werden diese Werte überoptionsnicht zuverlässig gesetzt und bleiben0. Prüfe in Listenern besserkeyodercode. Wenn AltcodekeyCodeerwartet, kannst du die Eigenschaft notfalls mitObject.defineProperty()überschreiben.keypressist veraltet: Verwende stattdessenkeydown.isTrustedist immerfalse: Manche Funktionen verlangen eine echte Benutzeraktion, z. B. Vollbild, Pop-ups, Zwischenablage oder Autoplay. Mit synthetischen Ereignissen lassen sie sich deshalb nicht auslösen.- Veraltete Methode: Die alte Methode
initKeyboardEvent()ist veraltet und sollte nicht mehr verwendet werden. - Kompatibilität: Der Konstruktor wird von allen modernen Browsern unterstützt. Internet Explorer unterstützt ihn nicht. In Node.js gibt es ihn nur über DOM-Nachbildungen wie jsdom.