指针锁定 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) 方法

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

1. 将 promise 设为 一个新的 promise。
2. 当一个 window 处于 焦点 时，如果 this 的 shadow-including root 是 活动文档，并且属于某个 浏览上下文 （或具有不在焦点中的 祖先 浏览上下文）：
   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 的 节点文档的 活动沙盒标志集 含有 已沙盒化的指针锁定浏览上下文标志：
   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. 如果用户代理的 指针锁定目标 是某个元素， 其 shadow-including root 不等于 this 的 shadow-including root，那么：
      1. 在用户交互任务源中， 通过给定的 this，排队一个元素任务，执行以下步骤：
         1. 触发一个事件， 名为 pointerlockerror， 目标是 this 的 节点文档。
         2. 拒绝 promise，并抛出 "InvalidStateError" DOMException。
   2. 如果用户代理的 指针锁定目标 的 shadow-including root 等于 this 的 shadow-including root，并且 options 等同于当前的 指针锁定选项，那么：
      1. 将 指针锁定目标 设置为 this。
      2. 在用户交互任务源中， 通过给定的 this，排队一个元素任务，执行以下步骤：
         1. 触发一个事件， 名为 pointerlockchange， 目标是 this 的 节点文档。
         2. 解决 promise。
   3. 如果 指针锁定目标 为 null，或者 options 不等同于当前的 指针锁定选项，则处理锁请求并在完成时处理响应：
      1. 如果锁请求失败：
         1. 在用户交互任务源中， 通过给定的 this，排队一个元素任务，执行以下步骤：
            1. 触发一个事件， 名为 pointerlockerror， 目标是 this 的 节点文档。
            2. 拒绝 promise，并抛出 "NotSupportedError" DOMException。
         Issue 91：当后续的 requestPointerLock 被拒绝时，已锁定的目标是否应退出锁定状态？

         在 PR #49 的 requestPointerLock 算法中，目前缺少对以下场景的描述：
         当后续请求失败（无论出于何种原因）时，已锁定的目标是否应退出锁定状态？

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

   在 PR#49 的 requestPointerLock 算法中，目前缺少对如何处理锁请求队列中条目的描述。如果没有明确的文本，可能会导致错误的（？）假设，即所有条目将在最后同步出列。

7. 返回 promise。

注意

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

onpointerlockchange 属性

一个用于 事件处理器 idl 属性 的 pointerlockchange 事件。

onpointerlockerror 属性

一个用于 事件处理器 idl 属性 的 pointerlockerror 事件。

exitPointerLock() 方法

1. 如果用户代理的指针锁定目标为 null，则返回。
2. 如果 指针锁定目标 的 shadow-including root 不等于 this 的 节点文档，则返回。
3. 使用用户代理的 指针锁定目标 退出指针锁定。

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。

对于除 mousemove 以外的所有鼠标事件，movementX 和 movementY 必须为零。所有运动数据必须通过 mousemove 事件传递，以便在任何两个鼠标事件 earlierEvent 和 currentEvent 之间， currentEvent.screenX - earlierEvent.screenX 的值与 movementX 的所有事件的总和相等，除非指针被 用户代理 屏幕边界限制而无法更新 screenX。

movementX 和 movementY 必须在不管指针锁定状态下更新。

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

当启用指针锁定时，clientX、clientY、screenX 和 screenY 必须保持恒定值，仿佛在进入指针锁定后指针没有移动。 但是 movementX 和 movementY 必须继续提供指针位置的变化，类似于指针未锁定时的情况。如果鼠标持续向一个方向移动， 则 movementX 和 movementY 的值将没有限制。鼠标光标的概念将被移除，光标不会移出窗口或受到屏幕边界的限制。

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

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

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

movementX 成员

movementY 成员

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

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

如果 指针锁定目标 断开连接， 或者 用户代理、 窗口或标签页失去焦点，则必须退出指针锁定。在 活动文档 元素之间移动焦点， 包括在 浏览上下文 之间， 不会导致 退出指针锁定。 例如，使用键盘在框架或 iframe 的内容之间移动焦点不会退出。

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

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

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