KeyboardEvent

Объекты KeyboardEvent описывают работу пользователя с клавиатурой. Каждое событие описывает клавишу; тип события (keydown, keypress или keyup) определяет произведённый тип действия.

Примечание: KeyboardEvent сообщит только о том, что на клавише произошло событие. Когда вам нужно обрабатывать ввод текста, то вместо него используйте "HTML5 input" (en-US)-событие. Например, если пользователь вводит текст рукописным способом, предположим с планшета, то события клавиш могут не возникать.

Конструктор

KeyboardEvent() (en-US)
Создаёт объект KeyboardEvent.

Методы

Этот интерфейс также наследует методы от своих родителей: UIEvent (en-US) и Event.

KeyboardEvent.getModifierState() (en-US)
Возвращает Boolean, показывающий, что использовалась клавиша-модификатор, такая как AltShiftCtrl или Meta, которая была нажата, когда создалось событие.
KeyboardEvent.initKeyEvent() (en-US) Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать.
Инициализирует объект KeyboardEvent. Этот метод реализован только в движке Gecko (остальные использовали метод KeyboardEvent.initKeyboardEvent() (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора KeyboardEvent() (en-US).
KeyboardEvent.initKeyboardEvent() (en-US) Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать.
Инициализирует объект KeyboardEvent. Этот метод никогда не был реализован в движке Gecko (вместо него использовался KeyboardEvent.initKeyEvent() (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора KeyboardEvent() (en-US).

Свойства

Этот интерфейс также наследует свойства от своих родителей: UIEvent (en-US) and Event.

KeyboardEvent.altKey Только для чтения
Возвращает Boolean, которое true, если клавиша Alt ( Option или в OS X) была активна, когда возникло событие.
KeyboardEvent.char Это API не было стандартизировано. Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Возвращает DOMString, представляющий символьное значение клавиши. Если клавиша соответствует печатному символу, то это значение будет непустой Unicode-строкой, содержащей этот символ. Если клавиша не имеет печатного представления, то значение будет пустой строкой.
Примечание: Если клавиша использовалась как макрос, который вставляет несколько символов, то значением будет вся строка, а не только первый символ.
Предупреждение: Эта функция была удалена из событий "DOM Level 3 Events". Она поддерживается только IE9+ и Microsoft Edge.
KeyboardEvent.charCode (en-US) Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Возвращает Number, представляющий Unicode-номер клавиши; этот атрибут использовался только с событием keypress. Для клавиш, чей char-атрибут содержит несколько символов, то значением этого атрибута будет Unicode-значение первого символа. В Firefox 26 этот атрибут возвращал коды для печатных символов.
Предупреждение: Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо него KeyboardEvent.key.
KeyboardEvent.code (en-US) Только для чтения
Возвращает DOMString с кодом клавиши, представленного события.
KeyboardEvent.ctrlKey (en-US) Только для чтения
Возвращает Boolean, которое true, если клавиша  Ctrl была активна, когда возникло событие.
KeyboardEvent.isComposing (en-US) Только для чтения
Возвращает Boolean, которое true, если событие возникло между "после-compositionstart" и "до-compositionend".
KeyboardEvent.key Только для чтения
Возвращает DOMString, представляющее значение клавиши, на которой возникло событие.
KeyboardEvent.keyCode (en-US)  Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Возвращает Number, представляющее системный и зависящий от конкретной реализации числовой код, идентифицирующий немодифицированное значение нажатой клавиши.
Предупреждение: Это нерекомендуемый  к эксплуатации атрибут; по возможности вам нужно использовать вместо него KeyboardEvent.key.
KeyboardEvent.keyIdentifier (en-US) Это API не было стандартизировано. Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Это свойство нестандартное, и его использование не рекомендуется в пользу KeyboardEvent.key. Это часть устаревшего "DOM Level 3 Events".
KeyboardEvent.keyLocation Это API не было стандартизировано. Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Это нестандартный нерекомендуемый синоним для KeyboardEvent.location (en-US). Это часть устаревшего "DOM Level 3 Events".
KeyboardEvent.locale Только для чтения
Возвращает DOMString, представляет строку-локаль, которая показывает текущую конфигурацию локали клавиатуры. Это может быть пустая строка, если браузер или устройство не имеют понятия о локали клавиатуры.
Заметьте: Это не описание языка ввода текста. Пользователь может использовать одну раскладку клавиатуры для ввода на разных языках.
KeyboardEvent.location (en-US) Только для чтения
Возвращает Number, представляющее расположение клавиши на клавиатуре или другом устройстве ввода.
KeyboardEvent.metaKey (en-US) Только для чтения
Возвращает Boolean, которое true, если клавиша Meta (на клавиатуре Mac - клавиша ⌘ Command; на Windows-клавиатуре - клавиша "Windows" ) была активна, когда возникло событие.
KeyboardEvent.repeat (en-US) Только для чтения
Возвращает Boolean, которое true, если клавиша была нажата до тех пор, пока её ввод не начал автоматически повторяться.
KeyboardEvent.shiftKey (en-US) Только для чтения
Возвращает Boolean, которое true, если клавиша Shift была активна, когда возникло событие.
KeyboardEvent.which Это устаревшее API больше не должно использоваться, но оно по-прежнему может работать. Только для чтения
Возвращает Number, представляющее зависящее от конкретной реализации значение системного кода нажатой клавиши, который представляет собой немодифицируемое значение; это обычно то же, что свойство keyCode.
Предупреждение: Это нерекомендуемый  к эксплуатации атрибут; по возможности вам нужно использовать вместо него KeyboardEvent.key.

Примечания

Особенности событий keydown, keypress и keyup. Для большинства клавиш Gecko обрабатывает последовательность событий так:

  1. Когда клавиша сначала нажата, то отправляется событие keydown.
  2. Если клавиша не является модификатором, то отправляется событие keypress.
  3. Когда пользователь отпускает клавишу, то отправляется событие keyup.

Особые случаи

Некоторые клавиши переключают подсветку индикаторов, такие как Caps Lock, Num Lock и Scroll Lock. На Windows и Linux эти клавиши создают только лишь события keydown и keyup.

В Linux Firefox 12 и более ранних также обрабатывается событие keypress.

Но в связи с ограничениями Mac OS X модель событий клавиши Caps Lock включает в себя только keydown. События Num Lock поддерживались на старых ноутбуках (2007 года и старше), но затем Mac OS X их перестала поддерживать, даже на внешних клавиатурах. На совсем старых MacBooks клавиша Num Lock вообще не генерирует никаких событий. Движок Gecko не поддерживает клавишу Scroll Lock, если это внешняя клавиатура с клавишей F14. В некоторых старых версиях Firefox эта клавиша генерирует событие keypress; это являлось нестабильным поведением и описано в баг 602812.

Обработка автоповтора нажатой клавиши

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

  1. keydown
  2. keypress
  3. keydown
  4. keypress
  5. <<повтор до тех пор, пока пользователь не отпустит клавишу>>
  6. keyup

Это то, что должно произойти в соответствии со спецификацией DOM Level 3. Однако, есть несколько предостережений относительно этого, описанных ниже.

Автоповтор на некоторых GTK-средах, таких как Ubuntu 9.4

В некоторых GTK-средах автоповтор обрабатывается автоматически нативными функциями как событие key-up, и у Gecko нет способа отличить серию одиночных нажатий от автоповтора. На таких платформах автоповтор генерирует следующую последовательность событий:

  1. keydown
  2. keypress
  3. keyup
  4. keydown
  5. keypress
  6. keyup
  7. <<повтор, пока пользователь не отпустит клавишу>>
  8. keyup

В этих средах, к сожалению, нет возможности сказать веб-контенту, произошёл автоповтор или клавиша была нажата несколько раз.

Обработка автоповтора на системах до Gecko 5.0

До Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) обработка событий клавиатуры была различна на разных платформах.

Windows
Поведение автоповтора такое же как в Gecko 4.0 и более поздних.
Mac
После первого события keydown только отправляются события keypress до тех пор, пока не произойдёт событие keyup; внутриинтервальные события keydown не отправляются.
Linux
Поведение событий зависит от конкретной платформы. Они могут иметь как Windows-тип и Mac-тип, так и свои собственные модели поведения.

Замечание: при вызове события вручную не происходит никакого действия по умолчанию, связанного с данным событием. Например, если вызвать вручную событие нажатия клавиши, то никакая буква на поле вводимого текста не появится. В случае событий пользовательского интерфейса, что важно по соображениям безопасности, это предотвращает работу скриптов в браузере, которые эмулируют работу пользователя.

Пример

<!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) {
    // Хотя event.key это не 'Control' (например, нажата клавиша 'a'),
    // то всё же event.ctrlKey может быть true, если ударживается клавиша Ctrl.
    alert(`Combination of ctrlKey + ${keyName}`);
  } else {
    alert(`Key pressed ${keyName}`);
  }
}, false);

document.addEventListener('keyup', (event) => {
  const keyName = event.key;

  // Как только пользователь отпустит клавишу Ctrl, то она больше не будет активной.
  // Поэтому event.ctrlKey = false.
  if (keyName === 'Control') {
    alert('Control key was released');
  }
}, false);

</script>
</head>

<body>
</body>
</html>

Спецификации

Спецификация Статус Комментарий
Document Object Model (DOM) Level 3 Events Specification
Определение 'KeyboardEvent' в этой спецификации.
Устаревшая Первоначальное определение

Спецификация интерфейса KeyboardEvent прошла многочисленные черновые варианты, сперва в DOM Events Level 2, где её поддержка не добилась консенсуса, затем в DOM Events Level 3. Это привело к реализации нестандартных методов инициализации Gecko-браузерами в ранних версиях DOM Events Level 2 KeyboardEvent.initKeyEvent() (en-US) и в ранних версиях DOM Events Level 3 KeyboardEvent.initKeyboardEvent() (en-US) остальными браузерами. Но оба были заменены новой формой использования конструктора:KeyboardEvent() (en-US).

Совместимость с браузерами

BCD tables only load in the browser

Смотрите также