KeyboardEvent
=============

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

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

Конструктор
-----------

`KeyboardEvent()` (en-US)

Создаёт объект `KeyboardEvent`.

Методы
------

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

`KeyboardEvent.getModifierState()` (en-US)

Возвращает `Boolean`, показывающий, что использовалась клавиша-модификатор, такая как

`Alt`

,

`Shift`

,

`Ctrl`

или

`Meta`

, которая была нажата, когда создалось событие.

`KeyboardEvent.initKeyEvent()` (en-US)
Устарело

Инициализирует объект `KeyboardEvent`. Этот метод реализован только в движке Gecko (остальные использовали метод `KeyboardEvent.initKeyboardEvent()` (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора `KeyboardEvent()` (en-US).

`KeyboardEvent.initKeyboardEvent()` (en-US)
Устарело

Инициализирует объект `KeyboardEvent`. Этот метод никогда не был реализован в движке Gecko (вместо него использовался `KeyboardEvent.initKeyEvent()` (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора `KeyboardEvent()` (en-US).

Свойства
--------

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

`KeyboardEvent.altKey` Только для чтения 

Возвращает `Boolean`, которое `true`, если клавиша

`Alt`

(

`Option`

или

`⌥`

в OS X) была активна, когда возникло событие.

`KeyboardEvent.char` 
Non-standard

Устарело
Только для чтения 

Возвращает `DOMString`, представляющий символьное значение клавиши. Если клавиша соответствует печатному символу, то это значение будет непустой Unicode-строкой, содержащей этот символ. Если клавиша не имеет печатного представления, то значение будет пустой строкой.

**Примечание:** Если клавиша использовалась как макрос, который вставляет несколько символов, то значением будет вся строка, а не только первый символ.

**Предупреждение:** Эта функция была удалена из событий "DOM Level 3 Events". Она поддерживается только IE9+ и Microsoft Edge.

`KeyboardEvent.charCode` (en-US) 
Устарело
Только для чтения 

Возвращает `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) 
Устарело
 Только для чтения 

Возвращает `Number`, представляющее системный и зависящий от конкретной реализации числовой код, идентифицирующий немодифицированное значение нажатой клавиши.

**Предупреждение:** Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо него `KeyboardEvent.key`.

`KeyboardEvent.keyIdentifier` (en-US) 
Non-standard

Устарело
Только для чтения 

Это свойство нестандартное, и его использование не рекомендуется в пользу `KeyboardEvent.key`. Это часть устаревшего "DOM Level 3 Events".

`KeyboardEvent.keyLocation` 
Non-standard

Устарело
Только для чтения 

Это нестандартный нерекомендуемый синоним для `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` 
Устарело
 Только для чтения 

Возвращает `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`; это являлось нестабильным поведением и описано в Firefox bug 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 обработка событий клавиатуры была различна на разных платформах.

Windows

Поведение автоповтора такое же как в Gecko 4.0 и более поздних.

Mac

После первого события `keydown` только отправляются события `keypress` до тех пор, пока не произойдёт событие `keyup`; внутриинтервальные события `keydown` не отправляются.

Linux

Поведение событий зависит от конкретной платформы. Они могут иметь как Windows-тип и Mac-тип, так и свои собственные модели поведения.


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

Пример
------


```html
<!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 with JavaScript enabled. Enable JavaScript to view data.

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

* `KeyboardEvent.code` (en-US).
* `KeyboardEvent.key`.
* `KeyboardEvent.getModifierState` (en-US)