振动接口

W3C 推荐标准 2015年2月10日

请参阅本规范的勘误表，其中包括本规范自最新发布以来所发现的错误或者缺陷。

本节描述本文档发布时状态，其他文档可能取代本文档。 W3C 最新发布的技术报告，以及本技术报告的最新版本，参见 W3C 技术报告索引： http://www.w3.org/TR/。

自发布提案推荐标准以来，本文档没有任何新的改变。

W3C 期望通过发布该推荐标准，其所规范的功能不受 Web IDL 规范通往推荐标准的过程所影响。

本文档代表该小组在振动接口这一范围和特性的共识。应当指出的是，工作组意识到了无法使用这一简单的第一个版本规范来实现更先进的使用案例。留待未来的修订来解决它们。

本文档由设备接口工作组发布为推荐标准。关于本文档的任何反馈意见，请发送至工作组邮件列表： public-device-apis@w3.org （订阅, 归档）。欢迎反馈。

请参阅工作组的实现报告。

本文档已由 W3C 成员、软件开发者、 W3C 工作组和有关各方审阅，并由 W3C 理事会批准为推荐标准。此为稳定的文档，可以用作参考文献或从另一个文件中引用。 W3C 制定推荐标准的任务是使之受到关注，并促使其被广泛使用。这将增强 Web 的功能性与互操作性。

本文档由一个遵循 2004年2月5日 W3C 专利政策的小组创作。 W3C 维护着一个与工作组交付产品相关的已公开的专利列表；该列表页面还包括如何公开一项专利的说明。对某专利拥有实际知识并相信该专利包含了基本要求的个人，必须根据 W3C 专利政策第6节的要求公开这些信息。

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

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

当调用 vibrate() 方法时，必须运行 processing vibration patterns 算法。

processing vibration patterns 的算法的规则描述如下：

设 pattern 为 vibrate() 方法的第一个参数。
设 valid pattern 为 pattern 参数进行 validate and normalize 的结果。
如果 hidden 属性值 [PAGE-VISIBILITY] 设置为 true，则返回 false 并终止所有步骤。

注

可信（也称授权）应用程序因为与操作系统功能集成紧密，即使完全不可见，也可能产生设备振动，因此可以忽略前述步骤。
对 valid pattern Perform vibration。

为 validate and normalize 某一给定的振动模式 pattern，运行这些步骤：

如果 pattern 是一个列表，则进入下一步。否则运行以下子步骤：
1. 设 list 为一个空的列表，并将 pattern 加入到 list 中。
2. 设 pattern 的值为 list。
设 max length 为实现相关的 pattern 的最大长度值。

注

如果模式的长度大于最大长度，该接口的实现可以考虑将此振动请求有效地分解成多个内部短请求，来实现同样的效果，而不是忽略最大长度后面的请求。然而，有些情况下忽略模式超过最大长度的部分是合时的。一个例子是，如果长度太长,将会有效地创建一个拒绝服务攻击用户。如果已知对某 web 应用程序来说某个长度太长时，该应用程序也可能采用多个请求；模式之间可能存在的差距是可以接受的。
如果 pattern 长度大于 max length，截断 pattern，仅保留前 max length 项。

注

如果 pattern 的长度是偶数并且非零，那么模式中的最后一项就会没有效果，因此实现可以在此从 pattern 中将之删除。
设 max duration 为实现相关的 pattern 中单个振动项的最大持续时间值。
对 pattern 中所有的持续时间值大于 max duration 的项，设置其值为 max duration。
返回 pattern。

为使用 pattern perform vibration ，运行这些步骤：

算法的实现可以在此返回 false 并终止这些步骤。

注

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

当 Document browsing context 上的 visibilitychange 事件 [PAGE-VISIBILITY] 触发时，用户代理必须终止所有已经在运行的 processing vibration patterns 算法。

本章节不具有规范性。

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

示例 1

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

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

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

示例 2

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

以下演示如何取消振动：

示例 3

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

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