KeyboardEvent: Eigenschaft key

Wert

Ein String.

Der Wert wird wie folgt bestimmt:

• Wenn die gedrückte Taste eine druckbare Darstellung hat, ist der zurückgegebene Wert eine nicht leere Unicode-Zeichenfolge mit der druckbaren Darstellung der Taste. Wird beispielsweise die Space-Taste gedrückt, ist der zurückgegebene Wert ein einzelnes Leerzeichen (" "). Wird die B-Taste gedrückt, ist der zurückgegebene Wert der String "b". Ist gleichzeitig die Shift-Taste gedrückt (sodass shiftKey true ist), wird stattdessen der String "B" zurückgegeben.
• Wenn die gedrückte Taste eine Steuer- oder Sondertaste ist, ist der zurückgegebene Wert einer der vordefinierten Tastenwerte.
• Wenn das KeyboardEvent das Drücken einer Tottaste darstellt, muss der Tastenwert "Dead" sein.
• Einige spezielle Tastaturtasten (etwa zusätzliche Tasten zur Mediensteuerung auf Multimedia-Tastaturen) erzeugen unter Windows keine Tastencodes. Stattdessen lösen sie WM_APPCOMMAND-Ereignisse aus. Diese Ereignisse werden DOM-Tastaturereignissen zugeordnet und unter den „virtuellen Tastencodes“ für Windows aufgeführt, obwohl es sich nicht tatsächlich um Tastencodes handelt.
• Wenn die Taste nicht identifiziert werden kann, ist der zurückgegebene Wert Unidentified.

KeyboardEvent-Abfolge

Jedes KeyboardEvent wird in einer festgelegten Abfolge ausgelöst. Für einen Tastendruck werden die KeyboardEvents in der folgenden Reihenfolge ausgelöst, sofern Event.preventDefault nicht aufgerufen wird:

1. Zuerst wird ein keydown-Ereignis ausgelöst. Wenn die Taste weiter gedrückt gehalten wird und ein Zeichen erzeugt, wird das Ereignis anschließend in einem von der Plattformimplementierung abhängigen Intervall wiederholt ausgelöst. Dabei wird die schreibgeschützte Eigenschaft KeyboardEvent.repeat auf true gesetzt.
2. Wenn die Taste ein Zeichen erzeugt, das beispielsweise in ein <input>-, ein <textarea>- oder ein Element eingefügt würde, dessen HTMLElement.contentEditable auf true gesetzt ist, werden die Ereignistypen beforeinput und input in dieser Reihenfolge ausgelöst. Beachten Sie, dass einige andere Implementierungen auch ein keypress-Ereignis auslösen können, sofern es unterstützt wird. Solange die Taste gedrückt gehalten wird, werden die Ereignisse wiederholt ausgelöst.
3. Sobald die Taste losgelassen wird, wird ein keyup-Ereignis ausgelöst. Damit ist der Vorgang abgeschlossen.

Bei den Schritten 1 und 3 ist das Attribut KeyboardEvent.key definiert und wird gemäß den zuvor beschriebenen Regeln auf den entsprechenden Wert gesetzt.

Beispiele

Beispiel für die KeyboardEvent-Abfolge

Betrachten wir die Ereignisabfolge, die entsteht, wenn wir die Tasten Shift und 2 auf einer US-amerikanischen Tastatur verwenden, und vergleichen sie mit der Abfolge auf einer britischen Tastatur.

Probieren Sie die folgenden beiden Testfälle aus:

1. Halten Sie die Shift-Taste gedrückt, drücken Sie dann 2 und lassen Sie diese Taste wieder los. Lassen Sie anschließend die Shift-Taste los.
2. Halten Sie die Shift-Taste gedrückt und halten Sie dann auch 2 gedrückt. Lassen Sie die Shift-Taste los. Lassen Sie schließlich 2 los.

HTML

<div class="fx">
  <div>
    <textarea rows="5" name="test-target" id="test-target"></textarea>
    <button type="button" name="btn-reset" id="btn-reset">Reset</button>
  </div>
  <div class="flex">
    <pre id="console-log"></pre>
  </div>
</div>

CSS

.fx {
  -webkit-display: flex;
  display: flex;
  margin-left: -20px;
  margin-right: -20px;
}

.fx > div {
  padding-left: 20px;
  padding-right: 20px;
}

.fx > div:first-child {
  width: 30%;
}

.flex {
  -webkit-flex: 1;
  flex: 1;
}

#test-target {
  display: block;
  width: 100%;
  margin-bottom: 10px;
}

JavaScript

const textarea = document.getElementById("test-target");
const consoleLog = document.getElementById("console-log");
const btnReset = document.getElementById("btn-reset");

function logMessage(message) {
  consoleLog.innerText += `${message}\n`;
}

textarea.addEventListener("keydown", (e) => {
  if (!e.repeat) {
    logMessage(`Key "${e.key}" pressed [event: keydown]`);
  } else {
    logMessage(`Key "${e.key}" repeating [event: keydown]`);
  }
});

textarea.addEventListener("beforeinput", (e) => {
  logMessage(`Key "${e.data}" about to be input [event: beforeinput]`);
});

textarea.addEventListener("input", (e) => {
  logMessage(`Key "${e.data}" input [event: input]`);
});

textarea.addEventListener("keyup", (e) => {
  logMessage(`Key "${e.key}" released [event: keyup]`);
});

btnReset.addEventListener("click", (e) => {
  let child = consoleLog.firstChild;
  while (child) {
    consoleLog.removeChild(child);
    child = consoleLog.firstChild;
  }
  textarea.value = "";
});

Ergebnis

Fall 1

Wenn die Shift-Taste gedrückt wird, wird zunächst ein keydown-Ereignis ausgelöst und die Eigenschaft key auf den String Shift gesetzt. Während die Taste gedrückt gehalten wird, wird das keydown-Ereignis nicht wiederholt ausgelöst, da die Taste kein Zeichen erzeugt.

Wenn key 2 gedrückt wird, wird für diesen Tastendruck ein weiteres keydown-Ereignis ausgelöst. Wegen der aktiven Modifikatortaste shift wird die Eigenschaft key für das Ereignis bei einer US-amerikanischen Tastatur auf den String @ und bei einer britischen Tastatur auf " gesetzt. Anschließend werden die Ereignisse beforeinput und input ausgelöst, da ein Zeichen erzeugt wurde.

Wenn key 2 losgelassen wird, wird ein keyup-Ereignis ausgelöst. Die Eigenschaft key behält dabei für die beiden Tastaturlayouts den jeweiligen Stringwert @ beziehungsweise " bei.

Wenn schließlich die shift-Taste losgelassen wird, wird für sie ein weiteres keyup-Ereignis ausgelöst. Der Wert des Attributs key bleibt Shift.

Fall 2

Wenn die Shift-Taste gedrückt wird, wird zunächst ein keydown-Ereignis ausgelöst und die Eigenschaft key auf den String Shift gesetzt. Während die Taste gedrückt gehalten wird, wird das keydown-Ereignis nicht wiederholt ausgelöst, da die Taste kein Zeichen erzeugt.

Wenn key 2 gedrückt wird, wird für diesen Tastendruck ein weiteres keydown-Ereignis ausgelöst. Wegen der aktiven Modifikatortaste shift wird die Eigenschaft key für das Ereignis bei einer US-amerikanischen Tastatur auf den String @ und bei einer britischen Tastatur auf " gesetzt. Anschließend werden die Ereignisse beforeinput und input ausgelöst, da ein Zeichen erzeugt wurde. Während die Taste gedrückt gehalten wird, wird das keydown-Ereignis wiederholt ausgelöst und die Eigenschaft KeyboardEvent.repeat auf true gesetzt. Auch die Ereignisse beforeinput und input werden wiederholt ausgelöst.

Wenn die shift-Taste losgelassen wird, wird für sie ein keyup-Ereignis ausgelöst. Der Wert des Attributs key bleibt Shift. Beachten Sie, dass die Eigenschaft key des wiederholt ausgelösten keydown-Ereignisses für key 2 nun den Wert „2“ hat, da die Modifikatortaste shift nicht mehr aktiv ist. Das gilt auch für die Eigenschaft InputEvent.data der Ereignisse beforeinput und input.

Wenn schließlich key 2 losgelassen wird, wird ein keyup-Ereignis ausgelöst. Die Eigenschaft key hat bei beiden Tastaturlayouts den Stringwert 2, da die Modifikatortaste shift nicht mehr aktiv ist.

Unterschiedliche Aktionen je nach Tastentyp

Dieses Beispiel verwendet EventTarget.addEventListener(), um auf keydown-Ereignisse zu reagieren. Wenn ein solches Ereignis auftritt, wird geprüft, ob der Tastenwert zu den Tasten gehört, die für den Code relevant sind. Ist dies der Fall, wird er entsprechend verarbeitet – etwa um ein Raumschiff zu steuern oder die ausgewählte Zelle in einer Tabellenkalkulation zu ändern.

window.addEventListener("keydown", (event) => {
  if (event.defaultPrevented) {
    return; // Do nothing if the event was already processed
  }

  switch (event.key) {
    case "ArrowDown":
      // Do something for "down arrow" key press.
      break;
    case "ArrowUp":
      // Do something for "up arrow" key press.
      break;
    case "ArrowLeft":
      // Do something for "left arrow" key press.
      break;
    case "ArrowRight":
      // Do something for "right arrow" key press.
      break;
    case "Enter":
      // Do something for "enter" or "return" key press.
      break;
    case " ":
      // Do something for "space" key press.
      break;
    case "Escape":
      // Do something for "esc" key press.
      break;
    default:
      return; // Quit when this doesn't handle the key event.
  }

  // Cancel the default action to avoid it being handled twice
  event.preventDefault();
});

Spezifikationen

Browser-Kompatibilität