Vibration API

请移步：https://w3c-html-ig-zh.github.io/vibration/ ； 那里有最新的完整版。

摘要

本规范定义了一个 API，它提供了访问托管设备的振动机制。振动是一种触觉反馈。

引言

本章节不具有规范性

振动 API 专门设计用于仅需简单触觉反馈的用例场景。那些需要细粒度控制的用例场景超出了本规范的范围。该 API 并非用于通用的通知机制。通用的通知可使用通知 API 规范来处理。此外，决定是否启用振动也超出了本规范的范围。

一致性

像其他不具有规范性的章节一样，本规范中所有指导方案、图表、示例以及注解都不具有规范性。本规范中其余部分均具有规范性。

关键词可以和必须的释义由 [RFC2119] 进行解释。

本规范所定义的一致性标准条件仅适用于实现了规范所包含接口的用户代理。

由于本规范使用了 WebIDL 规范及其术语，因此如果使用 ECMA 脚本对本规范定义的应用程序接口进行实现，则必须保持实现与 ECMA 脚本绑定定义的 WebIDL 规范 [WEBIDL] 相一致。

术语

浏览上下文和旋转事件循环的概念由 [HTML5] 规范定义。

振动接口

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

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

当调用 vibrate() 方法时，必须运行处理振动模式的算法。

处理振动模式的算法的规则由以下描述：

1. 设 pattern 为 vibrate() 方法的第一个参数。
2. 设 valid pattern 为 pattern 参数进行验证和规范化后的结果。
3. 如果 hidden 属性 [PAGE-VISIBILITY] 的值为 true，则返回 false 并终止所有步骤。
   注：可信（也称授权）应用程序因为与操作系统功能集成紧密，即使完全不可见，也可能产生设备振动，因此可以忽略前述步骤。
4. 对 valid pattern 执行振动。

为验证和规范化某一给定的振动模式 pattern，运行这些步骤：

1. 如果 pattern 是一个列表，则进入下一步。否则运行以下子步骤：
   1. 设 list 为一个空的列表，并将 pattern 加入到 list 中。
   2. 设 pattern 的值为 list 。
      Error creating thumbnail: Unable to save thumbnail to destination
2. 设 max length 为实现相关的 pattern 的最大长度值。
   注：如果模式的长度大于最大长度，该 API 的实现可以考虑将此振动请求有效地分解成多个内部短请求，来实现同样的效果，而不是忽略最大长度后面的请求。然而，有些情况下忽略模式超过最大长度的部分是合时的。一个例子是，如果长度太长,将会有效地创建一个拒绝服务攻击用户。如果已知对某 web 应用程序来说某个长度太长时，该应用程序也可能采用多个请求；模式之间可能存在的差距是可以接受的。
3. 如果 pattern 长度大于 max length，截断 pattern，仅保留前 max length 项。
   注：如果 pattern 的长度是偶数并且非零，那么模式中的最后一项就会没有效果，因此实现可以在此从 pattern 中将之删除。
4. 设 max duration 为实现相关的 pattern 中单个振动项的最大持续时间值。
5. 对 pattern 中所有的持续时间值大于 max duration 的项，设置其值为 max duration。
6. 返回 pattern。

为使用 pattern 执行振动，运行这些步骤：

1. 算法的实现可以在此返回 false 并终止这些步骤。
   注：例如，用户设置了某些域的页面不得使设备振动，或者振动的总时间长度超过了页面允许的最大值从而拒绝振动请求，这些情况下算法实现可以停止算法运行。
2. 如果已经存在处理振动模式的算法实例，那么运行下列子步骤：
   1. 中止任何其他正在执行振动的实例。
   2. 如果 pattern 是一个空列表，包含单独一项的值为0，或者该设备不能振动，那么返回 true 并且终止这些步骤。
3. 返回 true，然后继续异步执行后续步骤。
4. 对于 pattern 中的每一项，设其为 time，运行以下子步骤：
   1. 如果 time 对应的索引为偶数（第一项的索引为0），控制设备振动 time 毫秒。
   2. 否则等待 time 毫秒。

当 Document 上的 visibilitychange 事件 [PAGE-VISIBILITY] 触发时，用户代理必须终止任何已经在运行处理振动模式的算法。

示例

本章节不具有规范性。

以下演示如何让设备振动1秒：

// 振动1秒
navigator.vibrate(1000);

// 或者
navigator.vibrate([1000]);

以下演示如何让设备先振动50毫秒，再停止100毫秒，再振动150毫秒：

navigator.vibrate([50, 100, 150]);

以下演示如何取消振动：

// 取消所有振动
navigator.vibrate(0);

// 或者
navigator.vibrate([]);