Элемент: событие keydown

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

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

Событие keydown срабатывает при нажатии клавиши.

В отличие от устаревшего события keypress, событие keydown срабатывает для всех клавиш, независимо от того, генерируют ли они символьное значение.

События keydown и keyup предоставляют код, указывающий, какая клавиша нажата, в то время как keypress указывает, какой символ был введен. Например, строчная буква "a" будет отображаться как 65 событиями keydown и keyup, но как 97 событием keypress. Заглавная буква "A" отображается как 65 всеми событиями.

Целевым объектом события клавиатуры является элемент, который в данный момент фокусирован и обрабатывает действия клавиатуры. Это включает в себя: <input>, <textarea>, всё, что имеет свойство contentEditable, а также все остальное, с чем можно взаимодействовать с помощью клавиатуры, например, <a>, <button> и <summary>. Если подходящий элемент не имеет фокуса, целевой объект будет <body> или корневой элемент. Если событие не обработано, оно передается вверх по дереву DOM до достижения Document.

Целевой объект события может меняться между разными событиями нажатия клавиш. Например, целевой объект для нажатия клавиши Tab будет отличаться от целевого объекта keyup, так как фокус изменился.

Синтаксис

Используйте имя события в методах, таких как addEventListener(), или задайте свойство обработчика события.

addEventListener("keydown", (event) => {});

onkeydown = (event) => {};

Тип события

Объект KeyboardEvent. Наследует от UIEvent и Event.

Свойства события

Этот интерфейс также наследует свойства своих родительских интерфейсов, 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 была активна при генерации события нажатия клавиши.

Примеры

Пример addEventListener keydown

В этом примере регистрируется значение KeyboardEvent.code каждый раз, когда вы нажимаете клавишу внутри элемента <input>.

<input placeholder="Click here, then press down a key." size="40" />
<p id="log"></p>

const input = document.querySelector("input");
const log = document.getElementById("log");

input.addEventListener("keydown", logKey);

function logKey(e) {
  log.textContent += ` ${e.code}`;
}

События keydown с IME

С Firefox 65 события keydown и keyup теперь срабатывают во время составления Input method editor, чтобы улучшить кроссбраузерную совместимость для пользователей CJKT (Ошибка Firefox 354358). Чтобы проигнорировать все события keydown, которые являются частью составления, сделайте следующее (229 — специальное значение, устанавливаемое для keyCode относящегося к событию, обработанному IME):

eventTarget.addEventListener("keydown", (event) => {
  if (event.isComposing || event.keyCode === 229) {
    return;
  }
  // do something
});

Примечание: compositionstart может срабатывать после keydown при вводе первого символа, открывающего IME, и compositionend может срабатывать до keydown при вводе последнего символа, закрывающего IME. В этих случаях isComposing ложно, даже когда событие является частью составления. Однако KeyboardEvent.keyCode все ещё 229 в этих случаях, поэтому все равно рекомендуется проверять keyCode, хотя оно устарело.

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

Спецификация
События UI # event-type-keydown
HTML # handler-onkeydown

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

	Рабочий стол					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`keydown_event`	1	12	6	≤12.1	1.2	18	6	≤12.1	1	1.0	4.4

См. также

© 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/Element/keydown_event