游戏手柄

游戏手柄 可以具有一个 输入控件布局，它 描述 输入控件 在 游戏手柄 上的位置、方向和类型。用户代理 负责 识别 游戏手柄 何时 对应于标准布局，这意味着 该 游戏手柄 具有一个 输入 控件布局，使其能够与其他对应于 同一标准布局的 游戏手柄 互换使用。如果某布局的 输入控件 与标准布局中描述的 输入控件 具有大致相同的相对位置和方向，则 用户 代理 SHOULD 认为该布局 对应于标准布局。

用户代理 通常 不能直接检查某个 游戏手柄 的 输入控件布局，并且 MAY 使用启发式方法来决定 该布局。用户代理 SHOULD 在决定某个 游戏手柄 是否 对应于标准布局 时考虑设备标识符。如果系统为每个 输入控件 分配标签，并且 这些标签暗示某个特定布局，则 用户代理 SHOULD 认为该 游戏手柄 具有该布局。当存在 具有相同 输入控件 的 标准型号和无障碍型号时， 用户代理 SHOULD 认为该无障碍型号 具有与标准型号相同的 输入控件布局。

每个输入控件都有一个或多个关联的 输入值，这些值 是表示该控件当前状态的数值。 输入值 可随时更新。用户代理 负责 检测 输入值 何时已更新，并且 SHOULD 尽量减少更新与 读取更新后值之间的延迟。

读取某个 输入值 会返回其 逻辑值， 即 当前状态的未缩放数值表示。输入值 还 具有一个 逻辑 最小值 和一个 逻辑 最大值，它们定义边界内 逻辑值 的最小值和最大值。

输入值 可以具有一个关联的 HID usage identifier，这是一个 32 位值，用于识别 该输入值所表示的数据类型。HID usage 并不精确 描述 输入控件布局，但按照惯例，许多 布局类似的 游戏手柄 使用类似的 usages。用户代理 SHOULD 在决定 输入控件布局 时， 依赖围绕 HID usage identifiers 的惯例。

游戏手柄 可以具有 轴 输入。轴 是一个 输入值，表示控件相对于参考位置的当前位移。

游戏手柄 具有一个 轴 列表，它是一个 列表， 包含该 游戏手柄 的所有 轴 输入，顺序由 用户 代理 决定。

输入控件 可以被设计为在用户停止与 输入控件 交互时，自动将 轴 返回到中心位置。如果是这样，则该 轴 具有一个 首选轴 状态。具有 首选轴状态 的 轴 还可以 具有一个额外的 输入值，即 中心 位置 值，它是 轴 处于 中心位置时的 逻辑值。

游戏手柄 可以具有 按钮 输入。按钮 是一个 可以被按下以激活的 输入控件。游戏手柄 具有 一个 按钮 列表，它是一个 列表， 包含该 游戏手柄 的所有 按钮 输入，顺序由 用户代理 决定。

输入控件 可以被设计为在用户停止与 输入控件 交互时，自动将 按钮 返回到未按下状态。如果是这样，则该 按钮 具有一个 首选 按钮状态。

按钮 可以具有一个数字开关，用于指示该 按钮 何时被激活。如果是这样，则该 按钮 具有一个额外的 输入值，即 数字 按钮值，当该 按钮 被激活时为 true，否则为 false。

按钮 可以具有一个模拟传感器，使该 按钮 能够 报告该 按钮 被激活的程度。如果是这样，则该 按钮 具有：

• 一个 模拟 按钮值，即表示激活程度的 逻辑值，
• 一个 逻辑最小值，即表示未 激活的 逻辑值，以及
• 一个 逻辑最大值，即表示完全 激活的 逻辑值。

按钮 可以具有检测触摸的能力。如果是这样，则该 按钮 具有一个额外的 输入值，即 按钮 触摸值， 当该 按钮 被触摸时为 true，否则为 false。

游戏手柄 可以具有 触摸表面。触摸表面 是一种输入控件，提供表示接触点的 2D 位置数据。游戏手柄 具有一个 触摸 表面列表， 它是一个 列表，包含该 游戏手柄 的 触摸表面。该列表按如下方式排序：越靠近 游戏手柄 左侧的 触摸表面 越靠近 列表开头。

触摸表面 具有一个 活跃 触摸点列表 输入值，即一个包含零个或多个 触摸点 的 列表，表示传感器当前检测到的 接触点。触摸 点 表示单一时间点的单个接触点。触摸点 具有 触摸 x 坐标 和 触摸 y 坐标，表示其在 触摸表面 坐标系中的位置。如果某个 触摸表面 位于 游戏手柄 的顶部、底部、前侧或后侧，则 触摸 x 坐标 沿左右轴测量， 否则沿上下轴测量。触摸 y 坐标 沿垂直轴测量。

