KeyboardEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface KeyboardEvent extends UIEvent

Beschreibung

KeyboardEvent-Objekte beschreiben eine Benutzerinteraktion mit der Tastatur. Jedes Ereignis steht für genau eine Interaktion zwischen dem Benutzer und einer Taste bzw. einer Kombination aus Taste und Modifikatortasten wie Umschalt, Strg, Alt oder Meta. Die Art der Interaktion steht in der Eigenschaft type: keydown (Taste gedrückt, wiederholt sich bei gehaltener Taste) oder keyup (Taste losgelassen). Das veraltete keypress sollte man nicht mehr verwenden.

Die wichtigsten Eigenschaften sind:

key: der logische Wert der Taste unter Berücksichtigung von Tastaturlayout und Modifikatoren, z. B. "a", "A", "Enter", "ArrowLeft", "Escape".
code: die physische Taste unabhängig vom Layout, z. B. "KeyA", "Digit1", "Space". Ideal für Spielesteuerung (WASD).
ctrlKey, shiftKey, altKey, metaKey: Booleans für gehaltene Modifikatortasten.
repeat: true, wenn das Ereignis durch automatisches Wiederholen einer gehaltenen Taste entsteht.
isComposing: true während einer IME-Eingabe (z. B. Japanisch, Chinesisch).
location: Position der Taste (Standard, links/rechts, Ziffernblock).
Methode getModifierState(key): fragt Zustände wie "CapsLock" oder "NumLock" ab.

Man nutzt KeyboardEvent für Tastenkürzel, Barrierefreiheit (Tastaturnavigation in eigenen Widgets), Spielesteuerungen und das Abfangen bestimmter Eingaben. Für die reine Überwachung von Texteingaben ist dagegen das input-Ereignis besser geeignet, da es auch Einfügen, Autovervollständigung und Spracheingabe erfasst.

Mit dem Konstruktor new KeyboardEvent(type, options) lassen sich Ereignisse synthetisch erzeugen und per dispatchEvent() auslösen – etwa in Tests. Solche Ereignisse sind jedoch nicht vertrauenswürdig (isTrusted === false) und lösen keine Standardaktionen des Browsers aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, typischerweise `"keydown"` oder `"keyup"` (nur beim Konstruktor `new KeyboardEvent()`).
$options	KeyboardEventInit	{}	Optionales Objekt mit `key`, `code`, `location`, `ctrlKey`, `shiftKey`, `altKey`, `metaKey`, `repeat`, `isComposing` sowie den Event-Optionen `bubbles`, `cancelable` und `composed`.

Rückgabewert

Typ

KeyboardEvent

Beschreibung

Beim Konstruktor-Aufruf ein neues KeyboardEvent-Objekt; in Event-Handlern wird das Objekt vom Browser als Argument übergeben.

Beispiele

Tastenkürzel Strg/Cmd + S abfangen

document.addEventListener('keydown', (event) => {
  // metaKey für macOS (Cmd), ctrlKey für Windows/Linux
  const modifier = event.ctrlKey || event.metaKey;
  if (modifier && event.key.toLowerCase() === 's') {
    event.preventDefault(); // Browser-Dialog "Seite speichern" verhindern
    console.log('Dokument wird gespeichert …');
  }
});

Dokument wird gespeichert …

Spielsteuerung mit layoutunabhängigem code (WASD)

const pressed = new Set();

const onDown = (event) => {
  if (event.repeat) return; // gehaltene Taste ignorieren
  pressed.add(event.code);
  console.log('Aktiv:', [...pressed].join(', '));
};
const onUp = (event) => pressed.delete(event.code);

window.addEventListener('keydown', onDown);
window.addEventListener('keyup', onUp);

// Später, z. B. beim Verlassen des Spiels:
const stopGame = () => {
  window.removeEventListener('keydown', onDown);
  window.removeEventListener('keyup', onUp);
};

Aktiv: KeyW Aktiv: KeyW, KeyD

Escape schließt Dialog, IME-Eingaben berücksichtigen

const input = document.querySelector('#search');

input.onkeydown = (event) => {
  if (event.isComposing) return; // IME-Komposition nicht stören
  if (event.key === 'Enter') {
    console.log('Suche nach:', input.value);
  } else if (event.key === 'Escape') {
    input.value = '';
    input.blur();
  }
};

Suche nach: fetch api

Synthetisches Ereignis im Test auslösen

const target = document.body;
target.addEventListener('keydown', (e) => {
  console.log(e.key, e.code, e.shiftKey, e.isTrusted);
});

const event = new KeyboardEvent('keydown', {
  key: 'A',
  code: 'KeyA',
  shiftKey: true,
  bubbles: true,
  cancelable: true
});
target.dispatchEvent(event);

A KeyA true false

// Wichtig · Fallstricke

Veraltet: keyCode, which und charCode sowie das Ereignis keypress sind deprecated. Verwende stattdessen key bzw. code.
key vs. code: key hängt vom Layout ab (auf deutscher QWERTZ-Tastatur liefert die Taste mit code === \"KeyY\" den key \"z\"). Für Kürzel, die Buchstaben meinen, key nutzen; für positionsbezogene Steuerung code.
Groß-/Kleinschreibung: Mit gedrückter Umschalttaste oder CapsLock liefert key Großbuchstaben – vergleiche daher mit key.toLowerCase().
IME: Während einer Komposition feuert keydown mit isComposing === true (in manchen Browsern key === \"Process\"). Enter bestätigt dann oft nur die Komposition – vorher prüfen.
Fokus: Ereignisse gehen an das fokussierte Element. Nicht fokussierbare Elemente (z. B. <div>) brauchen tabindex, um Tastaturereignisse zu empfangen.
Nicht abfangbar: Einige Systemkürzel (z. B. Strg+W, Strg+T, Alt+Tab) können nicht per preventDefault() blockiert werden.
Mobilgeräte: Virtuelle Tastaturen liefern oft key === \"Unidentified\" oder keyCode 229; für Texteingaben besser input/beforeinput verwenden.
Sicherheit: Synthetische Ereignisse (isTrusted === false) lösen keine nativen Aktionen aus, etwa kein Einfügen von Text in Eingabefelder.

Siehe auch

Event ClipboardEvent ErrorEvent Keyboard CommandEvent