Element:requestPointerLock() 方法

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

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

语法

js
requestPointerLock()
requestPointerLock(options)

参数

options 可选

选项对象,可以包含以下属性:

unadjustedMovement 可选

禁用操作系统级别的鼠标加速调整,而是访问原始鼠标输入。默认值为 false;将其设置为 true 将禁用鼠标加速。

返回值

兑现 undefinedPromise

安全

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

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

如果使用 requestFullscreen() 调用 requestPointerLock(),则必须先调用 requestPointerLock(),因为 requestFullscreen() 将消耗瞬态激活的状态。

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

示例

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

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

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

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

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

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

更多示例代码请参见:

规范

Specification
Pointer Lock 2.0
# dom-element-requestpointerlock

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
requestPointerLock
options.unadjustedMovement parameter
ExperimentalNon-standard

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.
Requires a vendor prefix or different name for use.
Has more compatibility info.

参见