KeyboardEvent

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.

Anmerkung: Das 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() (en-US): Erzeugt ein KeyboardEvent Objekt.

Methoden

Diese Schnittstelle erbt auch Methoden seiner Eltern UIEvent (en-US) 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() (en-US): Initialisiert ein KeyboardEvent Objekt. Dies wurde nur durch Gecko implementiert (andere verwendeten KeyboardEvent.initKeyboardEvent() (en-US)) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, den KeyboardEvent() (en-US) Konstrutor zu verwenden.
KeyboardEvent.initKeyboardEvent() (en-US): Initialisiert ein KeyboardEvent Objekt. Dies wurde nie von Gecko implementiert (da stattdessen KeyboardEvent.initKeyEvent() (en-US) verwendet wurde) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, den KeyboardEvent() (en-US) Konstruktor zu verwenden.

Eigenschaften

Diese Schnittstelle erbt auch Methoden seiner Eltern UIEvent (en-US) und Event.

KeyboardEvent.altKey Schreibgeschützt: Liefert einen Boolean Wert der true ist falls die Alt ( Option oder ⌥ unter OS X) Taste aktiv war, als das Tastenevent erzeugt wurde.
KeyboardEvent.char Schreibgeschützt: 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 (en-US) Schreibgeschützt: Liefert einen Number Wert der die Unicode-Kennziffer der Taste repräsentiert; dieses Attribut wird nur vom keypress Event verwendet. Für Tasten deren char 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 (en-US) verwenden.
KeyboardEvent.code (en-US) Schreibgeschützt: Liefert einen DOMString mit dem Codewert der Taste, welche durch das Event repräsentiert wird.
KeyboardEvent.ctrlKey (en-US) Schreibgeschützt: Liefert einen Boolean Wert der true ist, falls die Ctrl Taste aktiv war als das Key-Event erzeugt wurde.
KeyboardEvent.isComposing (en-US) Schreibgeschützt: Liefert einen Boolean Wert der true ist falls das Event nach compositionstart und vor compositionend ausgelöst wird.
KeyboardEvent.key (en-US) Schreibgeschützt: Liefert einen DOMString der den Wert der Taste darstellt die durch das Event repräsentiert wird.
KeyboardEvent.keyCode Schreibgeschützt: 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 (en-US) verwenden.
KeyboardEvent.keyIdentifier (en-US) Schreibgeschützt: Diese Eigenschaft ist nicht standardisiert und veraltet. Es sollte stattdessen KeyboardEvent.key (en-US) verwendet werden. Sie war Teil einer alten Version von DOM Level 3 Events.
KeyboardEvent.keyLocation Schreibgeschützt: Dies ist ein nicht-standardisierter Alias für KeyboardEvent.location (en-US). Sie war Teil einer alten Version von DOM Level 3 Events.
KeyboardEvent.locale Schreibgeschützt: 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 (en-US) Schreibgeschützt: Liefert einen Number Wert der die Lage der Taste auf der Tastatur oder einem anderen Eingabegerät repräsentiert.
KeyboardEvent.metaKey (en-US) Schreibgeschützt: Liefert einen Boolean Wert der true 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 (en-US) Schreibgeschützt: Liefert einen Boolean Wert der true ist, falls die Taste gedrückt gehalten wird, so dass sie sich automatisch wiederholt.
KeyboardEvent.shiftKey (en-US) Schreibgeschützt: Liefert einen Boolean Wert der true ist, falls die Shift Taste aktiv war, als das Key-Event erzeugt wurde.
KeyboardEvent.which (en-US) Schreibgeschützt: 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 wie keyCode.
Warnung: Dieses Attribut ist veraltet; Sie sollten stattdessen - wenn vorhanden - KeyboardEvent.key (en-US) 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() (en-US) durch Gecko Browser und die frühe DOM Events Level 3 Version, KeyboardEvent.initKeyboardEvent() (en-US) durch Andere. Beide wurden durch den modernen Einsatz eines Konstruktors ersetzt: KeyboardEvent() (en-US).

Browserkompatibilität

Wir konvertieren die Kompatibilitätsdaten in ein maschinenlesbares JSON Format. Diese Kompatibilitätstabelle liegt noch im alten Format vor, denn die darin enthaltenen Daten wurden noch nicht konvertiert. Finde heraus wie du helfen kannst! (en-US)

Desktop
Mobile

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.