# [orientation]() Orientation模块管理设备的方向信息,包括alpha、beta、gamma三个方向信息,通过plus.orientation可获取设备方向管理对象。 ### 方法: - [getCurrentOrientation](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.getCurrentOrientation): 获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息 - [watchOrientation](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.watchOrientation): 监听设备方向信息的变化 - [clearWatch](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.clearWatch): 关闭监听设备方向信息 ### 对象: - [OrientationOption](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationOption): JSON对象,监听设备方向感应器参数 - [Rotation](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.Rotation): JSON对象,设备方向信息数据 ### 回调方法: - [OrientationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationSuccessCallback): 获取设备方向信息成功的回调函数 - [OrientationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationErrorCallback): 获取设备方向信息失败的回调函数 ### 权限: permissions ~~~ "Orientation": { "description": "访问方向感应器信息" } ~~~ # [getCurrentOrientation]() 获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息 ~~~ void plus.orientation.getCurrentOrientation( successCB, errorCB ); ~~~ ### 说明: 方向信息是设备相对于水平初始方向分别以z、x、y轴为轴心旋转的角度,对应值为alpha、beta、gamma三个方向的信息。 方向信息可通过successCB回调函数返回。方向信息获取失败则调用回调函数errorCB ### 参数: - successCB: *( [OrientationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationSuccessCallback) ) 必选 *获取设备方向信息成功回调函数 - errorCB: *( [OrientationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationErrorCallback) ) 可选 *获取设备方向信息失败回调函数 ### 返回值: void : 无 ### 平台支持: - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 ### 示例: ~~~ <!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](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationSuccessCallback) ) 必选 * 获取设备方向信息成功回调函数 - errorCB: *( [OrientationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationErrorCallback) ) 可选 * 获取设备方向信息失败回调函数 - option: *( [OrientationOption](http://www.dcloud.io/docs/api/zh_cn/orientation.shtml#plus.orientation.OrientationOption) ) 可选 * 监听设备方向信息的参数,如更新数据的频率等 ### 返回值: Number : 用于标识方向信息监听器,可通过clearWatch方法取消监听。 ### 平台支持: - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 ### 示例: ~~~ <!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 : 无 ### 平台支持: - Android - 2.2+ (支持): 支持 - iOS - 4.3+ (支持): 支持 # [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)。 ### 平台支持 - Android - 2.2+ (支持) - iOS - 4.3+ (支持): iTouch、iPad设备不支持 - trueHeading: *(float 类型)*设备方向与地球真实北极方向的角度 浮点数类型,只读属性,取值范围为0到360(不等于360)。 ### 平台支持 - Android - 2.2+ (支持) - iOS - 4.3+ (支持): iTouch、iPad设备不支持 - headingAccuracy: *(float 类型)*设备方向值的误差值 浮点数类型,只读属性,取值范围为0到360(不等于360)。 ### 平台支持 - Android - 2.2+ (支持) - iOS - 4.3+ (支持): iTouch、iPad设备不支持 # [OrientationSuccessCallback]() 获取设备方向信息成功的回调函数 ~~~ void onSuccess( rotation ){ // Get orientation success code. } ~~~ ### 参数: - rotation: *( DOMString ) 必选 *设备的方向信息Rotation ### 返回值: void : 无 # [OrientationErrorCallback]() 获取设备方向信息失败的回调函数 ~~~ void onError( error ) { // Get orientation error code. } ~~~ ### 参数: - error: *( DOMException ) 必选 *失败信息 ### 返回值: void : 无