Захват клавиш с помощью Keyboard Lock API

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

Thomas Steiner

Пользователи проводят все больше времени в браузере, поэтому разработчики интерактивных сайтов, игр, приложений и сервисов для удаленного доступа к рабочему столу стремятся сделать полноэкранный режим максимально удобным. Для этого сайтам нужен доступ к специальным клавишам и сочетаниям клавиш в полноэкранном режиме, чтобы их можно было использовать для навигации, меню или игр. Например, это могут быть клавиши Esc, Alt + Tab, Cmd + ` и Ctrl + N.

По умолчанию эти клавиши недоступны для веб-приложения, поскольку они перехватываются браузером или операционной системой. Keyboard Lock API позволяет сайтам использовать все доступные клавиши, разрешенные операционной системой хоста (см. раздел Совместимость с браузерами).

Ubuntu Linux, транслируемая на вкладку браузера в macOS Chrome (полноэкранный режим пока не включен).
Проблема: удаленный рабочий стол Ubuntu Linux не работает в полноэкранном режиме и без активной блокировки клавиатуры, поэтому системные клавиши по-прежнему захватываются операционной системой macOS и эффект погружения не достигается.

Как использовать Keyboard Lock API

Интерфейс Keyboard Keyboard API предоставляет функции, которые переключают захват нажатий клавиш на физической клавиатуре, а также получают информацию о раскладке клавиатуры пользователя.

Подготовка

В современных браузерах есть два типа полноэкранного режима: инициируемый JavaScript через Fullscreen API и инициируемый пользователем с помощью сочетания клавиш. Keyboard Lock API доступен, только если включен полноэкранный режим, инициированный JavaScript. Вот пример полноэкранного режима, инициированного JavaScript:

await document.documentElement.requestFullscreen();

Распознавание объектов

Чтобы проверить, поддерживается ли Keyboard Lock API, можно использовать следующий шаблон:

if ('keyboard' in navigator && 'lock' in navigator.keyboard) {
  // Supported!
}

Блокировка клавиатуры

Метод lock() интерфейса Keyboard возвращает промис после включения захвата нажатий клавиш для некоторых или всех клавиш на физической клавиатуре. Этот метод позволяет захватывать только те клавиши, доступ к которым разрешен операционной системой. Метод lock() принимает массив из одного или нескольких кодов клавиш, которые нужно заблокировать. Если коды не указаны, будут заблокированы все клавиши. Список допустимых значений кодов клавиш можно найти в спецификации UI Events KeyboardEvent code Values.

Захват всех клавиш

В примере ниже регистрируются все нажатия клавиш.

navigator.keyboard.lock();

Захват определенных клавиш

В примере ниже захватываются клавиши W, A, S и D. Оно захватывает эти клавиши независимо от того, какие модификаторы используются при нажатии. Если используется раскладка QWERTY (США), регистрация "KeyW" гарантирует, что W, Shift + W, Control + W, Control + Shift + W и все другие комбинации клавиш-модификаторов с W отправляются в приложение. То же самое относится к "KeyA", "KeyS" и "KeyD".

await navigator.keyboard.lock([
  "KeyW",
  "KeyA",
  "KeyS",
  "KeyD",
]);

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

document.addEventListener('keydown', (event) => {
  if ((event.code === 'KeyA') && !(event.ctrlKey || event.metaKey)) {
    // Do something when the 'A' key was pressed, but only
    // when not in combination with the command or control key.
  }
});

Разблокировка клавиатуры

Метод unlock() разблокирует все клавиши, захваченные методом lock(), и возвращает синхронно.

navigator.keyboard.unlock();

Когда документ закрывается, браузер всегда неявно вызывает unlock().

Демоверсии

Вы можете протестировать Keyboard Lock API, запустив эту демоверсию. Обязательно ознакомьтесь с исходным кодом. Если нажать кнопку "Полноэкранный режим" ниже, демоверсия откроется в новом окне и вы сможете развернуть ее на весь экран.

Безопасность

Одна из проблем с этим API заключается в том, что его можно использовать для захвата всех клавиш и (в сочетании с Fullscreen API и PointerLock API) запретить пользователю покидать веб-страницу. Чтобы этого не произошло, спецификация требует, чтобы браузер предоставлял пользователю возможность выйти из режима блокировки клавиатуры, даже если API запрашивает все клавиши. В Chrome для этого нужно нажать и удерживать клавишу Esc в течение двух секунд.

Благодарности

Статью проверили Джо Медли (Joe Medley) и Кейси Баскес (Kayce Basques). Авторы спецификации Keyboard Lock – Гэри Качмарчик (Gary Kacmarcik) и Джейми Уолч (Jamie Walch).