KeyboardEvent.location — Eigenschaft · JavaScript-Referenz

Signatur

KeyboardEvent.location

Beschreibung

Die schreibgeschützte Eigenschaft KeyboardEvent.location gibt einen unsigned long-Wert zurück. Er zeigt an, an welcher Stelle der Tastatur die auslösende Taste liegt. So lassen sich Tasten unterscheiden, die es mehrfach gibt, zum Beispiel linke und rechte Umschalt-, Strg- oder Alt-Taste oder die Ziffern im Hauptfeld und im Ziffernblock.

Mögliche Werte sind als Konstanten auf KeyboardEvent definiert:

KeyboardEvent.DOM_KEY_LOCATION_STANDARD (0): Die Taste gibt es nur einmal oder ihre Position wird nicht unterschieden, z. B. Buchstaben, Leertaste, Ziffern im Hauptfeld.
KeyboardEvent.DOM_KEY_LOCATION_LEFT (1): die linke Variante, z. B. linke Umschalt-Taste.
KeyboardEvent.DOM_KEY_LOCATION_RIGHT (2): die rechte Variante, z. B. AltGr oder rechte Strg-Taste.
KeyboardEvent.DOM_KEY_LOCATION_NUMPAD (3): Taste auf dem Ziffernblock, auch NumLock.

Die Eigenschaft ist vor allem für Spiele, Tastenkürzel-Editoren und Emulatoren nützlich, also überall, wo linke und rechte Modifikatortasten verschiedene Aktionen auslösen sollen. Für normale Texteingabe braucht man sie meist nicht. Oft ist event.code die einfachere Wahl, weil es die Position schon im Namen enthält ("ShiftLeft", "Numpad5").

Rückgabewert

Typ

number

Beschreibung

Einer der Werte 0 (STANDARD), 1 (LEFT), 2 (RIGHT) oder 3 (NUMPAD), passend zu den Konstanten KeyboardEvent.DOM_KEY_LOCATION_*.

Beispiele

Position der gedrückten Taste als Text ausgeben

const locationNames = {
  [KeyboardEvent.DOM_KEY_LOCATION_STANDARD]: 'Standard',
  [KeyboardEvent.DOM_KEY_LOCATION_LEFT]: 'Links',
  [KeyboardEvent.DOM_KEY_LOCATION_RIGHT]: 'Rechts',
  [KeyboardEvent.DOM_KEY_LOCATION_NUMPAD]: 'Ziffernblock'
};

document.addEventListener('keydown', (event) => {
  console.log(`${event.key} → ${locationNames[event.location] ?? 'Unbekannt'}`);
});

Shift → Links Shift → Rechts 5 → Standard 5 → Ziffernblock

Linke und rechte Umschalttaste im Spiel unterscheiden

const player1 = { boost: false };
const player2 = { boost: false };

const setBoost = (event, active) => {
  if (event.key !== 'Shift') return;
  if (event.location === KeyboardEvent.DOM_KEY_LOCATION_LEFT) {
    player1.boost = active;
  } else if (event.location === KeyboardEvent.DOM_KEY_LOCATION_RIGHT) {
    player2.boost = active;
  }
  console.log('P1:', player1.boost, 'P2:', player2.boost);
};

window.addEventListener('keydown', (e) => setBoost(e, true));
window.addEventListener('keyup', (e) => setBoost(e, false));

P1: true P2: false P1: false P2: false

Nur Ziffernblock-Eingaben für einen Taschenrechner auswerten

const display = document.querySelector('#display');

document.addEventListener('keydown', (event) => {
  if (event.location !== KeyboardEvent.DOM_KEY_LOCATION_NUMPAD) return;
  if (/^[0-9+\-*/.]$/.test(event.key)) {
    display.textContent += event.key;
    event.preventDefault();
  }
});

Synthetisches Event mit location erzeugen

const evt = new KeyboardEvent('keydown', {
  key: 'Control',
  code: 'ControlRight',
  location: KeyboardEvent.DOM_KEY_LOCATION_RIGHT
});

console.log(evt.location);

2

// Wichtig · Fallstricke

Nur in keydown und keyup zuverlässig. Beim veralteten keypress-Event ist der Wert in manchen Browsern 0.
Die Eigenschaft ist schreibgeschützt. Bei synthetischen Events legt man sie über das Options-Objekt im Konstruktor new KeyboardEvent(type, { location }) fest.
Die Zuordnung hängt von Hardware und Betriebssystem ab: AltGr meldet unter Windows oft zusätzlich ein Control-Event mit location = 1. Laptop-Tastaturen ohne echten Ziffernblock (z. B. mit Fn-Taste) liefern womöglich nicht 3.
Virtuelle Tastaturen auf Mobilgeräten liefern meist 0.
Die veralteten Namen keyLocation und die früheren Werte DOM_KEY_LOCATION_MOBILE (4) und DOM_KEY_LOCATION_JOYSTICK (5) gibt es nicht mehr. Man sollte sie nicht verwenden.
Browser-Kompatibilität: wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Sehr alte WebKit-Versionen kannten nur keyLocation.
Oft ist event.code lesbarer ("ShiftRight", "NumpadEnter"). location lohnt sich, wenn man unabhängig vom Tastennamen nach der Position filtern will.

Siehe auch

KeyboardEvent.repeat KeyboardEvent.altKey KeyboardEvent.charCode KeyboardEvent.code KeyboardEvent.metaKey