大网数据广告活动
Web 标准与前端开发

Element:requestPointerLock() 方法

· 52CE 我爱测

Element 接口的 **`requestPointerLock()`** 方法允许你异步请求在给定元素上锁定指针。

Pointer Lock API

Element 接口的 requestPointerLock() 方法允许你异步请求在给定元素上锁定指针。

要跟踪请求的成功或失败,必须在 Document 级别监听 Document/pointerlockchange_event 事件和 Document/pointerlockerror_event 事件。

[!NOTE] 在当前规范中,requestPointerLock() 仅通过触发 Document/pointerlockchange_event 事件或 Document/pointerlockerror_event 事件来传达请求的成功或失败。 对规范的拟议更新更新了 requestPointerLock(),以返回 Promise 来传达成功或失败。此页面记录了返回 Promise 的版本。但请注意,此版本尚未成为标准,并且并非所有浏览器都实现此版本。有关更多信息,请参阅浏览器兼容性。

语法

requestPointerLock()
requestPointerLock(options)

参数

  • options
    • : 选项对象,可以包含以下属性:
      • unadjustedMovement
        • : 禁用操作系统级别的鼠标加速调整,而是访问原始鼠标输入。默认值为 false;将其设置为 true 将禁用鼠标加速。

返回值

兑现 undefined 的 Promise。

安全

调用 requestPointerLock() 时需要Transient activation。用户必须与页面或 UI 元素进行交互才能使此特性正常工作。此外,目标元素的关联文档必须处于活动状态。

如果在通过默认解锁手势释放指针锁后立即调用 requestPointerLock()(而不是通过 exitPointerLock() 调用),即使有Transient activation,调用也会失败。

如果使用 Element.requestFullscreen() 调用 requestPointerLock(),则必须先调用 requestPointerLock(),因为 Element.requestFullscreen() 将消耗Transient activation的状态。

在 iframe 元素中调用 requestPointerLock() 时,必须添加 allow-pointer-lock 沙盒令牌。此外,其他 iframe 元素中的其他元素不得处于指针锁定模式。

示例

指针锁定通常用于在线游戏中,当你希望鼠标移动专注于控制游戏时,不会因鼠标指针四处移动、超出游戏区域或到达窗口边缘而分散注意力。

要启用指针锁定,你需要让用户以某种方式与 UI 进行交互,例如按下按钮或游戏画布本身。

canvas.addEventListener("click", async () => {
  await canvas.requestPointerLock();
});

操作系统默认启用鼠标加速,这在你有时想要缓慢精确的移动(例如,你可能会使用图形包)但又想以更快的鼠标移动移动很远的距离(例如,滚动和选择多个文件)时非常有用。然而,对于某些第一人称视角游戏,原始鼠标输入数据更适合控制相机旋转——相同距离的移动(快速或慢速)都会导致相同的旋转。专业游戏玩家表示,这会带来更好的游戏体验和更高的准确度。

要禁用操作系统级鼠标加速并访问原始鼠标输入,你可以将 unadjustedMovement 设置为 true:

canvas.addEventListener("click", async () => {
  await canvas.requestPointerLock({
    unadjustedMovement: true,
  });
});

更多示例代码请参见:

规范

浏览器兼容性

参见

  • Document.pointerLockElement
  • Document.exitPointerLock()
  • 指针锁定

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。