指针锁定 2.0

Element 接口被扩展，以提供请求指针锁定的能力。

WebIDLpartial interface Element {
  Promise<undefined> requestPointerLock(optional PointerLockOptions options = {});
};

const lock_element = document.getElementById("lock_element");
const lock_button = document.getElementById("lock");
lock_button.addEventListener("click", async (event) => {
    try {
        await lock_element.requestPointerLock({ unadjustedMovement: true });
        console.log("successfully locked!");
    } catch (e) {
        console.log("lock failed with error: ", e);
    }
});

requestPointerLock(PointerLockOptions options) 方法

一个名为 锁请求队列（lock requests queue） 的 并行队列 用于排队所有请求。当调用 requestPointerLock() 时，执行以下步骤：

1. 令 promise 为 一个新 promise。
2. 当 window 处于 焦点时，如果 this 的 包含 shadow 的根节点 不是 活动文档 所在的 浏览上下文 （或有一个 祖先 浏览上下文）处于非焦点状态：
   1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
      1. 触发一个事件 名为 pointerlockerror，事件目标为 this 的 节点文档。
      2. 拒绝 promise，错误为 "WrongDocumentError" DOMException。
   2. 返回 promise。
   Issue 93: 可见性状态检查

   规范不应允许隐藏文档请求指针锁定。

   此外，如果文档变为隐藏状态，则应释放指针锁定。

3. 如果相关全局对象没有瞬时激活，且 Document 之前未通过 exitPointerLock() 释放过成功的指针锁定：
   1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
      1. 触发一个事件 名为 pointerlockerror，事件目标为 this 的 节点文档。
      2. 拒绝 promise，错误为 "NotAllowedError" DOMException。
   2. 返回 promise。
   注
4. 如果 this 的 节点文档 的 活动沙箱标志集 含有 sandboxed pointer lock browsing context flag 标志：
   1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
      1. 触发一个事件 名为 pointerlockerror，事件目标为 this 的 节点文档。
      2. 拒绝 promise，错误为 "SecurityError" DOMException。
   2. 返回 promise。
5. 如果 options["unadjustedMovement"] 为 true 且平台不支持 unadjustedMovement：
   1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
      1. 触发一个事件 名为 pointerlockerror，事件目标为 this 的 节点文档。
      2. 拒绝 promise，错误为 "NotSupportedError" DOMException。
   2. 返回 promise。
   Issue 90: 建议添加静态字段用于指示是否支持 `unadjustedMovement`。

   在 PR #49 中引入了 PointerLockOptions。但 PointerLockOptions 的 unadjustedMovement 可能并非所有平台都支持。静态字段可用于在直接在 PointerLockOptions 里使用前判断是否支持，以避免不支持报错。

6. 将以下步骤加入 锁请求队列：
   1. 如果用户代理的 pointer-lock target 是一个其 包含 shadow 的根节点 不等于 this 的 包含 shadow 的根节点 的元素，则：
      1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
         1. 触发一个事件 名为 pointerlockerror，事件目标为 this 的 节点文档。
         2. 拒绝 promise，错误为 "InvalidStateError" DOMException。
   2. 如果用户代理的 pointer-lock target 的 包含 shadow 的根节点 等于 this 的 包含 shadow 的根节点 且 options 与当前 pointer-lock options 等价，则：
      1. 将 pointer-lock target 设为 this。
      2. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
         1. 触发一个事件 名为 pointerlockchange，事件目标为 this 的 节点文档。
         2. 解决 promise。
   3. 如果 pointer-lock target 为 null，或 options 不等价于当前 pointer-lock options，则处理锁请求并在完成后处理响应：
      1. 如果锁请求失败：
         1. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
            1. 触发一个事件 名为 pointerlockerror ，事件目标为 this 的 节点文档。
            2. 拒绝 promise，错误为 "NotSupportedError" DOMException。
         Issue 91: 如果后续 requestPointerLock 被拒绝，已锁定目标应否退出锁定状态？

         在 PR #49 的 requestPointerLock 算法中，目前没有描述如下场景：
         当后续请求失败（出于任何原因），已锁定目标是否应退出锁定状态？

      2. 如果锁请求成功：
         1. 通过执行以下操作进入 指针锁定状态：
            1. 将用户代理的 pointer-lock target 设为 this。
            2. 将用户代理的 光标位置 设为当前系统鼠标位置。
            3. 将 pointer-lock options 设为 options。
         2. 在 用户交互任务源 上排队一个元素任务，以 this 为参数，执行以下步骤：
            1. 触发一个事件 名为 pointerlockchange ，事件目标为 this 的 节点文档。
            2. 解决 promise。
   Issue 96: 锁请求队列处理不完整

   在 PR #49 的 requestPointerLock 算法中，目前没有描述 lock requests queue 中条目的处理方式。缺少明确文本可能导致所有条目在末尾同步出队的错误（？）假设。

7. 返回 promise。

注

