# [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 : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS