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.

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 verwendeten KeyboardEvent.initKeyboardEvent()) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, den KeyboardEvent() Konstrutor zu verwenden.

KeyboardEvent.initKeyboardEvent()

Initialisiert ein KeyboardEvent Objekt. Dies wurde nie von Gecko implementiert (da stattdessen KeyboardEvent.initKeyEvent() verwendet wurde) und sollte nicht mehr benutzt werden. Der moderne Standardweg ist, den KeyboardEvent() Konstruktor zu verwenden.

Eigenschaften

Diese Schnittstelle erbt auch Methoden seiner Eltern UIEvent und Event.

KeyboardEvent.altKey Read only

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 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 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 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 der true ist, falls die Ctrl Taste aktiv war als  das Key-Event erzeugt wurde.

KeyboardEvent.isComposing Read only

Liefert einen Boolean Wert der true ist falls das Event nach compositionstart und vor compositionend 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 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 Read only

Liefert einen Boolean Wert der true ist, falls die Taste gedrückt gehalten wird, so dass sie sich automatisch wiederholt.

KeyboardEvent.shiftKey Read only

Liefert einen Boolean Wert der true 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 wie keyCode.

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:

1. Wenn die Taste gedrückt wird, wird ein keydown Event gesendet.
2. Falls die Taste keine Hilfstaste ist, wird das keypress Event gesendet.
3. 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.

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:

1. keydown
2. keypress
3. keydown
4. keypress
5. <<wiederholt sich bis der Nutzer die Taste loslässt>>
6. 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:

1. keydown
2. keypress
3. keyup
4. keydown
5. keypress
6. keyup
7. <<wiederholt sich bis der Nutzer die Taste loslässt>>
8. 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

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

[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.

Siehe auch

• KeyboardEvent.code.
• KeyboardEvent.key.
• KeyboardEvent.getModifierState