KeyboardEvent

Базовая Широко поддерживается *

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с июля 2015 года.

* Некоторые части этой функции могут иметь различный уровень поддержки.

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

Примечание: KeyboardEvent события просто указывают, какое взаимодействие пользователь имел с клавишей на клавиатуре на низком уровне, не предоставляя контекстного значения этому взаимодействию. Если вам нужно обработать ввод текста, используйте событие input вместо него. События клавиатуры могут не срабатывать, если пользователь использует альтернативный способ ввода текста, например, систему рукописного ввода на планшете или графическом планшете.

Конструктор

KeyboardEvent(): Создаёт новый объект KeyboardEvent.

Константы

Интерфейс KeyboardEvent определяет следующие константы.

Расположения клавиш

Следующие константы определяют, из какой части клавиатуры происходит событие клавиши. К ним можно обращаться как KeyboardEvent.DOM_KEY_LOCATION_STANDARD и так далее.

Идентификаторы расположения клавиш
Константа	Значение	Описание
`DOM_KEY_LOCATION_STANDARD`	0x00	Клавиша, описываемая событием, не распознана как находящаяся в определённой области клавиатуры; она не расположена на цифровом блоке (если это не клавиша NumLock), и для клавиш, дублированных слева и справа на клавиатуре, клавиша по какой-то причине не должна быть связана с этим расположением. Примеры включают буквенно-цифровые клавиши на стандартной PC 101 US клавиатуре, клавишу NumLock и пробел.
`DOM_KEY_LOCATION_LEFT`	0x01	Клавиша может находиться в нескольких местах на клавиатуре и в этом случае расположена слева на клавиатуре. Примеры включают левую клавишу Control, левую клавишу Command на клавиатуре Macintosh или левую клавишу Shift.
`DOM_KEY_LOCATION_RIGHT`	0x02	Клавиша может находиться в нескольких местах на клавиатуре и в этом случае расположена справа на клавиатуре. Примеры включают правую клавишу Shift и правую клавишу Alt (Option на клавиатуре Mac).
`DOM_KEY_LOCATION_NUMPAD`	0x03	Клавиша расположена на цифровом блоке или является виртуальной клавишей, связанной с цифровым блоком, если клавиша может исходить из нескольких мест. Клавиша NumLock не относится к этой группе и всегда кодируется расположением `DOM_KEY_LOCATION_STANDARD`. Примеры включают цифры на цифровом блоке, клавишу Enter на цифровом блоке и десятичную точку на цифровом блоке.

Свойства экземпляра

Этот интерфейс также наследует свойства своих родительских интерфейсов, UIEvent и Event.

KeyboardEvent.altKey Только для чтения: Возвращает логическое значение, которое true если клавиша Alt (Option или ⌥ на macOS) была активна при генерации события клавиши.
KeyboardEvent.code Только для чтения: Возвращает строку со значением кода физической клавиши, представленной событием.

Предупреждение: Это игнорирует раскладку клавиатуры пользователя, поэтому если пользователь нажимает клавишу в позиции «Y» в раскладке QWERTY (около середины строки над основной строкой), это всегда будет возвращать «KeyY», даже если у пользователя раскладка QWERTZ (что означало бы, что пользователь ожидает «Z», и все другие свойства указывали бы на «Z») или раскладка Dvorak (где пользователь ожидал бы «F»). Если вы хотите отобразить правильные нажатия клавиш пользователю, вы можете использовать Keyboard.getLayoutMap().
KeyboardEvent.ctrlKey Только для чтения: Возвращает логическое значение, которое true если клавиша Ctrl была активна при генерации события клавиши.
KeyboardEvent.isComposing Только для чтения: Возвращает логическое значение, которое true если событие срабатывает между после compositionstart и до compositionend.
KeyboardEvent.key Только для чтения: Возвращает строку, представляющую значение клавиши, представленное событием.
KeyboardEvent.location Только для чтения: Возвращает число, представляющее расположение клавиши на клавиатуре или другом устройстве ввода. Список констант, определяющих расположения, показан выше в разделе Расположения клавиш.
KeyboardEvent.metaKey Только для чтения: Возвращает логическое значение, которое true если клавиша Meta (на клавиатурах Mac – клавиша ⌘ Command; на клавиатурах Windows – клавиша Windows (⊞)) была активна при генерации события клавиши.
KeyboardEvent.repeat Только для чтения: Возвращает логическое значение, которое true если клавиша удерживается, так что она автоматически повторяется.
KeyboardEvent.shiftKey Только для чтения: Возвращает логическое значение, которое true если клавиша Shift была активна при генерации события клавиши.

Устаревшие свойства

KeyboardEvent.charCode Устаревшее Только для чтения: Возвращает число, представляющее числовое значение Юникода клавиши; это свойство используется только для события keypress. Для клавиш, чьё свойство char содержит несколько символов, это значение Юникода первого символа в этом свойстве. В Firefox 26 это возвращает коды для печатаемых символов.
KeyboardEvent.keyCode Устаревшее Только для чтения: Возвращает число, представляющее зависящий от системы и реализации числовой код, идентифицирующий значение нажатой клавиши без модификаторов.
KeyboardEvent.keyIdentifier Нестандартно Устаревшее Только для чтения: Это свойство нестандартно и устарело в пользу KeyboardEvent.key. Оно было частью старой версии DOM Level 3 Events.

