KeyboardEvent - Интерфейсы веб API | MDN

Toggle sidebar

Theme

OS default
Light
Dark

Русский

Remember language Learn more

KeyboardEvent

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since июль 2015 г..

* Some parts of this feature may have varying levels of support.

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

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

Конструктор

KeyboardEvent()

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

Методы

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

KeyboardEvent.getModifierState()

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

Alt

Shift

Ctrl

или

Свойства

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

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

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

Alt

(

Option

или

⌥

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

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

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

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

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

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

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

Возвращает DOMString, представляет строку-локаль, которая показывает текущую конфигурацию локали клавиатуры. Это может быть пустая строка, если браузер или устройство не имеют понятия о локали клавиатуры.

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

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

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

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

Примечания

Особенности событий 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-тип, так и свои собственные модели поведения.

Пример

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>

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 27 окт. 2025 г. by MDN contributors.

View this page on GitHub • Report a problem with this content

UI Events
KeyboardEvent
Конструктор
1. KeyboardEvent()
Свойства экземпляра
Методы экземпляра
1. getModifierState()
2. initKeyboardEvent()
Наследование
1. UIEvent
2. Event
Похожие страницы для UI Events
Руководства
1. Code values for keyboard events
2. Значения клавиш

KeyboardEvent

In this article

Конструктор

Методы

Свойства

Примечания

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

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

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

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

Пример

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

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

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

Help improve MDN