KeyboardEvent: свойство key

Свойство key только для чтения интерфейса KeyboardEvent возвращает значение нажатой пользователем клавиши, учитывая состояние клавиш-модификаторов, таких как Shift, а также локаль и раскладку клавиатуры.

Строка.

Его значение определяется следующим образом:

• Если нажатая клавиша имеет печатное представление, возвращаемое значение — это непустая строка Unicode, содержащая печатное представление клавиши. Например: если нажата клавиша Space, возвращаемое значение — один пробел (" "). Если нажата клавиша B, возвращаемое значение — строка "b". Однако, если одновременно нажата клавиша Shift (так что shiftKey равно true), возвращаемое значение — строка "B".
• Если нажатая клавиша — управляющий или специальный символ, возвращаемое значение — одно из предопределённых значений клавиш из списка.
• Если KeyboardEvent представляет нажатие мертвой клавиши, значение клавиши должно быть "Dead".
• Некоторые специальные клавиши клавиатуры (например, расширенные клавиши для управления медиа на мультимедийных клавиатурах) не генерируют коды клавиш в Windows; вместо этого они вызывают события WM_APPCOMMAND. Эти события отображаются в события клавиатуры DOM и перечислены среди «виртуальных кодов клавиш» для Windows, даже если они фактически не являются кодами клавиш.
• Если клавишу невозможно идентифицировать, возвращаемое значение — Unidentified.

Каждое KeyboardEvent срабатывает в предопределённой последовательности. Для нажатия клавиши последовательность срабатывания KeyboardEvent выглядит следующим образом, при условии, что не вызывается Event.preventDefault:

1. Сначала срабатывает событие keydown. Если клавиша удерживается, и она генерирует символьную клавишу, то событие продолжает генерироваться с интервалом, зависящим от реализации платформы, и свойство KeyboardEvent.repeat устанавливается в true.
2. Если клавиша генерирует символьную клавишу, которая должна вставлять символ в, возможно, <input>, <textarea> или элемент с HTMLElement.contentEditable, установленным в true, срабатывают события типов beforeinput и input в указанном порядке. Обратите внимание, что в некоторых других реализациях может срабатывать событие keypress, если оно поддерживается. События будут срабатывать повторно, пока клавиша удерживается.
3. После того, как клавиша отпущена, срабатывает событие keyup. Это завершает процесс.

В последовательности 1 и 3 атрибут KeyboardEvent.key определён и установлен соответствующим значением в соответствии с ранее определёнными правилами.

Рассмотрим последовательность событий, генерируемых при взаимодействии с клавишей Shift и 2 с использованием раскладки клавиатуры США по сравнению с раскладкой клавиатуры Великобритании.

Попробуйте провести эксперимент, используя следующие два тестовых случая:

1. Нажмите и удерживайте клавишу Shift, затем нажмите 2 и отпустите её. Затем отпустите клавишу Shift.
2. Нажмите и удерживайте клавишу Shift, затем нажмите и удерживайте 2. Отпустите клавишу Shift. Наконец, отпустите 2.

Когда нажата клавиша shift, сначала срабатывает событие keydown, и значение свойства key устанавливается в строку Shift. При дальнейшем удерживании этой клавиши событие keydown не срабатывает повторно, потому что оно не генерирует символьную клавишу.

Когда нажимается key 2, срабатывает ещё одно событие keydown для этого нового нажатия клавиши, и значение свойства key для события устанавливается в строку @ для раскладки клавиатуры США и " для раскладки клавиатуры Великобритании, из-за активной клавиши-модификатора shift. Далее срабатывают события beforeinput и input, поскольку была сгенерирована символьная клавиша.

Когда мы отпускаем key 2, срабатывает событие keyup, и свойство key сохраняет строковые значения @ и " соответственно для различных раскладок клавиатуры.

Когда мы наконец отпускаем клавишу shift, для неё срабатывает ещё одно событие keyup, и значение атрибута клавиши остаётся Shift.

При нажатии клавиши shift сначала срабатывает событие keydown, и значение свойства key устанавливается в строку Shift. При дальнейшем удерживании этой клавиши событие keydown не срабатывает повторно, так как оно не генерирует символьную клавишу.

При нажатии key 2, срабатывает ещё одно событие keydown для этого нового нажатия клавиши, и значение свойства key для события устанавливается в строку @ для раскладки клавиатуры США и " для раскладки клавиатуры Великобритании из-за активной клавиши-модификатора shift. Далее срабатывают события beforeinput и input, поскольку была сгенерирована символьная клавиша. При удерживании клавиши событие keydown срабатывает повторно, а свойство KeyboardEvent.repeat устанавливается в true. События beforeinput и input также срабатывают повторно.

При отпускании клавиши shift, срабатывает событие keyup, и значение атрибута клавиши остаётся Shift. В этот момент обратите внимание, что значение свойства key для повторяющегося события keydown нажатия клавиши key 2 теперь равно "2", поскольку клавиша-модификатор shift больше не активна. То же самое касается свойства InputEvent.data событий beforeinput и input.

При окончательном отпускании клавиши key 2, срабатывает событие keyup, но свойство key будет установлено в строковое значение 2 для обеих раскладок клавиатуры, поскольку клавиша-модификатор shift больше не активна.

В этом примере используется EventTarget.addEventListener() для прослушивания событий keydown. При их возникновении значение клавиши проверяется на соответствие интересующим кодам, и если да, то оно обрабатывается каким-то образом (возможно, управлением космическим кораблём или изменением выделенной ячейки в таблице).

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();
  },
  true,
);