振动 API

除了标记为非规范性的章节外，本规范中的所有创作指南、图表、示例和注释均为非规范性内容。本规范中的其他所有内容均为规范性内容。

本文档中的关键字 MAY、MUST 与 SHOULD 应按照 BCP 14 [RFC2119] [RFC8174] 的定义进行解释，仅当它们全部大写出现时（如本处所示）。

本规范定义了适用于单一产品的合规性标准：实现其中接口的用户代理。

使用 ECMAScript 实现本规范中 API 的实现必须遵循 Web IDL 规范中定义的 ECMAScript 绑定[WEBIDL-1]，因为本规范采用了该规范及其术语。

WebIDLtypedef (unsigned long or sequence<unsigned long>) VibratePattern;

partial interface Navigator {
    boolean vibrate (VibratePattern pattern);
};

The vibrate() 方法的步骤是运行处理振动模式算法。振动模式由 VibratePattern 对象表示。

处理振动模式的规则如下面的算法所示。

1. 令 pattern 为 vibrate() 方法的第一个参数。
2. 令 valid pattern 为将 pattern 传递给验证并规范化后得到的结果。
3. 如果 文档 的 可见性状态 不是 visible，则返回 false 并终止这些步骤。
   注

   受信任（亦称特权）应用程序若与操作系统功能深度集成，即使该应用程序根本不可见，也可以振动设备，从而可以忽略前一步。
4. 使用 this 的 相关全局对象 和 valid pattern 执行振动。

要对给定的 pattern 振动模式 进行验证并规范化，请运行以下步骤。

1. 如果 pattern 是一个列表，则继续下一步。否则执行以下子步骤。
   1. 令 list 为最初为空的列表，并将 pattern 添加到 list。
   2. 将 pattern 设为 list。
2. 令 max length 的值为 10。
3. 如果 pattern 的长度大于 max length，则截断 pattern，仅保留前 max length 项。
   注

   如果 pattern 的长度为偶数且不为零，则模式中的最后一项没有效果，实施者此时可以将其从 pattern 中移除。
4. 令 max duration 的值为 10000。
5. 对于 pattern 中值大于 max duration 的每一项，将该项的值设为 max duration。
6. 返回 pattern。

要使用 全局对象 global 与 振动模式 pattern 执行振动，请运行以下步骤。

1. 如果 global 未拥有 粘性激活，则返回 false 并终止这些步骤。
2. 实现 MAY 返回 false 并终止这些步骤。
   注

   例如，实施者可能会在以下情况下中止算法：没有振动硬件、用户设置了偏好表明特定来源的页面永不可振动设备，或实施者对页面可导致的振动总时长设定上限并拒绝超出该上限的请求。
3. 如果已有另一实例的执行振动算法正在运行，则执行以下子步骤。
   1. 中止该其他实例的执行振动算法（若存在）。
   2. 如果 pattern 为空列表、仅包含一个值为 0 的条目，或设备无法振动，则返回 true 并终止这些步骤。
4. 返回 true，然后异步继续执行这些步骤。
5. 对于 pattern 中的每个 time，执行以下子步骤。
   1. 如果 time 的索引为偶数（第一个条目索引为 0），则让设备振动 time 毫秒。
   2. 否则等待 time 毫秒。

当 用户代理 检测到顶层浏览上下文的 Document 的 可见性状态 发生改变时，MUST 中止已在运行的 处理振动模式算法（若存在）。

振动 API 本身并不产生可在网络上消费的数据，但它可以成为其他 API 事件的来源。特别是，某些传感器（如加速度计或陀螺仪）在制造过程中会出现细微缺陷，这为指纹识别提供了可利用的表面，攻击者可通过振动 API 产生的振动刺激进行利用。因此，振动 API 与其他机制结合时会产生间接的隐私风险，可能导致跨设备追踪和通信等意外隐私风险。此外，振动的设备可能被外部观察者看到，从而实现对用户的物理识别甚至追踪。

基于上述原因，用户代理 MAY 在 API 被使用时通知用户，并提供按来源或全局禁用该 API（等同于空操作）的机制。

用户代理 SHOULD 实施全局速率限制，以在一定时间内（例如每分钟或每小时）限制振动请求的次数，防止过度使用。