振动 API

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

本文档中的关键词 MAY、MUST 和 SHOULD 应按 BCP 14 [RFC2119] [RFC8174] 中的描述进行解释，并且只有当它们以大写字母形式出现时，如此处所示，才应进行此解释。

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

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

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

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

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

处理振动模式的规则如下算法：

1. 令 pattern 为 vibrate() 方法的第一个参数。
2. 令 valid pattern 为将 pattern 传递给 校验与标准化 的结果。
3. 如果 document 的 visibility state 不是 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 的长度为偶数且不为零，则模式中的最后一个条目将无效，因此实现可在此处移除最后一个条目。
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 所在 顶级浏览上下文的 visibility state发生变化时， MUST 中止正在运行的 处理振动模式算法（如有）。

振动 API 本身不是数据源，因此不会在 Web 上产生可被消费的数据。但已知它可为其他 API 提供事件源。尤其是，一些传感器如加速度计或陀螺仪在制造时可能存在微小缺陷，因此可利用通过振动 API 产生的刺激，形成可被利用的指纹识别面。就此而言，振动 API 联合其他机制间接带来隐私风险，这可能包括跨设备追踪和通信。此外，设备振动时可能被外部观察者察觉，从而实现物理身份识别，甚至可能追踪用户。

因此，用户代理MAY在 API 被使用时通知用户，并按来源或全局提供禁用 API（实际无操作）的机制。

用户代理 SHOULD 应对每单位时间（如每分钟或每小时）内的振动请求数量进行全局速率限制，以防止过度使用。