振动接口

W3C 推荐标准2015年2月10日

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

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

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

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

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

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

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

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

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

partial interfaceNavigator {booleanvibrate (VibratePatternpattern);};

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

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

设pattern 为vibrate() 方法的第一个参数。
设valid pattern 为pattern 参数进行validate and normalize 的结果。
如果 hidden 属性值 [PAGE-VISIBILITY] 设置为 true，则返回 false 并终止所有步骤。
注
可信（也称授权）应用程序因为与操作系统功能集成紧密，即使完全不可见，也可能产生设备振动，因此可以忽略前述步骤。
对valid patternPerform 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。

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

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

当Documentbrowsing 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([]);