# [proximity]()
Proximity模块管理设备距离传感器，可获取当前设备的接近距离信息，通过plus.proximity可获取设备距离传感管理对象。
### 方法：
- [getCurrentProximity](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.getCurrentProximity): 获取当前设备的接近距离信息
- [watchProximity](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.watchProximity): 监听设备接近距离的变化
- [clearWatch](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.clearWatch): 关闭监听设备接近距离变化
### 回调方法：
- [ProximitySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximitySuccessCallback): 获取设备接近距离信息成功的回调函数
- [ProximityErrorCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximityErrorCallback): 获取设备接近距离信息失败的回调函数
### 权限：
permissions
~~~
"Proximity": {
"description": "访问距离感应器信息"
}
~~~
# [getCurrentProximity]()
获取当前设备的接近距离信息
~~~
void plus.proximity.getCurrentProximity( successCB, errorCB );
~~~
### 说明：
获取当前接近设备的距离信息，距离值单位为厘米。如果感应器无法获取准确的距离值，则在接近设备时返回0，否则返回Infinity。 获取成功则调用successCB回调函数返接近回距离值。获取失败则调用errorCB回调函数错误信息。
### 参数：
- successCB: *( [ProximitySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximitySuccessCallback) ) 必选 *获取距离信息成功回调函数
- errorCB: *( [ProximityErrorCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximityErrorCallback) ) 可选 *获取距离信息失败回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Proximity Example</title>
<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
function getProximity() {
plus.proximity.getCurrentProximity( function ( d ) {
alert( "Get distance success: "+d );
}, function ( e ) {
alert( "Error: "+e.message );
} );
}
</script>
</head>
<body >
<input type='button' onclick='getProximity();' value='Proximity'/>
</body>
</html>
~~~
# [watchProximity]()
监听设备接近距离的变化
~~~
Number plus.proximity.watchProximity( changeCB, errorCB );
~~~
### 说明：
watchProximity将监听设备的接近距离信息变化事件，当接近距离发生变化时通过changeCB回调函数返回距离值。监听距离变化事件失败则通过errorCB回调函数返回错误信息。
### 参数：
- changeCB: *( [ProximitySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximitySuccessCallback) ) 必选 *设备接近距离变化时的回调函数
- errorCB: *( [ProximityErrorCallback](http://www.dcloud.io/docs/api/zh_cn/proximity.shtml#plus.proximity.ProximityErrorCallback) ) 可选 *
监听设备接近距离变化事件失败的回调函数
### 返回值：
Number : 用于标识接近距离变化事件监听器，可通过clearWatch方法取消监听。
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Proximity Example</title>
<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.proximity.watchProximity( function ( d ) {
document.getElementById("inf").innerText="Proximity: "+d;
}, function ( e ) {
alert( "Error: " + e.message );
} );
}
</script>
</head>
<body >
Proximity watch<br/>
<span id="inf"></span>
</body>
</html>
~~~
# [clearWatch]()
关闭监听设备接近距离变化
~~~
void plus.proximity.clearWatch( watchId );
~~~
### 参数：
- watchId: *( Number ) 必选 *
需要取消的距离监听器标识，调用watchProximity方法的返回值。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [ProximitySuccessCallback]()
获取设备接近距离信息成功的回调函数
~~~
void onSuccess( distance ) {
// Get distance success code.
}
~~~
### 参数：
- distance: *( Number ) 必选 *设备接近距离
设备接近距离传感器获取的距离值，单位为厘米。如果感应器无法获取准确的距离值，则在接近设备时返回0，否则返回Infinity。
### 返回值：
void : 无
# [ProximityErrorCallback]()
获取设备接近距离信息失败的回调函数
~~~
void onError( error ) {
// Get distance 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