Warning:
This wiki has been archived and is now read-only.

DeviceOrientation事件规范

From HTML5 Chinese Interest Group Wiki
(Redirected from Orientation-event)
Jump to: navigation, search

一致性需求

该规范中的所有的图表、实例和注意事项都是非规范性的,同时这也是全部的非规范性内容。也就是说,除此之外的内容都是规范性的。

规范性内容中的关键字:“必须”、“禁止”、“要求的”、“应该”、“不应该”、“推荐的”、“可以”、“可选的”都是RFC2119中的描述性解释(to be interpreted as described in RFC2119)。为了保障阅读的流畅性,该规范中对这些关键字不会做格式上的强调。#RFC2119

有算法要求的部分全部使用了“必须”、“应该”、“可以”等关键字进行描述。

部分一致性要求是对特性、方法或对象的要求,这些要求会被解释为用户代理(user agent)的要求。

算法和步骤方面的一致性要求可以通过任何方式进行实现,只要运行结果相同即可。(规范里的算法定义只是为了易于遵循,而非性能最优)

规范中唯一的一致性的类就是用户代理。

用户代理在实现上可以针对无约束的用户输入进行特殊限制。比如为了防御服务攻击、为了保护过多内存 被占用、为了在有局限性的平台上工作等。

介绍

本章不具有规范性

本规范提供了几个新的DOM事件,这几个事件用于获得关于宿主设备物理方向及运动的信息。这些事件提供的信息不是原始的传感器信息,它们是不能获得底层信息来源的高层数据。常见的信息来源包括陀螺仪、罗盘及加速计。

本规范提供的第一个DOM事件是deviceorientation,其提供设备的物理方向信息,表示为一系列本地坐标系的旋角。

本规范提供的第二个DOM事件是devicemotion,其提供设备的加速信息,表示为定义在设备上的坐标系中的卡尔迪坐标。其还提供了设备在坐标系中的自转速率。若可行的话,事件应该提供设备重心处的加速信息。

本规范提供的最后一个DOM事件是compassneedscalibration,其用于通知Web站点使用罗盘信息校准上述事件。

下列代码展示了这些事件的使用方法:

注册一个deviceorientation事件的接收器:

      window.addEventListener("deviceorientation", function(event) {
          // 处理event.alpha、event.beta及event.gamma
      }, true);
将设备放置在水平表面,屏幕顶端指向西方,则其方向信息如下:

      {alpha: 90,
       beta: 0,
       gamma: 0};

为了获得罗盘指向,可以简单的使用360度减去alpha。若设被平行于水平表面,其罗盘指向为(360 - alpha)。
若用户手持设备,屏幕处于一个垂直平面且屏幕顶端指向上方。beta的值为90,alpha和gamma无关。
用户手持设备,面向alpha角度,屏幕处于一个垂直屏幕,屏幕顶端指向右方,则其方向信息如下:

      {alpha: 270 - alpha,
       beta: 0,
       gamma: 90};
只用自定义界面通知用户校准罗盘:

     window.addEventListener("compassneedscalibration", function(event) {
          alert('您的罗盘需要校准,请将设备沿数字8方向移动。');
          event.preventDefault();
      }, true);
注册一个devicemotion时间的接收器:

     window.addEventListener("devicemotion", function(event) {
          // 处理event.acceleration、event.accelerationIncludingGravity、
          // event.rotationRate和event.interval
      }, true);
将设备放置在水平表面,屏幕向上,acceleration为零,则其accelerationIncludingGravity信息如下:

      {x: 0,
       y: 0,
       z: 9.81};
设备做自由落体,屏幕水平向上,accelerationIncludingGravity为零,则其acceleration信息如下:

      {x: 0,
       y: 0,
       z: -9.81};
将设备安置于车辆至上,屏幕处于一个垂直平面,顶端向上,面向车辆后部。车辆行驶速度为v,向右侧进行半径为r的转弯。设备记录acceleration和accelerationIncludingGravity在位置x处的情况,同时设备还会记录rotationRate.gamma的负值:

      {acceleration: {x: v^2/r, y: 0, z: 0},
       accelerationIncludingGravity: {x: v^2/r, y: 0, z: 9.81},
       rotationRate: {alpha: 0, beta: 0, gamma: -v/r*180/pi} };

范围

本章不具有规范性

本规范仅提供取得描述宿主设备物品方向、运动信息的DOM事件。本API的预期目的是上述简单用例。本规范的范围不包括提供类似于旋转函数库之类的操作这些数据的工具。也不包括提供对传感器数据的访问和直接控制这些传感器。

描述

deviceorientation 事件

实现本规范的用户代理必须提供一个名为deviceorientation新DOM事件。相应事件的类型必须为DeviceOrientationEvent,且必须在window对象上触发。对deviceorientation事件的注册和触发必须遵循DOM Level 2事件的默认行为,[DOMEVENTS]。