如果 触摸表面 位于 游戏手柄 的左侧或右侧， 则其两个维度都不会与水平轴对齐。

触摸表面 可以具有表面尺寸 输入值。表面 宽度 和 表面 高度 输入值 是 触摸表面 的尺寸，单位与 触摸 x 坐标 和 触摸 y 坐标 相同。触摸表面 要么同时具有两个尺寸值，要么两个都没有。

一个 触摸点 可以是新的接触点，也可以是 较早接触的延续。一个 触摸点 是 现有活跃 触摸点的一部分，如果 用户代理 识别出它是由较早的 GamepadTouch 表示的 触摸点 的延续。对于一个 触摸点，如果它是 现有 活跃触摸点的一部分，则其 活跃 触摸点 id 是较早的 GamepadTouch 的 touchId。

游戏手柄 可以具有 触觉 执行器。触觉 执行器 是一种输出控件，能够以用户可以感受到的方式移动 游戏手柄。 触觉执行器 可用于生成 触觉效果，向 用户提供反馈。来自多个执行器的振动会组合起来生成 更复杂的效果。用户 代理 负责 命令 触觉执行器 在 可用 的 游戏手柄 上播放和停止 触觉效果。

游戏手柄 可以具有一个 振动 执行器，它是一个 触觉执行器，能够播放 触觉效果 以振动 整个 游戏手柄。

触觉执行器 具有一个 列表，其中包含一个或多个 GamepadHapticEffectType 值，即 受支持的 效果 类型；当 游戏手柄 是 可用 时， 该列表不能改变。

当系统 接收到新的按钮或轴输入值 时， 运行以下步骤：

1. 令 gamepad 为表示 接收到新的按钮或轴输入值的设备的 Gamepad 对象。
2. 在 gamepad task source 上， 使用 gamepad 的 相关 全局对象 排队一个全局 任务，以便为 gamepad 更新游戏手柄状态。

要为 gamepad 更新 游戏手柄状态，运行 以下步骤：

1. 令 now 为给定 gamepad 的 相关 全局对象 的 当前高分辨率 时间。
2. 将 gamepad.[[timestamp]] 设置为 now。
3. 对 gamepad 运行 映射并归一化轴 的步骤。
4. 对 gamepad 运行 映射并归一化按钮 的步骤。
5. 对 gamepad 运行 记录触摸 的步骤。
6. 令 navigator 为 gamepad 的 相关 全局对象 的 Navigator 对象。
7. 如果 navigator.[[hasGamepadGesture]] 为 false，并且 gamepad 包含游戏手柄用户手势：
   1. 将 navigator.[[hasGamepadGesture]] 设置为 true。
   2. 对 navigator.[[gamepads]] 中的每个 connectedGamepad 执行以下操作：
      1. 如果 connectedGamepad 不等于 null：
         1. 将 connectedGamepad.[[exposed]] 设置为 true。
         2. 将 connectedGamepad.[[timestamp]] 设置为 now。
         3. 令 document 为 gamepad 的 相关 全局对象 的 关联 Document；否则为 null。
         4. 如果 document 不为 null 且为 完全 活跃，则在 gamepad task source 上 排队 一个全局任务，以在 gamepad 的 相关 全局对象 上，使用 GamepadEvent 触发一个事件， 名为 gamepadconnected， 并将其 gamepad 属性初始化为 connectedGamepad。

要为 gamepad 映射并 归一化轴，运行 以下步骤：

1. 令 axisValues 为一个由 unsigned long 值组成的 列表， 表示由 gamepad 所代表设备的每个轴 输入的最新逻辑轴输入值。
2. 令 maxRawAxisIndex 为 axisValues 的 大小 − 1。
3. 对从 0 到 maxRawAxisIndex 的 范围 中的每个 rawAxisIndex 执行以下操作：
   1. 令 mappedIndex 为 gamepad.[[axisMapping]][rawAxisIndex]。
   2. 令 logicalValue 为 axisValues[rawAxisIndex]。
   3. 令 logicalMinimum 为 gamepad.[[axisMinimums]][rawAxisIndex]。
   4. 令 logicalMaximum 为 gamepad.[[axisMaximums]][rawAxisIndex]。
   5. 令 normalizedValue 为 2 (logicalValue − logicalMinimum) / (logicalMaximum − logicalMinimum) − 1。
   6. 将 gamepad.[[axes]][axisIndex] 设置为 normalizedValue。

