KeyboardEvent

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

KeyboardEvent Objekte beschreiben eine Benutzerinteraktion mit der Tastatur; jedes Ereignis beschreibt eine einzelne Interaktion zwischen dem Benutzer und einer Taste (oder einer Kombination einer Taste mit Modifikatortasten) auf der Tastatur. Der Ereignistyp (keydown, keypress oder keyup) identifiziert, welche Art von Tastaturaktivität aufgetreten ist.

Note: KeyboardEvent-Ereignisse zeigen nur an, welche Interaktion der Benutzer mit einer Taste auf der Tastatur auf niedriger Ebene hatte, ohne kontextuelle Bedeutung dieser Interaktion bereitzustellen. Wenn Sie Text eingaben behandeln müssen, verwenden Sie stattdessen das input-Ereignis. Tastaturereignisse werden möglicherweise nicht ausgelöst, wenn der Benutzer eine alternative Methode zur Eingabe von Text verwendet, wie z.B. ein Handschrifterkennungssystem auf einem Tablet oder Grafik-Tablet.

Konstruktor

KeyboardEvent(): Erstellt ein neues KeyboardEvent-Objekt.

Konstanten

Das KeyboardEvent-Interface definiert die folgenden Konstanten.

Tastaturanordnungen

Die folgenden Konstanten identifizieren, von welchem Teil der Tastatur das Tastenereignis stammt. Sie werden als KeyboardEvent.DOM_KEY_LOCATION_STANDARD usw. abgerufen.

Tastaturstandort-Identifikatoren
Konstante	Wert	Beschreibung
`DOM_KEY_LOCATION_STANDARD`	0x00	Die Taste, die durch das Ereignis beschrieben wird, ist nicht als in einem bestimmten Bereich der Tastatur lokalisiert identifiziert; sie befindet sich nicht auf dem Nummernblock (es sei denn, es ist die NumLock-Taste), und für Tasten, die auf der linken und rechten Seite der Tastatur dupliziert sind, ist die Taste aus irgendeinem Grund nicht mit diesem Standort zu assoziieren. Beispiele umfassen alphanumerische Tasten auf der Standard-PC-101-US-Tastatur, die NumLock-Taste und die Leertaste.
`DOM_KEY_LOCATION_LEFT`	0x01	Die Taste kann an mehreren Standorten auf der Tastatur existieren und befindet sich in diesem Fall auf der linken Seite der Tastatur. Beispiele umfassen die linke Steuerungstaste, die linke Befehlstaste auf einer Macintosh-Tastatur oder die linke Umschalttaste.
`DOM_KEY_LOCATION_RIGHT`	0x02	Die Taste kann an mehreren Positionen auf der Tastatur existieren und befindet sich in diesem Fall auf der rechten Seite der Tastatur. Beispiele umfassen die rechte Umschalttaste und die rechte Alt-Taste (Option auf einer Mac-Tastatur).
`DOM_KEY_LOCATION_NUMPAD`	0x03	Die Taste befindet sich auf dem Nummernblock oder ist eine virtuelle Taste, die mit dem Nummernblock assoziiert ist, wenn es mehr als eine Stelle gibt, von der die Taste stammen könnte. Die NumLock-Taste fällt nicht in diese Gruppe und wird immer mit der Lokation `DOM_KEY_LOCATION_STANDARD` kodiert. Beispiele beinhalten die Ziffern auf dem Nummernblock, die Enter-Taste des Nummernblocks und den Dezimalpunkt auf dem Nummernblock.

Instanzeigenschaften

Dieses Interface erbt auch Eigenschaften seiner Eltern, UIEvent und Event.

KeyboardEvent.altKey Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn die Alt-Taste (Option oder ⌥ auf macOS) aktiv war, als das Tastenereignis generiert wurde.
KeyboardEvent.code Schreibgeschützt: Gibt eine Zeichenkette mit dem Codewert der physischen Taste zurück, die durch das Ereignis dargestellt wird.