用户代理同时还必须提供一个window对象上名为ondeviceorientation的事件处理函数IDL属性[HTML5]。该事件处理函数的类型必须是DeviceOrientationEvent

   interface DeviceOrientationEvent : Event {
   readonly attribute double? alpha;
   readonly attribute double? beta;
   readonly attribute double? gamma;
   readonly attribute boolean absolute;
   void initDeviceOrientationEvent(in DOMString type,
                                   in boolean bubbles,
                                   in boolean cancelable,
                                   in double? alpha,
                                   in double? beta,
                                   in double? gamma,
                                   in boolean absolute);
   }


该事件应当在方向发生较大改变时触发。在此上下文中对较大改变的定义由实现给出。另外,在注册此事件新的监听器时,实现应该在获得足够的新信息之后立即触发该事件。

本事件的alphabetagamma属性必须指示设备的方向,其表现形式为从固定在地球上的坐标系到固定在设备上的坐标系的转换。坐标系必须按照下面的描述调整。

地球坐标系是一个位于用户位置的“东、北、上”系。其拥有3个轴,地面相切与1984世界测地系统的spheriod的用户所在位置。

  • 东(X)在地面上,垂直于北轴,向东为正。
  • 北(Y)在地面上,向正北为正(指向北极)。
  • 上(Z)垂直于地面,向上为正。

对于一个移动设备,例如电话或平板,设备坐标系的定义于屏幕的标准方向相关。这意味着类似于键盘的滑动元素没有展开、类似于显示器的选择元素折叠至其默认位置。如果在设备旋转或展开滑动键盘时屏幕方向发生变化,这不会影响关于设备的坐标系的方向。用户希望获得这些屏幕方向的变化可以使用现有的orientationchange事件。对于膝上电脑,设备的坐标系定义于集成键盘。

  • x在屏幕或键盘平面上,屏幕或键盘的右侧为正。
  • y在屏幕或键盘屏幕上,屏幕或键盘的上方为正。
  • z垂直于屏幕或键盘屏幕,离开屏幕或键盘为正。

从地球坐标系到设备坐标系的转变必须按照下列系统转换。

旋转必须使用右手规则,即正向沿一个轴旋转为从该轴的方向看顺时针旋转。从两个系重合开始,旋转应用下列规则:

  1. 以设备坐标系z轴为轴,旋转alpha度。alpha的作用域为[0, 360)。
  2. 以设备坐标系x轴为轴,旋转beta度。beta的作用域为[-180, 180)。
  3. 已设备坐标系y轴为轴,旋转gamma度。gamma的作用域为[-90, 90)。

File:Http://www.w3.org/TR/orientation-event/start.png 设备的初始位置,地球(XYZ)与设备(zyz)坐标系重合。

File:Http://www.w3.org/TR/orientation-event/c-rotation.png 设备以z轴为轴,旋转alpha度,原坐标x、y轴显示为x0、y0

File:Http://www.w3.org/TR/orientation-event/a-rotation.png 设备以x轴为轴,旋转beta度,原坐标y、z轴显示为y0、z0

File:Http://www.w3.org/TR/orientation-event/b-rotation.png 设备以y轴为轴,旋转beta度,原坐标x、z轴显示为x0、z0

因此,alphabetagamma组成一组Z-X'-Y''式的固有Tait-Bryan角度。[[EULERANGLES]]注意这里对角度的选择遵循数学惯例,但这意味着alpha与罗盘指向相反。这还意味着这些角度不匹配车辆动力学中的roll-pitch-yaw惯例。

对于不能提供三个角度绝对值的实现,作为替代,可以提供关于任意方向的相对值。在这种情况下,必须设absolute属性为false,否则必须设absolute属性为true

对于不能提供所有三个角度的实现,其必须设未知的角度的值为null。如果提供了某一角度,必须恰当的设置absolute属性。如果实现不能提供任何方向信息,则触发事件时所有属性都必须被设为null。

compassneedscalibration 事件

实现了本规范的用户代理必须提供一个名为compassneedscalibration的新DOM事件,其使用定义于DOM Leve 2事件规范的Event接口[DOMEVENTS]。此事件必须在window对象上触发。对deviceorientation事件的注册和触发必须遵循DOM Level 2事件的默认行为,[DOMEVENTS]。

用户代理同时还必须提供一个window对象上名为oncompassneedscalibration的事件处理函数IDL属性[HTML5]。该事件处理函数的类型必须是Event

该事件必须在用户代理确定用于获得方向数据的罗盘需要校准时触发。此外,用户代理应当仅在校准罗盘可以提高deviceorientation事件获得的的数据的精准度时触发该事件。

该事件的默认行为应当是向用户提示如何校准罗盘。事件必须可以被撤销,以允许网站提供替代的校准界面。

devicemotion 事件

