KeyboardEvent
Objekte beschreiben eine Benutzerinteraktion mit dem Keyboard. Jedes Event beschreibt eine Taste. Der Eventtyp (keydown
, keypress
, oder keyup
) identifiziert welche Art von Aktivität ausgeführt wurde.
KeyboardEvent
deutet nur an was mit einer Taste passiert. Wenn Sie Texteingaben behandeln müssen, verwenden sie stattdessen das HTML5 input
Event. Beispiel: Wenn ein Benutzer Text über ein Handschriftsystem - wie auf einem Tablet - eingibt, werden Tastenevents möglicherweise nicht ausgelöst.Konstruktor
KeyboardEvent()
- Erzeugt ein
KeyboardEvent
Objekt.
Methoden
Diese Schnittstelle erbt auch Methoden seiner Eltern UIEvent
und Event
.
KeyboardEvent.getModifierState()
- Liefert einen
Boolean
Wert welcher angibt ob eine Hilfstaste wie Alt, Shift, Ctrl, oder Meta gedrückt war als das Event erzeugt wurde. KeyboardEvent.initKeyEvent()
- Initialisiert ein
KeyboardEvent
Objekt. Dies wurde nur durch Gecko implementiert (andere verwendetenKeyboardEvent.initKeyboardEvent()
) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, denKeyboardEvent()
Konstrutor zu verwenden. KeyboardEvent.initKeyboardEvent()
- Initialisiert ein
KeyboardEvent
Objekt. Dies wurde nie von Gecko implementiert (da stattdessenKeyboardEvent.initKeyEvent()
verwendet wurde) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, denKeyboardEvent()
Konstruktor zu verwenden.
Eigenschaften
Diese Schnittstelle erbt auch Methoden seiner Eltern UIEvent
und Event
.
KeyboardEvent.altKey
Read only- Liefert einen
Boolean
Wert dertrue
ist falls die Alt ( Option oder ⌥ unter OS X) Taste aktiv war, als das Tastenevent erzeugt wurde. KeyboardEvent.char
Read only- Liefert einen
DOMString
der das Zeichen der Taste repräsentiert. Wenn die Taste einem druckbaren Zeichen entspricht, ist dieser Wert eine nicht-leere Unicode-Zeichenkette die dieses Zeichen enthält. Fall die Taste keine druckbare Darstellung besitzt, ist der Wert eine leere Zeichenkette.Anmerkung: Falls die Taste als Makro verwendet wird, das mehrere Zeichen einfügt, ist der Wert dieses Attributs die gesamte Zeichenkette, nicht nur das erste Zeichen.Warnung: Dies wurde aus den DOM Level 3 Events entfernt. Es wird nur von IE9+ und Microsoft Edge unterstützt. KeyboardEvent.charCode
Read only- Liefert einen
Number
Wert der die Unicode-Kennziffer der Taste repräsentiert; dieses Attribut wird nur vomkeypress
Event verwendet. Für Tasten derenchar
Attribut mehrere Zeichen enthält ist der Wert dieses Attributs der Unicode-Wert des ersten Zeichens . In Firefox 26 liefert dies Codes für druckbare Zeichen.Warnung: Dieses Attribut ist veraltet; Sie sollten stattdessen - wenn vorhanden -KeyboardEvent.key
verwenden. KeyboardEvent.code
Read only- Liefert einen
DOMString
mit dem Codewert der Taste, welche durch das Event repräsentiert wird. KeyboardEvent.ctrlKey
Read only- Liefert einen
Boolean
Wert dertrue
ist, falls die Ctrl Taste aktiv war als das Key-Event erzeugt wurde. KeyboardEvent.isComposing
Read only- Liefert einen
Boolean
Wert dertrue
ist falls das Event nachcompositionstart
und vorcompositionend
ausgelöst wird. KeyboardEvent.key
Read only- Liefert einen
DOMString
der den Wert der Taste darstellt die durch das Event repräsentiert wird. KeyboardEvent.keyCode
Read only- Liefert einen
Number
Wert der einen system- und implementationsabhängigen Zahlencode darstellt, der den unmodifizierten Wert der gedrückten Taste repräsentiert.Warnung: Dieses Attribut ist veraltet; Sie sollten stattdessen - wenn vorhanden -KeyboardEvent.key
verwenden. KeyboardEvent.keyIdentifier
Read only- Diese Eigenschaft ist nicht standardisiert und veraltet. Es sollte stattdessen
KeyboardEvent.key
verwendet werden. Sie war Teil einer alten Version von DOM Level 3 Events. KeyboardEvent.keyLocation
Read only- Dies ist ein nicht-standardisierter Alias für
KeyboardEvent.location
. Sie war Teil einer alten Version von DOM Level 3 Events. KeyboardEvent.locale
Read only- Liefert einen
DOMString
der das Gebietsschema identifiziert für die das Keyboard konfiguriert ist. Diese Zeichenkette kann leer sein, wenn der Browser oder das Gerät das Gebietsschema des Keyboards nicht kennt.Anmerkung: Dies beschreibt nicht das Gebietsschema der eingegebenen Daten. Ein Benutzer könnte ein Tastaturlayout nutzen während er Text in einer anderen Sprache eingibt. KeyboardEvent.location
Read only- Liefert einen
Number
Wert der die Lage der Taste auf der Tastatur oder einem anderen Eingabegerät repräsentiert. KeyboardEvent.metaKey
Read only- Liefert einen
Boolean
Wert dertrue
ist, falls die Meta Taste (auf Mac-Tastaturen, die ⌘ Command Taste; auf Windows-Tastaturen, die Windows -Taste (⊞)) aktiv war, als das Key-Event erzeugt wurde. KeyboardEvent.repeat
Read only- Liefert einen
Boolean
Wert dertrue
ist, falls die Taste gedrückt gehalten wird, so dass sie sich automatisch wiederholt. KeyboardEvent.shiftKey
Read only- Liefert einen
Boolean
Wert dertrue
ist, falls die Shift Taste aktiv war, als das Key-Event erzeugt wurde. KeyboardEvent.which
Read only- Liefert einen
Number
Wert der einen system- und implementationsabhängigen Zahlencode darstellt, der den unmodifizierten Wert der gedrückten Taste repräsentiert; das ist gewöhnlich das Gleiche wiekeyCode
.Warnung: Dieses Attribut ist veraltet; Sie sollten stattdessen - wenn vorhanden -KeyboardEvent.key
verwenden.
Anmerkungen
Es gibt keydown
, keypress
, and keyup
Events. Für die meisten Tasten versendet Gecko eine Sequenz von Key-Events wie folgt:
- Wenn die Taste gedrückt wird, wird ein
keydown
Event gesendet. - Falls die Taste keine Hilfstaste ist, wird das
keypress
Event gesendet. - Wenn der Nutzer die Taste loslässt, wird das
keyup
Event gesendet.
Sonderfälle
Einige Taste schalten den Status einer Kontrollleuchte um; dazu gehören Caps Lock, Num Lock, und Scroll Lock. Unter Windows und Linux senden diese Tasten nur keydown
and keyup
Events.
Unter Linux versendet Firefox 12 und eher das keypress
Event auch für diese Tasten.
Jedoch sorgen die Einschränkungen des Mac OS X Event-Modells dafür, dass Caps Lock nur das keydown
Event versendet. Num Lock wurde auf einigen älteren Laptop-Modellen (Modelle 2007 und älter) unterstützt, aber seitdem hat Mac OS X Num Lock nicht mehr untertstützt - nicht einmal auf externen Tastaturen. Auf älteren MacBooks mit einer Num Lock Taste, erzeugt diese Taste überhaupt keine KeyEvents. Gecko unterstützt die Scroll Lock Taste, falls eine externe Tastatur, die eine F14 Taste besitzt, angeschlossen ist. In bestimmten älteren Firefox-Versionen erzeugt diese Taste ein keypress
Event; dieses inkonsistente Verhalten war Bug 602812.
Behandlung von Auto-repeat
Wenn eine Taste gedrückt und gehalten wird, beginnt sie die automatische Wiederholung (sog. auto-repeat). Das Resultat ist das Versenden einer Reihe von Events ähnlich der folgenden:
keydown
keypress
keydown
keypress
- <<wiederholt sich bis der Nutzer die Taste loslässt>>
keyup
Das sollte laut DOM Level 3 Spezifikation passieren. Allerdings gibt es einige Ausnahmen, wie unten beschrieben.
Auto-repeat in einigen GTK-Umgebungen wie Ubuntu 9.4
In einigen GTK-basierten Umgebungen versendet auto-repeat automatisch ein natives Key-Up Event während der automatischen Wiederholung und es ist für Gecko deshalb nicht möglich zwischen wiederholten Tastendrücken und einem auto-repeat unterscheiden zu können. Auf diesen Platformen wird eine Auto-Repeat Taste also die folgende Reihe von Events erzeugen:
keydown
keypress
keyup
keydown
keypress
keyup
- <<wiederholt sich bis der Nutzer die Taste loslässt>>
keyup
Innerhalb dieser Umgebungen gibt es leider keine Möglichkeit für Webinhalte den Unterschied zwischen selbst-wiederholenden Tasten und Tasten die wiederholt gedrückt werden herauszufinden.
Behandlung von auto-repeat vor Gecko 5.0
Vor Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) war platformübergreifendes Tastatur-Handling weniger einheitlich.
- Windows
- Das Auto-Repeat-Verhalten ist das Gleiche wie in Gecko 4.0 und später.
- Mac
- Nach dem initialen keydown Event werden nur keypress Events gesendet bis das keyup Event auftritt; die dazwischendliegenden keydown Events werden nicht gesendet.
- Linux
- Das Event-Verhalten hängt von der spezifischen Platform ab. Es wird sich entweder so verhalten wie Windows oder Mac, abhängig davon was das native Event-Modell macht.
Anmerkung: manuelles Auslösen eines Events erzeugt nicht die mit dem Event verbundene Standard-Aktion. Zum Beispiel: manuelles Auslösen eines KeyEvent führt nicht dazu, dass der Buchstabe in einem fokussierten Eingabefeld auftaucht. Im Fall von UI-Events ist dies aus Sicherheitsgründen wichtig, da es verhindert, dass Skripte Benutzeraktionen simulieren, die mit dem Browser selbst interagieren.
Beispiel
<!DOCTYPE html>
<html>
<head>
<script>
'use strict';
document.addEventListener('keydown', (event) => {
const keyName = event.key;
if (keyName === 'Control') {
// not alert when only Control key is pressed.
return;
}
if (event.ctrlKey) {
// Even though event.key is not 'Control' (i.e. 'a' is pressed),
// event.ctrlKey may be true if Ctrl key is pressed at the time.
alert(`Combination of ctrlKey + ${keyName}`);
} else {
alert(`Key pressed ${keyName}`);
}
}, false);
document.addEventListener('keyup', (event) => {
const keyName = event.key;
// As the user release the Ctrl key, the key is no longer active.
// So event.ctrlKey is false.
if (keyName === 'Control') {
alert('Control key was released');
}
}, false);
</script>
</head>
<body>
</body>
</html>
Spezifikationen
Specification | Status | Comment |
---|---|---|
Document Object Model (DOM) Level 3 Events Specification Die Definition von 'KeyboardEvent' in dieser Spezifikation. |
Veraltet | Initiale Definition |
Die KeyboardEvent
Schnittstelle lief durch eine Vielzahl von Entwurfsversionen, erst unter DOM Events Level 2, wo sie verworfen wurde als kein Konsens entstand, danach unter DOM Events Level 3. Dies führte zu einer Implementation von nicht standardisierten Initialisationsmethoden, der frühen DOM Events Level 2 Version
KeyboardEvent.initKeyEvent()
durch Gecko Browser und die frühe DOM Events Level 3 Version, KeyboardEvent.initKeyboardEvent()
durch Andere. Beide wurden durch den modernen Einsatz eines Konstruktors ersetzt: KeyboardEvent()
.
Browserkompatibilität
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | (Ja) | (Ja) | (Ja) | (Ja) | (Ja) | (Ja) |
constructor | (Ja) | ? | 31.0 (31.0) | Nicht unterstützt | (Ja) | ? |
.char |
Nicht unterstützt | ? | Nicht unterstützt | 9 | Nicht unterstützt | Nicht unterstützt |
.charCode |
(Ja) | ? | (Ja) | (Ja) | (Ja) | (Ja) |
.isComposing |
Nicht unterstützt | ? | 31.0 (31.0) | Nicht unterstützt | Nicht unterstützt | Nicht unterstützt |
.keyCode |
(Ja) | ? | (Ja) | (Ja) | (Ja) | (Ja) |
.locale |
Nicht unterstützt | ? | Nicht unterstützt | (Ja) | Nicht unterstützt | Nicht unterstützt |
.location |
(Ja) | ? | 15.0 (15.0) | (Ja) | Nicht unterstützt | Nicht unterstützt |
.repeat |
(Ja) | ? | 28.0 (28.0) | (Ja) | Nicht unterstützt | Nicht unterstützt |
.which |
(Ja) | ? | (Ja) | (Ja) | (Ja) | (Ja) |
.initKeyboardEvent() |
(Ja)[1] | ? | Nicht unterstützt[2] | 9.0[3] | ? | (Ja)[1] |
Feature | Android | Edge | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | ? | (Ja) | (Ja) | ? | ? | ? |
constructor | ? | ? | 31.0 (31.0) | ? | ? | ? |
.char |
? | ? | Nicht unterstützt | ? | ? | ? |
.charCode |
? | ? | (Ja) | ? | ? | ? |
.isComposing |
Nicht unterstützt | ? | 31.0 (31.0) | Nicht unterstützt | Nicht unterstützt | Nicht unterstützt |
.keyCode |
? | ? | (Ja) | ? | ? | ? |
.locale |
? | ? | Nicht unterstützt | ? | ? | ? |
.location |
? | ? | 15.0 (15.0) | ? | ? | ? |
.repeat |
? | ? | 28.0 (28.0) | ? | ? | ? |
.which |
? | ? | (Ja) | ? | ? | ? |
.initKeyboardEvent() |
? | ? | Nicht unterstützt | ? | ? | ? |
[1] Die Argumente von initKeyboardEvent()
von WebKit and Blink weichen von der Definition in DOM Level 3 Events ab. Die Methode ist: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIdentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)
[2] Gecko wird initKeyboardEvent()
nicht unterstützen, weil es die Feature-Erkennung von Web-Apllikationen komplett zerstört. Siehe Bug 999645.
[3] Das Argument von initKeyboardEvent()
von IE weicht von der Definition in DOM Level 3 Events ab. Die Methode ist: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in number locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg)
. Siehe document of initKeyboardEvent()
in MSDN.