Объекты
KeyboardEvent
описывают работу пользователя с клавиатурой. Каждое событие описывает клавишу; тип события (keydown
, keypress
или keyup
) определяет произведённый тип действия.
KeyboardEvent
сообщит только о том, что на клавише произошло событие. Когда вам нужно обрабатывать ввод текста, то вместо него используйте "HTML5 input"
-событие. Например, если пользователь вводит текст рукописным способом, предположим с планшета, то события клавиш могут не возникать.Конструктор
KeyboardEvent()
- Создаёт объект
KeyboardEvent
.
Методы
Этот интерфейс также наследует методы от своих родителей: UIEvent
и Event
.
KeyboardEvent.getModifierState()
- Возвращает
Boolean
, показывающий, что использовалась клавиша-модификатор, такая как Alt, Shift, Ctrl или Meta, которая была нажата, когда создалось событие. KeyboardEvent.initKeyEvent()
- Инициализирует объект
KeyboardEvent
. Этот метод реализован только в движке Gecko (остальные использовали методKeyboardEvent.initKeyboardEvent()
), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктораKeyboardEvent()
. KeyboardEvent.initKeyboardEvent()
- Инициализирует объект
KeyboardEvent
. Этот метод никогда не был реализован в движке Gecko (вместо него использовалсяKeyboardEvent.initKeyEvent()
), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктораKeyboardEvent()
.
Свойства
Этот интерфейс также наследует свойства от своих родителей: UIEvent
and Event
.
KeyboardEvent.altKey
Только для чтения- Возвращает
Boolean
, котороеtrue
, если клавиша Alt ( Option или ⌥ в OS X) была активна, когда возникло событие. KeyboardEvent.char
Только для чтения- Возвращает
DOMString
, представляющий символьное значение клавиши. Если клавиша соответствует печатному символу, то это значение будет непустой Unicode-строкой, содержащей этот символ. Если клавиша не имеет печатного представления, то значение будет пустой строкой.Примечание: Если клавиша использовалась как макрос, который вставляет несколько символов, то значением будет вся строка, а не только первый символ.Предупреждение: Эта функция была удалена из событий "DOM Level 3 Events". Она поддержтвается только IE9+ и Microsoft Edge. KeyboardEvent.charCode
Только для чтения- Возвращает
Number
, представляющий Unicode-номер клавиши; этот атрибут использовался только с событиемkeypress
. Для клавиш, чейchar
-атрибут содержит несколько символов, то значением этого атрибута будет Unicode-значение первого символа. В Firefox 26 этот атрибут возвращал коды для печатных символов.Предупреждение: Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо негоKeyboardEvent.key
. KeyboardEvent.code
Только для чтения- Возвращает
DOMString
с кодом клавиши, представленного события. KeyboardEvent.ctrlKey
Только для чтения- Возвращает
Boolean
, котороеtrue
, если клавиша Ctrl была активна, когда возникло событие. KeyboardEvent.isComposing
Только для чтения- Возвращает
Boolean
, котороеtrue
, если событие возникло между "после-compositionstart
" и "до-compositionend
". KeyboardEvent.key
Только для чтения- Возвращает
DOMString
, представлающее значение клавиши, на которой возникло событие. KeyboardEvent.keyCode
Только для чтения- Возвращает
Number
, представляющее системный и зависящий от конкретной реализации числовой код, идентифицирущий немодифицированное значение нажатой клавиши.Предупреждение: Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо негоKeyboardEvent.key
. KeyboardEvent.keyIdentifier
Только для чтения- Это свойство нестандартное, и его использование не рекомендуется в пользу
KeyboardEvent.key
. Это часть устаревшего "DOM Level 3 Events". KeyboardEvent.keyLocation
Только для чтения- Это нестандартный нерекомендуемый синоним для
KeyboardEvent.location
. Это часть устаревшего "DOM Level 3 Events". KeyboardEvent.locale
Только для чтения- Возвращает
DOMString
, представляет строку-локаль, которая показывает текущую конфигурацию локали клавиатуры. Это может быть пустая строка, если браузер или устройство не имеют понятия о локали клавиатуры.Заметьте: Это не описание языка ввода текста. Пользователь может использовать одну раскладку клавиатуры для ввода на разных языках. KeyboardEvent.location
Только для чтения- Возвращает
Number
, представляющее расположение клавиши на клавиатуре или другом устройстве ввода. KeyboardEvent.metaKey
Только для чтения- Возвращает
Boolean
, котороеtrue
, если клавиша Meta (на клавиатуре Mac - клавиша ⌘ Command; на Windows-клавиатуре - клавиша "Windows" ⊞) была активна, когда возникло событие. KeyboardEvent.repeat
Только для чтения- Возвращает
Boolean
, котороеtrue
, если клавиша была нажата до тех пор, пока её ввод не начал автоматически повторяться. KeyboardEvent.shiftKey
Только для чтения- Возвращает
Boolean
, котороеtrue
, если клавиша Shift была активна, когда возникло событие. KeyboardEvent.which
Только для чтения- Возвращает
Number
, представляющее зависящее от конкретной реализации значение системного кода нажатой клавиши, который представляет собой немодифицируемое значение; это обычно то же, что свойствоkeyCode
.Предупреждение: Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо негоKeyboardEvent.key
.
Примечания
Особенности событий keydown
, keypress
и keyup
. Для большинства клавиш Gecko обрабатывает последовательность событий так:
- Когда клавиша сначала нажата, то отправляется событие
keydown
. - Если клавиша не является модификатором, то отправляется событие
keypress
. - Когда пользователь отпускает клавишу, то отправляется событие
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.
Обработка автоповтора нажатой клавиши
Когда клавиша нажата и удерживается, то начинается автоповтор. Результатом этого будет последовательность событий аналогичная следующей:
keydown
keypress
keydown
keypress
- <<повтор до тех пор, пока пользователь не отпустит клавишу>>
keyup
Это то, что должно произойти в соответствии со спецификацией DOM Level 3. Однако, есть несколько предостережений относительно этого, описанных ниже.
Автоповтор на некоторых GTK-средах, таких как Ubuntu 9.4
В некоторых GTK-средах автоповтор обрабатывается автоматически нативными функциями как событие key-up, и у Gecko нет способа отличить серию одиночных нажатий от автоповтора. На таких платформах автоповтор генерирует следующую последовательность событий:
keydown
keypress
keyup
keydown
keypress
keyup
- <<повтор, пока пользователь не отпустит клавишу>>
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()
и в ранних версиях DOM Events Level 3 KeyboardEvent.initKeyboardEvent()
остальными браузерами. Но оба были заменены новой формой использования конструктора:KeyboardEvent()
.
Совместимость с браузерами
Возможность | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Базовая поддержка | (Да) | (Да) | (Да) | (Да) | (Да) | (Да) |
constructor | (Да) | ? | 31.0 (31.0) | Нет | (Да) | ? |
.char |
Нет | ? | Нет | 9 | Нет | Нет |
.charCode |
(Да) | ? | (Да) | (Да) | (Да) | (Да) |
.isComposing |
Нет | ? | 31.0 (31.0) | Нет | Нет | Нет |
.keyCode |
(Да) | ? | (Да) | (Да) | (Да) | (Да) |
.locale |
Нет | ? | Нет | (Да) | Нет | Нет |
.location |
(Да) | ? | 15.0 (15.0) | (Да) | Нет | Нет |
.repeat |
(Да) | ? | 28.0 (28.0) | (Да) | Нет | Нет |
.which |
(Да) | ? | (Да) | (Да) | (Да) | (Да) |
.initKeyboardEvent() |
(Да)[1] | ? | Нет[2] | 9.0[3] | ? | (Да)[1] |
Возможность | Android | Edge | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Базовая поддержка | ? | (Да) | (Да) | ? | ? | ? |
constructor | ? | ? | 31.0 (31.0) | ? | ? | ? |
.char |
? | ? | Нет | ? | ? | ? |
.charCode |
? | ? | (Да) | ? | ? | ? |
.isComposing |
Нет | ? | 31.0 (31.0) | Нет | Нет | Нет |
.keyCode |
? | ? | (Да) | ? | ? | ? |
.locale |
? | ? | Нет | ? | ? | ? |
.location |
? | ? | 15.0 (15.0) | ? | ? | ? |
.repeat |
? | ? | 28.0 (28.0) | ? | ? | ? |
.which |
? | ? | (Да) | ? | ? | ? |
.initKeyboardEvent() |
? | ? | Нет | ? | ? | ? |
[1] Аргументы функции initKeyboardEvent()
в WebKit и в Blink отличаются от определения в документе "DOM Level 3 Events". Эта функция выглядит так: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyIdentifierArg, in number locationArg, in boolean ctrlKeyArg, in boolean altKeyArg, in boolean shiftKeyArg, in boolean metaKeyArg, in boolean altGraphKeyArg)
[2] Gecko-движок не будет поддерживать initKeyboardEvent()
, потому что её поддержка полностью ломает определение фич вэб-приложений. Смотрите баг 999645.
[3] Аргументы initKeyboardEvent()
в IE отличаются от определения в документе "DOM Level 3 Events". Эта функция выглядит так: initKeyboardEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in views::AbstractView viewArg, in DOMString keyArg, in number locationArg, in DOMString modifierListArg, in boolean repeatArt, in DOMString locationArg)
. Смотрите документ о initKeyboardEvent()
на сайте MSDN.