使用 Keyboard Lock API 捕获按键

针对各种使用场景(包括互动式网站、游戏以及远程桌面或应用串流)提供沉浸式全屏体验。

随着越来越多的用户把大部分时间花在浏览器上,互动性很强的网站、游戏、远程桌面流式传输和应用串流努力提供沉浸式全屏体验。为此,网站需要在全屏模式下使用特殊键和键盘快捷键,以便将其用于导航、菜单或游戏。一些可能需要用到的键示例包括 EscAlt + TabCmd + `Ctrl + N

默认情况下,这些密钥不适用于 Web 应用,因为它们会被浏览器或底层操作系统获取。借助 键盘锁定 API,网站可以使用主机操作系统允许的所有可用按键(请参阅浏览器兼容性)。

<ph type="x-smartling-placeholder">
</ph> 在 macOS Chrome 中流式传输到浏览器标签页的 Ubuntu Linux(尚未在全屏模式下运行)。 <ph type="x-smartling-placeholder">
</ph> 问题:流式传输的 Ubuntu Linux 远程桌面没有在全屏模式下运行,且没有有效的键盘锁定。 因此,系统键仍由 macOS 主机操作系统捕获,因此尚不提供沉浸式体验。

使用 键盘锁定 API

键盘 API 的 Keyboard 接口提供了一些功能,用于切换是否捕获实体键盘的按键操作,以及获取有关用户键盘布局的信息。

前提条件

新型浏览器支持两种类型的全屏:JavaScript(通过 Fullscreen API)启动和用户通过键盘快捷键启动的全屏。只有在由 JavaScript 发起的全屏处于活动状态时,才能使用 键盘锁定 API。 下面是一个 JavaScript 发起的全屏示例:

await document.documentElement.requestFullscreen();

功能检测

您可以使用以下格式检查是否支持 KEY Lock API:

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

锁定键盘

启用捕获实体键盘上任一或所有按键的按键操作后,Keyboard 接口的 lock() 方法会返回一个 promise。此方法只能捕获由底层操作系统授予访问权限的密钥。lock() 方法接受一个数组,其中包含要锁定的一个或多个按键代码。如果未提供任何按键代码,系统将锁定所有按键。界面事件键盘事件代码值规范中提供了一系列有效的键码值。

捕获所有密钥

以下示例捕获了所有按键操作。

navigator.keyboard.lock();

捕获特定键

以下示例会捕获 WASD 键。无论按键使用哪个辅助键,系统都会捕获这些按键。假设使用的是美式 QWERTY 布局,注册 "KeyW" 可确保将 WShift + WControl + WControl + 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()

演示

您可以通过在 Glitch 上运行演示来测试 键盘锁定 API。请务必查看源代码。点击下方的 进入全屏 按钮,即可在新窗口中启动演示,以便进入全屏模式。

安全注意事项

使用此 API 的一个问题是,它可用于获取所有键,并且(与 Fullscreen APIPointerLock API 结合使用)可防止用户退出网页。为防止出现这种情况,该规范要求浏览器为用户提供一种退出键盘锁定的方式,即使所有键都是由 API 请求的。在 Chrome 中,这个应急通道是一种长按 Esc 键(按 2 秒),可触发退出“键盘锁定”的操作。

致谢

本文由 Joe MedleyKayce Basques 审核。键盘锁定规范由 Gary KacmarcikJamie Walch 编写。 主打图片,由 Ken SuarezUnsplash 用户上传。