WebIDLpartial interface Document {
  attribute EventHandler onpointerlockchange;
  attribute EventHandler onpointerlockerror;
  undefined exitPointerLock();
};

onpointerlockchange 属性

用于事件处理程序 IDL 属性， 监听pointerlockchange事件。

onpointerlockerror 属性

用于事件处理程序 IDL 属性， 监听pointerlockerror事件。

exitPointerLock() 方法

1. 如果用户代理的 pointer-lock target 为 null，则返回。
2. 如果pointer-lock target的包含 shadow 的根节点不等于 this的节点文档，则返回。
3. 使用用户代理的pointer-lock target 退出指针锁定。

WebIDLpartial interface mixin DocumentOrShadowRoot {
  readonly attribute Element? pointerLockElement;
};

pointerLockElement

当指针被锁定时，返回对该元素进行重定向的结果，该元素是鼠标事件的目标。如果结果和this元素在同一棵树中，则返回该元素，否则返回 null。

如果锁定正在等待中或指针未被锁定，则返回 null。

示例 2

<body>
  <div id="host1">
    <shadow-root id="root1">
      <canvas id="canvas1"></canvas>
    </shadow-root>
  </div>
  <div id="host2">
    <shadow-root id="root2">
      <canvas id="canvas2"></canvas>
    </shadow-root>
  </div>
</body>

注

本示例使用虚构的 shadow-root 元素来表示shadow root 实例。

如果 #canvas1 是目标，document.pointerLockElement 返回 #host1，而 root1.pointerLockElement 返回 #canvas1。将 重定向 #canvas1 到 #root2 的结果是 #host1，但由于 #host1 不在与 #root2 相同的树中，因此 root2.pointerLockElement 会返回 null。

WebIDLpartial interface MouseEvent {
  readonly attribute double movementX;
  readonly attribute double movementY;
};

movementX 属性

movementY 属性

movementX 和 movementY 属性必须提供指针位置的变化量，相当于在两个连续的 mousemove 事件 eNow 和 ePrevious 之间，screenX、screenY 的值被保存，并取其差值 movementX = eNow.screenX - ePrevious.screenX。

movementX 和 movementY 在所有鼠标事件中（除了 mousemove 和 pointermove）必须为零。所有运动数据必须通过 mousemove 事件传递，这样在任意两个鼠标事件 earlierEvent 和 currentEvent 之间，currentEvent.screenX - earlierEvent.screenX 的值等价于 earlierEvent 之后所有事件的 movementX 的和，唯一的例外是当 screenX 无法更新时（因为指针被 用户代理 的屏幕边界裁剪）。

movementX 和 movementY 必须在无论是否处于指针锁定状态下都进行更新。

当未锁定时，系统光标可以离开并重新进入用户代理窗口。如果发生这种情况，且用户代理不是操作系统鼠标移动事件的目标，则用户代理将无法获知最近的指针位置，movementX/movementY 也无法计算，必须设为零。

当启用指针锁定时，clientX、clientY、screenX 和 screenY 必须保持恒定值，好像进入指针锁定后指针根本未移动。但 movementX 和 movementY 必须继续像未锁定时一样提供指针位置的变化量。如果鼠标持续向一个方向移动，movementX 和 movementY 的值不会有上限。此时鼠标光标的概念已被移除，它不会移出窗口，也不会被屏幕边缘限制。

movementX 和 movementY 的未初始化值必须为 0。

在鼠标输入被中断（如鼠标光标离开窗口后又在另一位置重新进入）时，不应出现大的 movement 值。如果用户代理 遇到从操作系统接收鼠标输入数据的间隙，则下一个生成的 mousemove 事件必须将 movementX 和 movementY 设为 0。例如，当用户代理在窗口系统 API 收到鼠标离开事件时就可能出现这种间隙。作为例外，鼠标捕获可能允许用户代理在光标移出窗口时继续接收鼠标事件。

WebIDLpartial dictionary MouseEventInit {
  double movementX = 0;
  double movementY = 0;
};

movementX 成员

movementY 成员

movementX 和 movementY 成员用于初始化 MouseEvent 的对应成员。

必须始终提供一个 默认解锁手势， 用于通过 退出指针锁定， 使用 用户代理 的 指针锁定目标。

如果pointer-lock target变为断开，或用户代理、窗口或标签失去焦点，则必须退出指针锁定。在 活动文档的各元素之间切换焦点，包括在浏览上下文之间切换，并不会退出指针锁定。例如，使用键盘在 frame 或 iframe 的内容之间切换焦点不会导致退出。

当进入或退出全屏 [FULLSCREEN] 时， 除非指针需要启用与 用户代理 图形用户界面的交互， 使用 默认解锁手势 退出了全屏和指针锁定，或者窗口或标签页失去焦点，则不得退出指针锁定。

与标记为非规范的章节一样，本规范中的所有作者指南、图表、示例和注释都是非规范的。除此之外，本规范中的所有内容都是规范性的。

本规范定义了一些一致性标准，适用于单个产品：用户代理，即实现了其中包含的接口的用户代理。