KeyboardEvent
Объекты 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
Non-standard Устарело Только для чтения-
Возвращает
DOMString
, представляющий символьное значение клавиши. Если клавиша соответствует печатному символу, то это значение будет непустой Unicode-строкой, содержащей этот символ. Если клавиша не имеет печатного представления, то значение будет пустой строкой. KeyboardEvent.charCode
Устарело Только для чтения-
Возвращает
Number
, представляющий Unicode-номер клавиши; этот атрибут использовался только с событиемkeypress
. Для клавиш, чейchar
-атрибут содержит несколько символов, то значением этого атрибута будет Unicode-значение первого символа. В Firefox 26 этот атрибут возвращал коды для печатных символов. KeyboardEvent.code
Только для чтения-
Возвращает
DOMString
с кодом клавиши, представленного события. KeyboardEvent.ctrlKey
Только для чтения-
Возвращает
Boolean
, котороеtrue
, если клавишаCtrl
была активна, когда возникло событие.
KeyboardEvent.isComposing
Только для чтения-
Возвращает
Boolean
, котороеtrue
, если событие возникло между "после-compositionstart
" и "до-compositionend
". KeyboardEvent.key
Только для чтения-
Возвращает
DOMString
, представляющее значение клавиши, на которой возникло событие. KeyboardEvent.keyCode
Устарело Только для чтения-
Возвращает
Number
, представляющее системный и зависящий от конкретной реализации числовой код, идентифицирующий немодифицированное значение нажатой клавиши. KeyboardEvent.keyIdentifier
Non-standard Устарело Только для чтения-
Это свойство нестандартное, и его использование не рекомендуется в пользу
KeyboardEvent.key
. Это часть устаревшего "DOM Level 3 Events". KeyboardEvent.keyLocation
Non-standard Устарело Только для чтения-
Это нестандартный нерекомендуемый синоним для
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
.
Примечания
Особенности событий 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
; это являлось нестабильным поведением и описано в Firefox bug 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 обработка событий клавиатуры была различна на разных платформах.
- 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>
Спецификации
Specification |
---|
UI Events # interface-keyboardevent |
Совместимость с браузерами
BCD tables only load in the browser