Signatur
Beschreibung
Die Eigenschaft key eines KeyboardEvent liefert den logischen Wert der gedrückten Taste als Zeichenkette. Bei druckbaren Zeichen ist das das erzeugte Zeichen selbst, also "a", "A" (mit Shift), "ß", "@" oder " " für die Leertaste. Bei Sondertasten steht dort ein festgelegter Name wie "Enter", "Escape", "ArrowUp", "Backspace", "Tab", "Shift" oder "F5".
Anders als KeyboardEvent.code, das die physische Position der Taste angibt (z. B. "KeyZ", egal ob auf einer QWERTZ- oder QWERTY-Tastatur), berücksichtigt key das Tastaturlayout und den Zustand der Modifikatortasten. Auf einer deutschen Tastatur liefert die Taste rechts neben „T“ deshalb key === "z" und code === "KeyY".
Nimm key, wenn es auf die Bedeutung der Eingabe ankommt: Tastenkürzel wie Strg+S, Formularsteuerung mit Enter/Escape oder Navigation mit den Pfeiltasten. Für Spielsteuerungen, bei denen die Tastenposition zählt (WASD), ist code meist die bessere Wahl. Die veralteten Eigenschaften keyCode, which und charCode ersetzt key vollständig.
Lässt sich eine Taste keinem Wert zuordnen, ist der Wert "Unidentified". Während einer IME-Eingabe (z. B. bei Japanisch oder Chinesisch) meldet der Browser häufig "Process".
Rückgabewert
"a", "€", " "), ein benannter Tastenwert (z. B. "Enter", "ArrowLeft", "Control"), "Dead" für Tottasten oder "Unidentified".Beispiele
Gedrückte Taste protokollieren
document.addEventListener('keydown', (event) => {
console.log(`key: "${event.key}" | code: "${event.code}"`);
});
// Auf deutscher Tastatur Shift + Taste rechts neben T drückenEnter und Escape in einem Eingabefeld behandeln
const input = document.querySelector('#search');
const onKey = (event) => {
switch (event.key) {
case 'Enter':
console.log('Suche nach:', input.value);
break;
case 'Escape':
input.value = '';
input.blur();
break;
}
};
input.addEventListener('keydown', onKey);
// Später wieder entfernen:
// input.removeEventListener('keydown', onKey);Tastenkürzel Strg/Cmd + S abfangen
window.addEventListener('keydown', (event) => {
const mod = event.ctrlKey || event.metaKey;
// toLowerCase(), weil key bei gedrückter Shift-Taste "S" liefert
if (mod && event.key.toLowerCase() === 's') {
event.preventDefault(); // Speichern-Dialog des Browsers unterdrücken
console.log('Dokument gespeichert');
}
});Pfeiltasten-Navigation in einer Liste
const items = [...document.querySelectorAll('#menu li')];
let index = 0;
document.addEventListener('keydown', (event) => {
if (event.isComposing) return; // IME-Eingabe ignorieren
if (event.key === 'ArrowDown') index = Math.min(index + 1, items.length - 1);
else if (event.key === 'ArrowUp') index = Math.max(index - 1, 0);
else return;
event.preventDefault(); // Scrollen verhindern
items[index].focus();
console.log('Aktiv:', index);
});// Wichtig · Fallstricke
- Groß-/Kleinschreibung: Bei gedrückter Shift-Taste oder aktivem Caps Lock liefert
keyGroßbuchstaben. Prüfe Kürzel deshalb mitevent.key.toLowerCase(). - Layout-Abhängigkeit: Auf einer deutschen Tastatur liefert
AltGr+Qden Wert"@". Unter Windows meldet der Browser AltGr zusätzlich alsctrlKey+altKey. Das kann Kürzel mit Strg+Alt fälschlich auslösen. - Tottasten (z. B.
^oder´) liefern zunächst"Dead". Das fertige Zeichen erscheint erst mit der folgenden Taste. - IME-Eingabe: Während einer Komposition ist
event.isComposinggesetzt undkeyoft"Process". Solche Ereignisse solltest du bei Kürzeln ignorieren. - Leertaste: Der Wert ist
" "(ein Leerzeichen), nicht"Space"."Space"ist der Wert voncode. - Veraltete Werte: Ältere Versionen von Edge und Internet Explorer lieferten abweichende Namen wie
"Esc","Left","Spacebar"oder"Del". Falls du alte Umgebungen unterstützen musst, prüfe auch diese Werte. - Nutze
keydownstatt des veraltetenkeypress.keyCode,whichundcharCodesind veraltet und sollten nicht mehr verwendet werden. - Die Eigenschaft ist schreibgeschützt. Für Tests setzt du sie beim Erzeugen:
new KeyboardEvent('keydown', { key: 'Enter' }).