要为 gamepad 映射 并归一化按钮，运行 以下步骤：

1. 令 buttonValues 为一个由 unsigned long 值组成的 列表， 表示由 gamepad 所代表设备的每个 按钮输入的最新逻辑按钮输入值。
2. 令 maxRawButtonIndex 为 buttonValues 的 大小 − 1。
3. 对从 0 到 maxRawButtonIndex 的 范围 中的每个 rawButtonIndex 执行以下操作：
   1. 令 mappedIndex 为 gamepad.[[buttonMapping]][rawButtonIndex]。
   2. 令 logicalValue 为 buttonValues[rawButtonIndex]。
   3. 令 logicalMinimum 为 gamepad.[[buttonMinimums]][rawButtonIndex]。
   4. 令 logicalMaximum 为 gamepad.[[buttonMaximums]][rawButtonIndex]。
   5. 令 normalizedValue 为 (logicalValue − logicalMinimum) / (logicalMaximum − logicalMinimum)。
   6. 令 button 为 gamepad.[[buttons]][mappedIndex]。
   7. 将 button.[[value]] 设置为 normalizedValue。

   8. 如果该按钮具有数字开关来指示纯按下 或释放状态，则当按钮被按下时，将 button.[[pressed]] 设置为 true；如果未被按下，则设置为 false。

      否则，如果该值高于 按钮按下阈值， 则将 button.[[pressed]] 设置为 true；如果不高于该阈值，则设置为 false。

   9. 如果该按钮能够检测触摸，则当该按钮当前正被触摸时，将 button.[[touched]] 设置为 true。

      否则，将 button.[[touched]] 设置为 button.[[pressed]]。

要为 gamepad 记录 触摸，运行以下 步骤：

1. 断言：Gamepad.[[touches]] 为空。
2. 按触摸表面枚举顺序，对 gamepad 上的每个触摸表面重复以下步骤：
   1. 令 surfaceId 为当前表面 枚举索引。
   2. 如果触摸表面以设备单位暴露最大表面尺寸， 则将 touch.surfaceDimensions 设置为一个 DOMRectReadOnly， 其 width 和 height 初始化为触摸表面上的最大 X 和 Y 维度，单位为设备单位。
   3. 对 gamepad 为当前触摸表面报告的每个活跃触摸点 重复以下步骤。
      1. 令 touch 为一个新创建的 GamepadTouch 对象。
      2. 将 touch.surfaceId 设置为 surfaceId。
      3. 如果触摸数据是由 用户代理 跟踪的现有活跃触摸 点的一部分：
         1. 将 touch.touchId 设置为该 活跃触摸点的 touchId。
         2. 否则，将 touch.touchId 设置为 gamepad.[[nextTouchId]]，并 递增 gamepad.[[nextTouchId]]。
            注：触摸 id 相对于 Gamepad

            如果 Gamepad 有多个触摸表面，则触摸 id 在各表面之间是唯一的。

      4. 将 touch.position 设置为一个 新的 DOMPointReadOnly， 其中 x 初始化 为相对于设备触摸表面的设备 X 坐标， 并归一化到 [-1 .. 1]，其中 -1 是最左 坐标，1 是最右坐标；并且 y 初始化为设备触摸 表面的坐标，并归一化到 [-1 .. 1]，其中 -1 是最上 坐标，1 是最下坐标。
         注：可能的实现（如果 surfaceDimensions 可用）

         x = (2.0 * touchData.x / surfaceDimensions.width) - 1
y = (2.0 * touchData.y / surfaceDimensions.height) - 1

      5. 将 touch 追加 到 gamepad.[[touches]]。

表示已连接游戏手柄设备的 新 Gamepad 通过执行以下步骤构造：

1. 令 gamepad 为一个新创建的 Gamepad 实例：
   1. 将 gamepad 的 id 属性初始化为该游戏手柄的 标识字符串。
   2. 将 gamepad 的 index 属性初始化为 为 gamepad 选择未使用的 游戏手柄索引 的结果。
   3. 将 gamepad 的 mapping 属性初始化为 为游戏手柄设备 选择映射 的 结果。
   4. 将 gamepad.[[connected]] 设置为 true。
   5. 将 gamepad.[[timestamp]] 设置为给定 gamepad 的 相关 全局对象 的 当前高 分辨率时间。
   6. 将 gamepad.[[axes]] 设置为 为 gamepad 初始化轴 的结果。
   7. 将 gamepad.[[buttons]] 设置为 为 gamepad 初始化按钮 的结果。
   8. 将 gamepad.[[vibrationActuator]] 设置为 为 gamepad 构造 GamepadHapticActuator 的结果。
