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.
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 stattgefunden hat.
Hinweis: KeyboardEvent
-Ereignisse zeigen nur, welche Interaktion der Benutzer auf niedriger Ebene mit einer Taste auf der Tastatur hatte, ohne der Interaktion eine kontextuelle Bedeutung zu geben. Wenn Sie Texteingaben behandeln müssen, verwenden Sie stattdessen das input
Ereignis. Tastaturereignisse werden möglicherweise nicht ausgelöst, wenn der Benutzer eine alternative Methode zur Texteingabe verwendet, wie z. B. ein Handschrifterkennungssystem auf einem Tablet oder Grafiktablett.
Konstruktor
KeyboardEvent()
-
Erstellt ein neues
KeyboardEvent
-Objekt.
Konstanten
Das KeyboardEvent
-Interface definiert die folgenden Konstanten.
Tastaturlokationen
Die folgenden Konstanten identifizieren, aus welchem Bereich der Tastatur das Tastenereignis stammt. Sie werden als KeyboardEvent.DOM_KEY_LOCATION_STANDARD
usw. abgerufen.
Konstante | Wert | Beschreibung |
---|---|---|
DOM_KEY_LOCATION_STANDARD |
0x00 |
Die durch das Ereignis beschriebene Taste wird nicht als in einem bestimmten Bereich der Tastatur befindlich identifiziert; sie befindet sich nicht auf dem Nummernblock (es sei denn, es handelt sich um 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 dieser Position zu assoziieren. Beispiele sind 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 Positionen auf der Tastatur existieren und befindet sich in diesem Fall auf der linken Seite der Tastatur. Beispiele sind die linke Strg-Taste, die linke Befehlstaste auf einer Mac-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 sind 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 Position gibt, von der die Taste stammen könnte. Die NumLock-Taste gehört nicht zu dieser Gruppe und wird immer mit der Position Beispiele sind die Ziffern auf dem Nummernblock, die Eingabetaste des Nummernblocks und der Dezimalpunkt auf dem Nummernblock. |
Instanz-Eigenschaften
Dieses Interface erbt auch Eigenschaften seiner Eltern, UIEvent
und Event
.
KeyboardEvent.altKey
Nur lesbar-
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
Nur lesbar-
Gibt einen String mit dem Codewert der durch das Ereignis dargestellten physischen Taste zurück.
Warnung: Dies ignoriert das Tastaturlayout des Benutzers, sodass, wenn der Benutzer die Taste an der "Y"-Position in einem QWERTY-Tastaturlayout (in der Nähe der Mitte der Reihe über der Grundreihe) drückt, 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 korrekten Tastenanschläge dem Benutzer anzeigen möchten, können Sie
Keyboard.getLayoutMap()
verwenden. KeyboardEvent.ctrlKey
Nur lesbar-
Gibt einen booleschen Wert zurück, der
true
ist, wenn die Strg-Taste aktiv war, als das Tastenereignis generiert wurde. KeyboardEvent.isComposing
Nur lesbar-
Gibt einen booleschen Wert zurück, der
true
ist, wenn das Ereignis zwischencompositionstart
undcompositionend
ausgelöst wird. KeyboardEvent.key
Nur lesbar-
Gibt einen String zurück, der den Tastenwert der durch das Ereignis dargestellten Taste darstellt.
KeyboardEvent.location
Nur lesbar-
Gibt eine Zahl zurück, die den Ort der Taste auf der Tastatur oder einem anderen Eingabegerät darstellt. Eine Liste der Konstanten, die die Standorte identifizieren, wird oben unter Tastaturlokationen gezeigt.
KeyboardEvent.metaKey
Nur lesbar-
Gibt einen booleschen Wert zurück, der
true
ist, wenn die Meta-Taste (auf Mac-Tastaturen die ⌘ Befehlstaste; auf Windows-Tastaturen die Windows-Taste (⊞)) aktiv war, als das Tastenereignis generiert wurde. KeyboardEvent.repeat
Nur lesbar-
Gibt einen booleschen Wert zurück, der
true
ist, wenn die Taste gedrückt gehalten wird, sodass sie sich automatisch wiederholt. KeyboardEvent.shiftKey
Nur lesbar-
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 Nur lesbar-
Gibt eine Zahl zurück, die die Unicode-Referenznummer der Taste darstellt; diese Eigenschaft wird nur von dem
keypress
-Ereignis verwendet. Bei Tasten, derenchar
-Eigenschaft mehrere Zeichen enthält, ist dies der Unicode-Wert des ersten Zeichens in dieser Eigenschaft. In Firefox 26 werden dadurch Codes für druckbare Zeichen zurückgegeben. KeyboardEvent.keyCode
Veraltet Nur lesbar-
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 Nur lesbar-
Diese Eigenschaft ist nicht standardisiert und wurde zugunsten von
KeyboardEvent.key
veraltet. Sie war Teil einer alten Version von DOM Level 3 Events.
Instanz-Methoden
Dieses Interface erbt auch Methoden seiner Eltern, UIEvent
und Event
.
KeyboardEvent.getModifierState()
-
Gibt einen booleschen Wert zurück, der anzeigt, ob eine Modifikatortaste wie Alt, Shift, Strg oder Meta gedrückt war, als das Ereignis erstellt wurde.
Veraltete Methoden
KeyboardEvent.initKeyEvent()
Veraltet-
Initialisiert ein
KeyboardEvent
-Objekt. Dies wurde nur von Firefox implementiert und wird auch dort nicht mehr unterstützt; stattdessen sollten Sie denKeyboardEvent()
Konstruktor verwenden. KeyboardEvent.initKeyboardEvent()
Veraltet-
Initialisiert ein
KeyboardEvent
-Objekt. Dies ist jetzt veraltet. Sie sollten stattdessen denKeyboardEvent()
Konstruktor verwenden.
Ereignisse
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 löst Gecko eine Sequenz von Tastenereignissen wie folgt aus:
- 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 Status eines Anzeigelichts um; dazu gehören Tasten wie Caps Lock, Num Lock und Scroll Lock. 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.
Ein Problem des macOS-Ereignismodells führt jedoch dazu, dass Caps Lock nur das keydown
-Ereignis auslöst. Num Lock wurde auf einigen älteren Laptop-Modellen (Modelle von 2007 und älter) unterstützt, aber seitdem unterstützt macOS Num Lock nicht mehr, selbst auf externen Tastaturen. Auf älteren MacBooks mit einer Num Lock-Taste erzeugt diese keine Tastenereignisse. Gecko unterstützt die Scroll-Lock-Taste, wenn eine externe Tastatur mit einer F14-Taste angeschlossen ist. In bestimmten älteren Versionen von Firefox erzeugte diese Taste ein keypress
-Ereignis; dieses inkonsistente Verhalten war Firefox-Bug 602812.
Auto-Repeat-Handhabung
Wenn eine Taste gedrückt und gehalten wird, beginnt sie, sich automatisch zu wiederholen. Dies führt zur Auslösung einer Ereignissequenz wie folgt:
keydown
keypress
keydown
keypress
- <<wiederholt sich, bis der Benutzer die Taste loslässt>>
keyup
Dies ist das, was die DOM Level 3-Spezifikation verlangt. Es gibt jedoch einige Einschränkungen, wie unten beschrieben.
Auto-Repeat in bestimmten GTK-Umgebungen wie Ubuntu 9.4
In einigen GTK-basierten Umgebungen löst Auto-Repeat ein natives Key-Up-Ereignis automatisch während des Auto-Repeats aus, und es gibt keine Möglichkeit für Gecko, den Unterschied zwischen einer wiederholten Serie von Tastenanschlägen und einem Auto-Repeat zu erkennen. Auf diesen Plattformen erzeugt eine Auto-Repeat-Taste dann die folgende Ereignissequenz:
keydown
keypress
keyup
keydown
keypress
keyup
- <<wiederholt sich, bis der Benutzer die Taste loslässt>>
keyup
In diesen Umgebungen gibt es leider keine Möglichkeit für Webinhalte, den Unterschied zwischen sich wiederholenden Tasten und Tasten, die 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 KeyboardEvent
-Schnittstellenspezifikation durchlief mehrere Entwurfsfassungen, zuerst 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 ersetzt: KeyboardEvent()
.
Browser-Kompatibilität
BCD tables only load in the browser
Kompatibilitätsnotizen
- Ab Firefox 65 wird das
keypress
-Ereignis nicht mehr für nicht druckbare Tasten ausgelöst (Firefox-Bug 968056), mit Ausnahme der Enter-Taste und der Shift + Enter und Strg + Enter-Tastenkombinationen (diese wurden aus Gründen der plattformübergreifenden Kompatibilität beibehalten).