Warnung: Dies ignoriert das Tastatur-Layout des Benutzers, sodass wenn der Benutzer die Taste an der "Y"-Position in einem QWERTY-Tastaturlayout drückt (nahe der Mitte der Reihe über der Home-Row), dies immer "KeyY" zurückgibt, selbst wenn der Benutzer eine QWERTZ-Tastatur hat (was bedeuten würde, dass der Benutzer ein "Z" erwartet und alle anderen Eigenschaften ein "Z" anzeigen würden) oder ein Dvorak-Tastaturlayout (wo der Benutzer ein "F" erwarten würde). Wenn Sie die richtigen Tastenanschläge für den Benutzer anzeigen möchten, können Sie Keyboard.getLayoutMap() verwenden.
KeyboardEvent.ctrlKey Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn die Ctrl-Taste aktiv war, als das Tastenereignis generiert wurde.
KeyboardEvent.isComposing Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn das Ereignis zwischen compositionstart und compositionend ausgelöst wird.
KeyboardEvent.key Schreibgeschützt: Gibt eine Zeichenkette zurück, die den Tastenwert der Taste darstellt, die durch das Ereignis repräsentiert wird.
KeyboardEvent.location Schreibgeschützt: Gibt eine Zahl zurück, die die Position der Taste auf der Tastatur oder einem anderen Eingabegerät darstellt. Eine Liste der Konstanten, die die Positionen identifizieren, wird oben im Abschnitt Tastaturanordnungen angezeigt.
KeyboardEvent.metaKey Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn die Meta-Taste (auf Mac-Tastaturen die ⌘ Command-Taste; auf Windows-Tastaturen die Windows-Taste (⊞)) aktiv war, als das Tastenereignis generiert wurde.
KeyboardEvent.repeat Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn die Taste gedrückt gehalten wird, sodass sie automatisch wiederholt wird.
KeyboardEvent.shiftKey Schreibgeschützt: Gibt einen booleschen Wert zurück, der true ist, wenn die Shift-Taste aktiv war, als das Tastenereignis generiert wurde.

Veraltete Eigenschaften

KeyboardEvent.charCode Veraltet Schreibgeschützt: Gibt eine Zahl zurück, die die Unicode-Referenznummer der Taste repräsentiert; diese Eigenschaft wird nur durch das keypress-Ereignis verwendet. Für Tasten, deren char-Eigenschaft mehrere Zeichen enthält, ist dies der Unicode-Wert des ersten Zeichens in dieser Eigenschaft. In Firefox 26 gibt dies die Codes für druckbare Zeichen zurück.
KeyboardEvent.keyCode Veraltet Schreibgeschützt: Gibt eine Zahl zurück, die einen system- und implementierungsabhängigen numerischen Code darstellt, der den unveränderten Wert der gedrückten Taste identifiziert.
KeyboardEvent.keyIdentifier Nicht standardisiert Veraltet Schreibgeschützt: Diese Eigenschaft ist nicht standardisiert und wurde zugunsten von KeyboardEvent.key veraltet. Sie war Teil einer alten Version der DOM Level 3 Events.

Instanzmethoden

Dieses Interface erbt auch Methoden seiner Eltern, UIEvent und Event.

KeyboardEvent.getModifierState(): Gibt einen booleschen Wert zurück, der angibt, ob eine Modifikatortaste wie Alt, Shift, Ctrl oder Meta gedrückt war, als das Ereignis erstellt wurde.

Veraltete Methoden

KeyboardEvent.initKeyboardEvent() Veraltet: Initialisiert ein KeyboardEvent-Objekt. Diese Methode ist jetzt veraltet. Sie sollten stattdessen den KeyboardEvent()-Konstruktor verwenden.

Ereignisse

Die folgenden Ereignisse basieren auf dem KeyboardEvent-Typ. In der Liste unten verlinkt jedes Ereignis auf die Dokumentation für den Element-Handler des Ereignisses, der allgemein für alle Empfänger gilt, einschließlich Element, Document und Window.

keydown: Eine Taste wurde gedrückt.
keyup: Eine Taste wurde losgelassen.

Veraltete Ereignisse

keypress Veraltet: Eine Taste, die normalerweise einen Zeichenwert erzeugt, wurde gedrückt. Dieses Ereignis war stark geräteabhängig und ist veraltet. Sie sollten es nicht verwenden.

Nutzungshinweise

Es gibt drei Arten von Tastaturereignissen: keydown, keypress und keyup. Für die meisten Tasten sendet Gecko eine Sequenz von Tastenereignissen wie folgt:

Wenn die Taste zuerst gedrückt wird, wird das keydown-Ereignis gesendet.
Wenn die Taste keine Modifikatortaste ist, wird das keypress-Ereignis gesendet.
Wenn der Benutzer die Taste loslässt, wird das keyup-Ereignis gesendet.

Sonderfälle