2. 返回 gamepad。

要为 gamepad 选择未使用的 游戏手柄索引，运行以下步骤：

1. 令 navigator 为 gamepad 的 相关 全局对象 的 Navigator 对象。
2. 令 maxGamepadIndex 为 navigator.[[gamepads]] 的 大小 − 1。
3. 对从 0 到 maxGamepadIndex 的 范围 中的每个 gamepadIndex 执行以下操作：
   1. 如果 navigator.[[gamepads]][gamepadIndex] 为 null，则返回 gamepadIndex。
4. 将 null 追加 到 navigator.[[gamepads]]。
5. 返回 navigator.[[gamepads]] 的 大小 − 1。

要为 gamepad 初始化轴，运行以下步骤：

1. 令 inputCount 为由 gamepad 所代表设备暴露的轴输入数量。
2. 将 gamepad.[[axisMinimums]] 设置为一个由 unsigned long 值组成的 列表，其 大小 等于 inputCount， 包含每个轴输入的最小逻辑值。
3. 将 gamepad.[[axisMaximums]] 设置为一个由 unsigned long 值组成的 列表，其 大小 等于 inputCount， 包含每个轴输入的最大逻辑值。
4. 令 unmappedInputList 为一个空的 列表。
5. 令 mappedIndexList 为一个空的 列表。
6. 令 axesSize 为 0。
7. 对从 0 到 inputCount − 1 的 范围 中的每个 rawInputIndex 执行以下操作：
   1. 如果索引 rawInputIndex 处的游戏手柄轴 表示 Standard Gamepad 轴：
      1. 令 canonicalIndex 为该轴的 规范索引。
      2. 如果 mappedIndexList 包含 canonicalIndex， 则将 rawInputIndex 追加到 unmappedInputList。

         否则：

         1. 将 gamepad.[[axisMapping]][rawInputIndex] 设置为 canonicalIndex。
         2. 将 canonicalIndex 追加 到 mappedIndexList。
         3. 如果 canonicalIndex + 1 大于 axesSize， 则将 axesSize 设置为 canonicalIndex + 1。

      否则，将 rawInputIndex 追加 到 unmappedInputList。

8. 令 axisIndex 为 0。
9. 对 unmappedInputList 中的每个 rawInputIndex 执行以下操作：
   1. 当 mappedIndexList 包含 axisIndex 时：
      1. 递增 axisIndex。
   2. 将 gamepad.[[axisMapping]][rawInputIndex] 设置为 axisIndex。
   3. 将 axisIndex 追加 到 mappedIndexList。
   4. 如果 axisIndex + 1 大于 axesSize，则将 axesSize 设置为 axisIndex + 1。
10. 令 axes 为一个空的 列表。
11. 对从 0 到 axesSize − 1 的 范围 中的每个 axisIndex 执行以下操作，将 0 追加 到 axes。
12. 返回 axes。

要为 gamepad 初始化按钮，运行以下步骤：

1. 令 inputCount 为由 gamepad 所代表设备暴露的按钮输入数量。
2. 将 gamepad.[[buttonMinimums]] 设置为一个由 unsigned long 值组成的 列表， 其 大小 等于 inputCount， 包含每个按钮输入的最小逻辑值。
3. 将 gamepad.[[buttonMaximums]] 设置为一个由 unsigned long 值组成的 列表， 其 大小 等于 inputCount， 包含每个按钮输入的最大逻辑值。
4. 令 unmappedInputList 为一个空的 列表。
5. 令 mappedIndexList 为一个空的 列表。
6. 令 buttonsSize 为 0。
7. 对从 0 到 inputCount − 1 的 范围 中的每个 rawInputIndex 执行以下操作：
   1. 如果索引 rawInputIndex 处的游戏手柄按钮 表示 Standard Gamepad 按钮：
      1. 令 canonicalIndex 为 该按钮的 规范索引。
      2. 如果 mappedIndexList 包含 canonicalIndex， 则将 rawInputIndex 追加到 unmappedInputList。

         否则：

         1. 将 gamepad.[[buttonMapping]][rawInputIndex] 设置为 canonicalIndex。
         2. 将 canonicalIndex 追加 到 mappedIndexList。
         3. 如果 canonicalIndex + 1 大于 buttonsSize，则将 buttonsSize 设置为 canonicalIndex + 1。

      否则，将 rawInputIndex 追加 到 unmappedInputList。

   2. 递增 rawInputIndex。