实现本规范的用户代理必须提供一个名为devicemotion新DOM事件。相应事件的类型必须为DeviceMotionEvent,且必须在window对象上触发。对devicemotion事件的注册和触发必须遵循DOM Level 2事件的默认行为,[DOMEVENTS]。

用户代理同时还必须提供一个window对象上名为ondevicemotion的事件处理函数IDL属性[HTML5]。该事件处理函数的类型必须是DeviceMotionEvent

   [Callback, NoInterfaceObject]
   interface DeviceAcceleration {
   readonly attribute double? x;
   readonly attribute double? y;
   readonly attribute double? z;
   }
   [Callback, NoInterfaceObject]
   interface DeviceRotationRate {
   readonly attribute double? alpha;
   readonly attribute double? beta;
   readonly attribute double? gamma;
   }
   interface DeviceMotionEvent : Event {
   readonly attribute DeviceAcceleration? acceleration;
   readonly attribute DeviceAcceleration? accelerationIncludingGravity;
   readonly attribute DeviceRotationRate? rotationRate;
   readonly attribute double? interval;
   void initAccelerometerEvent(in DOMString type,
                               in boolean bubbles,
                               in boolean cancelable,
                               in DeviceAcceleration? acceleration,
                               in DeviceAcceleration? accelerationIncludingGravity,
                               in DeviceRotationRate? rotationRate,
                               in double? interval);
   }

acceleration属性必须提供宿主设备相对于地球坐标系的加速信息,其表现形式为定义于4.1章的主坐标系,单位必须是m/s2

对于不能提供排除重力影响的加速数据的实现(例如缺少陀螺仪),作为替代,可以提供受重力影响的加速数据。这对于许多应用来说并不好用,但提供这些信息意味着提供了最大力度的支持。在此情况下,accelerationIncludingGravity属性必须提供宿主设备的加速信息,并加上一个加速度相等方向相反的反重力加速度。其表现形式为定义于4.1章的主坐标系。加速信息的单位必须是m/s2

rotationRate属性必须提供宿主设备在空间中旋转的速率,其表现形式为定义于4.1章的角度的变化速率,单位必须是deg/s。

interval属性必须提供从硬件获得数据的间隔,单位必须是毫秒。其必须是一个常量,以简化Web应用对数据的过滤。

对于不能提供所有属性的实现,其必须将位置的属性的值设为null。如果一个实现不能提供移动信息,则触发该事件时,所有属性都应被设为null。

用例与要求

用例

控制游戏

Web游戏应用监控设备方向,并将其解释为控制屏幕上的精灵在某方向上的倾斜。

手势识别

Web应用监控设备的加速,并将其应用于信号处理,以便识别特定首饰。距离说明,使用摇晃手势清除web表单。

地图

Web地图应用使用设备方向,将地图与实际情况对齐。

要求

本规范必须提供描述设备在空间中物理方向的数据。

本规范必须提供描述设备在空间中运动的数据。

本规范必须允许Web应用注册设备方向的变换。

本规范必须独立于方向和运动数据的底层来源。

本规范必须使用现有DOM事件框架。

样例

本节不具有规范性

下列样例旨在帮助DeviceOrientation事件的用户。

第二章提供了在设备屏幕水平放置时使用DeviceOrientation事件获得罗盘指向的例子。该例子展示了在用户“面对”设备且设备屏幕近似于垂直于用户面前时如何确定罗盘指向。此类应用被称为增强现实系统。

更确切地说,我们希望确定设备屏幕与屏幕背向的正交矢量的水平部分的罗盘指向。

如果r表示旋转设备主坐标系xyz中的该矢量,则:

File:Http://www.w3.org/TR/orientation-event/equation1.gif

对于r的变换,围绕z轴旋转表示为下列旋转矩阵:

File:Http://www.w3.org/TR/orientation-event/equation2.gif

对于r的变换,围绕x轴旋转表示为下列旋转矩阵:

File:Http://www.w3.org/TR/orientation-event/equation3.gif

对于r的变换,围绕y轴旋转表示为下列旋转矩阵:

File:Http://www.w3.org/TR/orientation-event/equation4.gif

如果R表示在地球坐标系XYZ中的向量r,则因为初始本体坐标系与地球对齐,则R:

File:Http://www.w3.org/TR/orientation-event/equation5a.gif

File:Http://www.w3.org/TR/orientation-event/equation5b.gif

File:Http://www.w3.org/TR/orientation-event/equation5c.gif

File:Http://www.w3.org/TR/orientation-event/equation5d.gif

File:Http://www.w3.org/TR/orientation-event/equation5e.gif

设β及γ均不为零,罗盘指向θ:

File:Http://www.w3.org/TR/orientation-event/equation6.gif

作为一致性验证,如果设γ = 0,则预期:

File:Http://www.w3.org/TR/orientation-event/equation7.gif

另外,如果设β = 90,则预期:

File:Http://www.w3.org/TR/orientation-event/equation8a.gif

File:Http://www.w3.org/TR/orientation-event/equation8b.gif