Einige Tasten schalten den Zustand einer Anzeigelampe um; dazu gehören Tasten wie Feststelltaste, Num-Taste und Bildlaufsperre. Unter Windows und Linux lösen diese Tasten nur die keydown- und keyup-Ereignisse aus.

Hinweis: Unter Linux löste Firefox 12 und früher auch das keypress-Ereignis für diese Tasten aus.

Jedoch verursacht eine Einschränkung des macOS-Ereignismodells, dass die Feststelltaste nur das keydown-Ereignis auslöst. Die Num-Taste wurde auf einigen älteren Laptop-Modellen (Modelle von 2007 und früher) unterstützt, aber seitdem hat macOS keine Unterstützung für die Num-Taste, selbst auf externen Tastaturen. Auf älteren MacBooks mit einer Num-Taste erzeugt diese Taste keine Tastenereignisse. Gecko unterstützt die Bildlaufsperre-Taste, wenn eine externe Tastatur angeschlossen ist, die eine F14-Taste hat. In bestimmten älteren Versionen von Firefox erzeugte diese Taste ein keypress-Ereignis; dieses inkonsistente Verhalten war Firefox-Bug 602812.

Automatische Wiederholverarbeitung

Wenn eine Taste gedrückt und gehalten wird, beginnt sie, sich automatisch zu wiederholen. Dies führt dazu, dass eine Ereignissequenz ähnlich der folgenden ausgelöst wird:

keydown
keypress
keydown
keypress
<<wiederholend, bis der Benutzer die Taste loslässt>>
keyup

Dies ist, was die DOM-Level-3-Spezifikation besagt, dass passieren sollte. Es gibt jedoch einige Einschränkungen, wie unten beschrieben.

Automatische Wiederholung in einigen GTK-Umgebungen wie Ubuntu 9.4

In einigen auf GTK basierenden Umgebungen löst die automatische Wiederholung ein natives key-up-Ereignis automatisch während der automatischen Wiederholung aus, und es gibt keine Möglichkeit für Gecko, den Unterschied zwischen einer wiederholten Serie von Tastendrücken und einer automatischen Wiederholung zu erkennen. Auf diesen Plattformen erzeugt dann eine automatisch wiederholte Taste die folgende Ereignissequenz:

keydown
keypress
keyup
keydown
keypress
keyup
<<wiederholend, bis der Benutzer die Taste loslässt>>
keyup

In diesen Umgebungen gibt es leider keine Möglichkeit für Web-Inhalte, den Unterschied zwischen automatisch wiederholten Tasten und Tasten, die einfach nur wiederholt gedrückt werden, zu erkennen.

Beispiel

document.addEventListener(
  "keydown",
  (event) => {
    const keyName = event.key;

    if (keyName === "Control") {
      // do not alert when only Control key is pressed.
      return;
    }

    if (event.ctrlKey) {
      // Even though event.key is not 'Control' (e.g., 'a' is pressed),
      // event.ctrlKey may be true if Ctrl key is pressed at the same time.
      alert(`Combination of ctrlKey + ${keyName}`);
    } else {
      alert(`Key pressed ${keyName}`);
    }
  },
  false,
);

document.addEventListener(
  "keyup",
  (event) => {
    const keyName = event.key;

    // As the user releases the Ctrl key, the key is no longer active,
    // so event.ctrlKey is false.
    if (keyName === "Control") {
      alert("Control key was released");
    }
  },
  false,
);

Spezifikationen

Specification
UI Events # interface-keyboardevent

Die Spezifikation der KeyboardEvent-Schnittstelle durchlief zahlreiche Entwurfsversionen, zunächst unter DOM Events Level 2, wo sie fallengelassen wurde, da kein Konsens erzielt wurde, dann unter DOM Events Level 3. Dies führte zur Implementierung nicht standardisierter Initialisierungsmethoden, der frühen DOM Events Level 2-Version, KeyboardEvent.initKeyEvent() durch Gecko-Browser und der frühen DOM Events Level 3-Version, KeyboardEvent.initKeyboardEvent() durch andere. Beide wurden durch die moderne Verwendung eines Konstruktors, KeyboardEvent(), ersetzt.

Browser-Kompatibilität

Kompatibilitätsnotizen

Ab Firefox 65 wird das keypress-Ereignis nicht mehr für nicht druckbare Tasten (Firefox-Bug 968056) ausgelöst, mit Ausnahme der Enter-Taste und der Tastenkombinationen Shift + Enter und Ctrl + Enter (diese wurden zur Wahrung der Browser-Kompatibilität beibehalten).