8. 令 buttonIndex 为 0。
9. 对 unmappedInputList 中的每个 rawInputIndex 执行以下操作：
   1. 当 mappedIndexList 包含 buttonIndex 时：
      1. 递增 buttonIndex。
   2. 将 gamepad.[[buttonMapping]][rawInputIndex] 设置为 buttonIndex。
   3. 将 buttonIndex 追加 到 mappedIndexList。
   4. 如果 buttonIndex + 1 大于 buttonsSize，则将 buttonsSize 设置为 buttonIndex + 1。
10. 令 buttons 为一个空的 列表。
11. 对从 0 到 buttonsSize − 1 的 范围 中的每个 buttonIndex 执行以下操作，将一个 新的 GamepadButton 追加 到 buttons。
12. 返回 buttons。

当 document 的 可见性状态 变为 "hidden" 时，对每个 GamepadHapticActuator actuator 运行这些步骤：

1. 如果 actuator.[[playingEffectPromise]] 为 null，则中止这些步骤。
2. 在 gamepad task source 上，使用 actuator 的 相关 全局对象 排队一个全局 任务，以运行以下 步骤：
   1. 如果 actuator.[[playingEffectPromise]] 为 null，则中止这些步骤。
   2. 使用 "preempted" 兑现 actuator.[[playingEffectPromise]]。
   3. 将 actuator.[[playingEffectPromise]] 设置为 null。
3. 在 actuator 上停止触觉效果。

表示 Gamepad 的主振动执行器的 新 gamepadHapticActuator 通过 执行以下步骤构造：

1. 令 gamepadHapticActuator 为一个新 创建的 GamepadHapticActuator 实例。
2. 令 supportedEffectsList 为一个空的 列表。
3. 对于 GamepadHapticEffectType 的每个枚举值 type，如果 用户代理 可以向该执行器 发送命令以启动该类型的效果，则将 type 追加到 supportedEffectsList。
4. 将 gamepadHapticActuator.[[effects]] 设置为 supportedEffectsList。

getGamepads() 方法步骤 为：

1. 令 doc 为 当前 全局对象 的 关联 Document。
2. 如果 doc 为 null，或 doc 不是 完全 活跃， 则返回一个空 列表。
3. 如果不 允许 doc 使用 "gamepad" 权限， 则抛出一个 "SecurityError" DOMException 并 中止这些步骤。
4. 如果 this.[[hasGamepadGesture]] 为 false，则 返回一个空 列表。
5. 令 now 为给定 当前 全局对象 的 当前高分辨率 时间。
6. 令 gamepads 为一个空 列表。
7. 对 this.[[gamepads]] 的每个 gamepad 执行以下操作：
   1. 如果 gamepad 不为 null 且 gamepad.[[exposed]] 为 false：
      1. 将 gamepad.[[exposed]] 设置为 true。
      2. 将 gamepad.[[timestamp]] 设置为 now。
   2. 将 gamepad 追加 到 gamepads。
8. 返回 gamepads。

如果当前输入状态表明 用户当前正在与游戏手柄交互，则 gamepad 包含 游戏手柄用户手势。用户代理 MUST 提供一种算法来检查输入状态是否 包含游戏手柄用户手势。对于支持中性 默认值并且已至少报告一次 pressed 值为 false 的按钮，pressed 值为 true SHOULD 被视为交互。如果按钮不支持 中性默认值（例如，切换开关），则 pressed 值为 true SHOULD NOT 被视为 交互。如果按钮从未报告过 pressed 值为 false， 则它 SHOULD NOT 被 视为交互。若轴支持中性默认值、当前 相对于中性的位移大于由 用户代理 选择的阈值，并且该轴 已至少报告一次低于该阈值的值，则轴移动 SHOULD 被视为 交互。如果某个轴不支持中性默认值 （例如，不会自动回中的操纵杆轴），或 某个轴从未报告过低于轴手势阈值的值， 则在检查交互时，该轴 SHOULD NOT 被考虑。 轴手势阈值 SHOULD 足够大，以免随机抖动 被视为交互。

WebIDLdictionary GamepadEventInit : EventInit {
  required Gamepad gamepad;
};

gamepad 成员

与此事件关联的 Gamepad。

检查 Gamepad 对象的能力可被用作 主动指纹识别的一种手段。用户代理 MAY 更改 通过 API 暴露的 设备信息，以减少 指纹识别表面。例如，某个实现可以要求 Gamepad 对象恰好具有 Standard Gamepad 布局中定义的按钮和轴数量， 即使已连接设备上存在更多或更少的 输入。 [FINGERPRINTING-GUIDANCE]