orientation
Orientation模块管理设备的方向信息,包括alpha、beta、gamma三个方向信息,通过plus.orientation可获取设备方向管理对象。
方法:
- getCurrentOrientation: 获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息
- watchOrientation: 监听设备方向信息的变化
- clearWatch: 关闭监听设备方向信息
对象:
- OrientationOption: JSON对象,监听设备方向感应器参数
- Rotation: JSON对象,设备方向信息数据
回调方法:
- OrientationSuccessCallback: 获取设备方向信息成功的回调函数
- OrientationErrorCallback: 获取设备方向信息失败的回调函数
权限:
permissions
"Orientation": { "description": "访问方向感应器信息" }
getCurrentOrientation
获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息
void plus.orientation.getCurrentOrientation( successCB, errorCB );
说明:
方向信息是设备相对于水平初始方向分别以z、x、y轴为轴心旋转的角度,对应值为alpha、beta、gamma三个方向的信息。 方向信息可通过successCB回调函数返回。方向信息获取失败则调用回调函数errorCB
参数:
- successCB:
(
OrientationSuccessCallback
)
必选 获取设备方向信息成功回调函数
- errorCB:
(
OrientationErrorCallback
)
可选 获取设备方向信息失败回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Orientation Example</title> <script type="text/javascript"> // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { plus.orientation.getCurrentOrientation( function ( o ) { alert( "Orientation\nAlpha:" + o.alpha + "\nBeta:" + o.beta + "\nGamma:" + o.gamma ); } ); } </script> </head> <body> Orientation </body> </html>
watchOrientation
监听设备方向信息的变化
Number plus.orientation.watchOrientation( successCB, errorCB, option );
说明:
方向信息是设备相对于水平初始方向分别以z、x、y轴为轴心旋转的角度,对应值为alpha、beta、gamma三个方向的信息。watchOrientation每隔固定时间就获取一次设备的方向信息,通过successCB回调函数返回。可通过option的frequency参数设定获取设备方向信息的时间间隔。方向信息获取失败则调用回调函数errorCB。
参数:
- successCB:
(
OrientationSuccessCallback
)
必选
获取设备方向信息成功回调函数 - errorCB:
(
OrientationErrorCallback
)
可选
获取设备方向信息失败回调函数 - option:
(
OrientationOption
)
可选
监听设备方向信息的参数,如更新数据的频率等
返回值:
Number : 用于标识方向信息监听器,可通过clearWatch方法取消监听。平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Orientation Example</title> <script type="text/javascript"> // 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false ); // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() { plus.orientation.watchOrientation( function ( o ) { alert( "Orientation\nAlpha:" + o.alpha + "\nBeta:" + o.beta + "\nGamma:" + o.gamma ); }, function ( e ) { alert( "Orientation error: " + e.message ); } ); } </script> </head> <body> Orientation watch </body> </html>
clearWatch
关闭监听设备方向信息
void plus.orientation.clearWatch( watchId );
参数:
- watchId:
(
Number
)
必选
需要取消的方向监听器标识,调用watchOrientation方法的返回值。
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
OrientationOption
JSON对象,监听设备方向感应器参数
属性:
- frequency: (Number
类型
)更新方向信息的时间间隔
数值类型,单位为ms,默认值为500ms。
Rotation
JSON对象,设备方向信息数据
interface Rotation { readonly attribute float alpha; readonly attribute float beta; readonly attribute float gamma; readonly attribute float magneticHeading; readonly attribute float trueHeading; readonly attribute float headingAccuracy; }
属性:
- alpha: (float
类型
)以z方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
- beta: (float
类型
)以x方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为-180到180(不等于180)。
- gamma: (float
类型
)以y方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为-180到180(不等于180)。
- magneticHeading: (float
类型
)设备方向与地球磁场北极方向的角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
- Android2.2+ (支持)
- iOS4.3+ (支持): iTouch、iPad设备不支持
- WP7.5+ (支持)
- trueHeading: (float
类型
)设备方向与地球真实北极方向的角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
- Android2.2+ (支持)
- iOS4.3+ (支持): iTouch、iPad设备不支持
- WP7.5+ (支持)
- headingAccuracy: (float
类型
)设备方向值的误差值
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
- Android2.2+ (支持)
- iOS4.3+ (支持): iTouch、iPad设备不支持
- WP7.5+ (支持)
OrientationSuccessCallback
获取设备方向信息成功的回调函数
void onSuccess( rotation ){ // Get orientation success code. }
参数:
- rotation:
(
DOMString
)
必选 设备的方向信息Rotation
返回值:
void : 无OrientationErrorCallback
获取设备方向信息失败的回调函数
void onError( error ) { // Get orientation error code. }
参数:
- error:
(
DOMException
)
必选 失败信息