Просмотрщик кодов клавиш

Что такое просмотрщик кодов клавиш?#

Когда клавиша нажимается, браузер порождает KeyboardEvent, несущий два параллельных ответа на вопрос «какая клавиша?». Поле key говорит, какой символ произвело нажатие, — a, A, Enter, ?. Поле code говорит, какая физическая клавиша нажата, — KeyA, Enter, Slash — независимо от раскладки. Эти два ответа расходятся, как только появляется международная клавиатура, модификатор или цифровой блок, и именно это различие нужно видеть, когда вы вяжете шорткат, управление в игре или accessibility-функцию.

Эта страница захватывает каждое keydown в снимок и выворачивает наружу каждое поле: key, code, устаревшие числа keyCode и which (оставлены для отладки старого кода), location (стандартная / левая / правая / цифровой блок), активные модификаторы и было ли нажатие авто-повтором. Накатывающая история последних нажатий остаётся видимой, чтобы можно было отследить аккорд или последовательность.

Ничего глобального нет: захват идёт, только пока фокус внутри зоны захвата, поэтому остальная страница продолжает нормально слушаться клавиатуру.

Как пользоваться#

1. Щёлкните в любом месте пунктирной зоны захвата вверху (или перейдите в неё табом). Она подсветится, показывая, что слушает.
2. Нажмите клавишу или аккорд. Таблица-снимок ниже обновляется на каждое keydown.
3. Читайте строки:
   • key — логическое значение клавиши (символ или именованная клавиша, которую разобрал браузер).
   • code — физическая клавиша, не зависит от раскладки. Именно по ней сопоставляют шорткаты.
   • keyCode и which — устаревшие числовые коды с пометкой устарел. Сопоставляйте их только при портировании старого кода, который их ещё читает.
   • location — standard, left, right или numpad. Так вы отличаете левый Shift от правого или 5 цифрового блока от 5 верхнего ряда.
   • repeat — да, пока клавиша удерживается и авто-повторяется.
   • modifiers — значки для тех из Ctrl, Alt, Shift, Meta, кто был удержан.
4. Отметьте Блокировать действия клавиш по умолчанию в панели параметров, если хотите, чтобы страница не позволяла браузеру реагировать на клавишу (например, чтобы Tab не уводил фокус во время теста).
5. Используйте Копировать текущую, чтобы забрать текущий снимок, и Очистить историю на панели истории, чтобы сбросить накатывающийся список.

Ключевые возможности#

• key и code рядом. Самое полезное различие в обработке клавиатуры, видимое на каждом нажатии, — поэтому сразу ясно, почему key === "@" может прийти с Shift+Digit2 в одной раскладке и с совсем другой физической клавиши в другой.
• Учёт location. Левые и правые модификаторы отчитываются раздельно, а клавиши цифрового блока несут location: numpad. Это необходимо для игровых раскладок, где одна и та же цифра значит разное в основном ряду и на цифровом блоке.
• Значки модификаторов. Ctrl, Alt, Shift и Meta (Command на macOS, Super/Windows в других системах) показаны в общепринятом порядке, чтобы аккорд читался с одного взгляда.
• Устаревшие поля помечены явно. keyCode и which депрекированы и убраны из современных спецификаций, но много существующего кода их ещё читает. Они выведены с видимым тегом устарел и сноской, никогда — как первичный ответ.
• История из 20 записей. Удержите клавишу и следите, как repeat переключается на да при каждом авто-выстреле; нажмите последовательность — и пройдитесь по ней назад. Каждая запись — изолированный снимок.
• Захват в пределах зоны. Слушатель привязан к зоне захвата, а не к window. Остальная страница — табы, скролл — продолжает работать, пока вы снова не сфокусируете зону.

Разбор примера#

Классический источник путаницы — разница между 1 верхнего ряда и 1 цифрового блока. Они порождают один и тот же символ, но это разные клавиши.

Нажмите 1 верхнего ряда — и снимок покажет:

key        1
code       Digit1
keyCode    49      (устарел)
which      49      (устарел)
location   standard
repeat     нет
modifiers  нет

Теперь нажмите 1 на цифровом блоке (с включенным Num Lock) — и снимок покажет:

key        1
code       Numpad1
keyCode    97      (устарел)
which      97      (устарел)
location   numpad
repeat     нет
modifiers  нет

Тот же key, другой code, другая location, другой устаревший код. Если вы вяжете шорткат, сопоставляйте code === "Digit1", чтобы означить «ряд над буквами», и code === "Numpad1", чтобы означить «цифровой блок», — и избегайте ловушки key === "1", который срабатывает и там, и там.

FAQ#

Сопоставлять по key или по code?#

Зависит от того, что вы строите. Сопоставляйте по code для шорткатов и игровых управлений, где важна физическая позиция клавиши и вы не хотите, чтобы бинд менялся при переходе пользователя на Dvorak или не-латинскую раскладку. Сопоставляйте по key для текстового ввода, где вам важен порождённый символ (? против / или диакритики через dead-key). Для аккордов с модификаторами проверяйте флаги модификаторов (ctrlKey, metaKey, …), а не собственное значение key модификатора.

Почему keyCode и which помечены «устарел»?#

Они депрекированы и удалены из спецификации UI Events. Браузеры всё ещё заполняют их для совместимости, но их значения никогда не были согласованны между браузерами и раскладками (одна и та же физическая клавиша могла сообщать разные числа). Современный код должен читать key и code. Они показаны здесь лишь для отладки или портирования старого кода, ещё зависящего от чисел, — никогда не используйте их для новых биндов.

Страница не захватывает мои нажатия. Почему?#

Захват ограничен пунктирной зоной. Если фокус ушёл в другое место — потому что вы вышли табом или щёлкнули другой контрол, — зона перестаёт слушать. Щёлкните снова внутри зоны (она подсветится), и нажатия снова будут регистрироваться. Такое ограничение намеренно: оно сохраняет остальную страницу доступной с клавиатуры.

Meta — это Command или Windows?#

И то и другое — Meta это «супер»-клавиша платформы: Command на macOS, Windows / Super на Linux и Windows. Значок гласит Meta, а не угадывает ОС, потому что лежащее в основе поле metaKey — это то, что ваш код реально должен проверять.