Методы экземпляра

Этот интерфейс также наследует методы своих родительских интерфейсов, UIEvent и Event.

KeyboardEvent.getModifierState(): Возвращает логическое значение, указывающее, была ли нажата клавиша-модификатор, такая как Alt, Shift, Ctrl или Meta, при создании события.

Устаревшие методы

KeyboardEvent.initKeyEvent() Устаревшее: Инициализирует объект KeyboardEvent. Эта функция была реализована только в Firefox и больше не поддерживается; вместо неё следует использовать конструктор KeyboardEvent().
KeyboardEvent.initKeyboardEvent() Устаревшее: Инициализирует объект KeyboardEvent. Эта функция теперь устарела. Вместо неё следует использовать конструктор KeyboardEvent().

События

Следующие события основаны на типе KeyboardEvent. В списке ниже каждое событие ссылается на документацию обработчика Element события, который применяется ко всем получателям, включая Element, Document и Window.

keydown: Нажата клавиша.
keyup: Клавиша отпущена.

Устаревшие события

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

Примечания по использованию

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

При первом нажатии клавиши отправляется событие keydown.
Если клавиша не является модификатором, отправляется событие keypress.
При отпускании клавиши отправляется событие keyup.

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

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

Примечание: В Linux Firefox 12 и более ранних версиях для этих клавиш также отправлялось событие keypress.

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

Обработка автоповтора

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

keydown
keypress
keydown
keypress
<<повторяется до отпускания клавиши пользователем>>
keyup

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

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

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

keydown
keypress
keyup
keydown
keypress
keyup
<<повторяется до отпускания клавиши пользователем>>
keyup

В этих средах, к сожалению, веб-контент не может отличить автоповторяющиеся клавиши от просто повторяемых нажатий.

Пример

document.addEventListener(
  "keydown",
  (event) => {
    const keyName = event.key;

    if (keyName === "Control") {
      // do not alert when only Control key is pressed.
      return;
    }

    if (event.ctrlKey) {
      // Even though event.key is not 'Control' (e.g., 'a' is pressed),
      // event.ctrlKey may be true if Ctrl key is pressed at the same time.
      alert(`Combination of ctrlKey + ${keyName}`);
    } else {
      alert(`Key pressed ${keyName}`);
    }
  },
  false,
);

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

    // As the user releases the Ctrl key, the key is no longer active,
    // so event.ctrlKey is false.
    if (keyName === "Control") {
      alert("Control key was released");
    }
  },
  false,
);

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

Спецификация
События UI # interface-keyboardevent

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

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

	Настольный					Мобильный
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на IOS	Samsung Internet	WebView Android
`KeyboardEvent`	26	12	31	15	7	26	31	14	7	1.5	4.4
`KeyboardEvent`	1	12	1.5	≤12.1	1.2	18	4	≤12.1	1	1.0	≤37
`altKey`	1	12	1.5	≤12.1	1.2	18	4	≤12.1	1	1.0	≤37
`charCode`	1	12	1.5	12.1	1.2	18	4	12.1	1	1.0	≤37
`code`	48	79	38	35	10.1	48 Значение всегда пустое.	38 Значение всегда пустое.	35 Значение всегда пустое.	10.3	5.0 Значение всегда пустое.	48 Значение всегда пустое.
`ctrlKey`	1	12	1.5	≤12.1	1.2	18	4	≤12.1	1	1.0	≤37
`getModifierState`	30	12	15	17	10.1	30	15	18	10.3	2.0	4.4
`initKeyboardEvent`	1	12	57	≤12.1	1.2	18	57	≤12.1	1	1.0	≤37
`isComposing`	56	79	31	43	10.1	56	31	43	10.3	6.0	56
`key`	51	12	23	38	10.1	51	23	41	10.3	5.0	51
`keyCode`	1	12	1.5	12.1	1.2	18	4	12.1	1	1.0	≤37
`keyIdentifier`	26–54	Нет	Нет	15–41	1.2	26–54	Нет	14–41	1	1.5–6.0	4.4–54
`location`	30	12	15	17	8	30	15	18	8	2.0	4.4
`metaKey`	1	12	1.5 Начиная с Firefox 48, клавиша Windows больше не обрабатывается как клавиша `meta`.	≤12.1	1.2	18	4 Начиная с Firefox для Android 48, клавиша Windows больше не обрабатывается как клавиша `meta`.	≤12.1	1	1.0	≤37
`repeat`	32 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.	12	28	19 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.	10.1	32 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.	28	19 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.	10.3	2.0 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.	4.4.3 В Windows и Linux, если нажато несколько клавиш, событие `keydown` для последней нажатой клавиши сработает с неправильно установленным `repeat` в `false`. См. ошибку 40940886.
`shiftKey`	1	12	1.5	≤12.1	1.2	18	4	≤12.1	1	1.0	≤37

Примечания о совместимости

Начиная с Firefox 65, событие keypress больше не генерируется для непечатаемых клавиш (ошибка Firefox 968056), за исключением клавиши Enter, а также комбинаций клавиш Shift + Enter и Ctrl + Enter (они были сохранены для обеспечения кросс-браузерной совместимости).

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent