KeyboardEvent: key-Eigenschaft

Wert

Ein String.

Der Wert wird wie folgt bestimmt:

• Wenn die gedrückte Taste eine gedruckte Darstellung hat, ist der zurückgegebene Wert ein nicht-leerer Unicode-Zeichenketten-String, der die druckbare Darstellung der Taste enthält. Zum Beispiel: Wenn die gedrückte Taste die Leertaste ist, ist der zurückgegebene Wert ein einzelnes Leerzeichen (" "). Wenn die gedrückte Taste die B-Taste ist, ist der zurückgegebene Wert der String "b". Wenn jedoch gleichzeitig die Shift-Taste gedrückt wird (also shiftKey true ist), ist der zurückgegebene Wert der String "B".
• Bei Steuerungs- oder Sonderzeichen ist der zurückgegebene Wert einer der vordefinierten Schlüsselwerte.
• Wenn das KeyboardEvent das Drücken einer Dead Key darstellt, muss der Schlüsselwert "Dead" sein.
• Einige Spezialtasten auf Tastaturen (wie die erweiterten Tasten zur Mediensteuerung auf Multimedia-Tastaturen) erzeugen keine Tastencodes unter Windows; stattdessen lösen sie WM_APPCOMMAND-Ereignisse aus. Diese Ereignisse werden auf DOM-Tastaturereignisse abgebildet und sind unter den "Virtuellen Tastencodes" für Windows aufgeführt, obwohl sie tatsächlich keine Tastencodes sind.
• Wenn die Taste nicht identifiziert werden kann, ist der zurückgegebene Wert Unidentified.

Tastaturereignisse-Sequenz

Jedes KeyboardEvent wird in einer vorbestimmten Reihenfolge ausgelöst. Für ein gegebenes Tastendruck wird die Reihenfolge der ausgelösten KeyboardEvents wie folgt festgelegt, vorausgesetzt, dass Event.preventDefault nicht aufgerufen wird:

1. Ein keydown-Ereignis wird zuerst ausgelöst. Wenn die Taste weiter gedrückt gehalten wird und die Taste ein Zeichen erzeugt, wird das Ereignis in einem vom Plattform-Implementierung abhängigen Intervall weiter ausgelöst und die schreibgeschützte Eigenschaft KeyboardEvent.repeat wird auf true gesetzt.
2. Wenn die Taste ein Zeichen erzeugt, das möglicherweise in ein <input>, <textarea> oder ein Element mit HTMLElement.contentEditable auf true, eingefügt würde, werden die Ereignistypen beforeinput und input in dieser Reihenfolge ausgelöst. Beachten Sie, dass einige andere Implementierungen das keypress-Ereignis auslösen können, wenn es unterstützt wird. Die Ereignisse werden wiederholt ausgelöst, während die Taste gedrückt gehalten wird.
3. Ein keyup-Ereignis wird ausgelöst, sobald die Taste losgelassen wird. Dies schließt den Vorgang ab.

In den Sequenzen 1 & 3 ist das Attribut KeyboardEvent.key definiert und wird gemäß den zuvor definierten Regeln entsprechend auf einen Wert gesetzt.

Beispiel einer Tastaturereignisse-Sequenz

Betrachten Sie die Ereignisse-Reihenfolge, die erzeugt wird, wenn wir mit der Shift- und der 2-Taste interagieren, und zwar sowohl mit einem US-amerikanischen Tastaturlayout als auch mit einem UK-Tastaturlayout.

Versuchen Sie, mit den folgenden zwei Testfällen zu experimentieren:

1. Drücken und halten Sie die Shift-Taste, dann drücken Sie 2 und lassen sie sie los. Lassen Sie dann die Shift-Taste los.
2. Drücken und halten Sie die Shift-Taste, dann drücken und halten Sie 2. Lassen Sie die Shift-Taste los. Schließlich lassen Sie 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 zuerst ein keydown-Ereignis ausgelöst und der key-Eigenschaftswert wird auf den String Shift gesetzt. So lange wir diese Taste gedrückt halten, wird das keydown-Ereignis nicht wiederholt ausgelöst, da es keinen Zeichenwert erzeugt.

Wenn die Taste 2 gedrückt wird, wird ein weiteres keydown-Ereignis für dieses neue Drücken ausgelöst und der key-Eigenschaftswert des Ereignisses wird auf den String @ für die US-amerikanische Tastaturart und " für die UK-Tastaturart gesetzt, aufgrund der aktiven Modifikator-Taste shift. Die beforeinput- und input-Ereignisse werden als nächstes ausgelöst, weil ein Zeichenwert erzeugt wurde.

Sobald wir die Taste 2 loslassen, wird ein keyup-Ereignis ausgelöst und die key-Eigenschaft behält den String-Wert @ und " für die unterschiedlichen Tastaturlayouts.

Wenn wir schließlich die shift-Taste loslassen, wird ein weiteres keyup-Ereignis für sie ausgelöst, und der Schlüsselattributwert bleibt Shift.

Fall 2

Wenn die Shift-Taste gedrückt wird, wird zuerst ein keydown-Ereignis ausgelöst und der key-Eigenschaftswert wird auf den String Shift gesetzt. So lange wir diese Taste gedrückt halten, wird das keydown-Ereignis nicht wiederholt ausgelöst, da es keinen Zeichenwert erzeugt.

Wenn die Taste 2 gedrückt wird, wird ein weiteres keydown-Ereignis für dieses neue Drücken ausgelöst und der key-Eigenschaftswert des Ereignisses wird auf den String @ für die US-amerikanische Tastaturart und " für die UK-Tastaturart gesetzt, aufgrund der aktiven Modifikator-Taste shift. Die beforeinput- und input-Ereignisse werden als nächstes ausgelöst, weil ein Zeichenwert erzeugt wurde. So lange wir die Taste gedrückt halten, wird das keydown-Ereignis weiterhin wiederholt ausgelöst und die KeyboardEvent.repeat-Eigenschaft wird auf true gesetzt. Die beforeinput- und input-Ereignisse werden ebenfalls wiederholt ausgelöst.

Sobald wir die shift-Taste loslassen, wird ein keyup-Ereignis für sie ausgelöst und der Schlüsselattributwert bleibt Shift. An diesem Punkt wird der key-Eigenschaftswert für das wiederholte Keydown-Ereignis des key 2-Tastendrucks jetzt "2" sein, da die Modifikatortaste shift nicht mehr aktiv ist. Gleiches gilt für die InputEvent.data-Eigenschaft der beforeinput- und input-Ereignisse.

Sobald wir die Taste 2 schließlich loslassen, wird ein keyup-Ereignis ausgelöst, aber die key-Eigenschaft wird auf den String-Wert 2 für beide Tastaturlayouts gesetzt, da die Modifikatortaste shift nicht mehr aktiv ist.

Beispiele

Dieses Beispiel verwendet EventTarget.addEventListener(), um auf keydown-Ereignisse zu horchen. Wenn sie auftreten, wird der Wert der Taste überprüft, um festzustellen, ob es sich um eine der Tasten handelt, an der der Code interessiert ist. Wenn ja, wird sie in irgendeiner Weise verarbeitet (möglicherweise durch Steuern eines Raumfahrzeugs oder durch Ändern der ausgewählten Zelle in einer Tabellenkalkulation).

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