# [geolocation]()
Geolocation模块管理设备位置信息，用于获取地理位置信息，如经度、纬度等。通过plus.geolocation可获取设备位置管理对象。虽然W3C已经提供标准API获取位置信息，但在某些平台存在差异或未实现，为了保持各平台的统一性，定义此规范接口获取位置信息。
### 方法：
- [getCurrentPosition](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.getCurrentPosition): 获取当前设备位置信息
- [watchPosition](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.watchPosition): 监听设备位置变化信息
- [clearWatch](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.clearWatch): 关闭监听设备位置信息
### 对象：
- [Position](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Position): JSON对象，设备位置信息数据
- [Coordinates](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Coordinates): JSON对象，地理坐标信息
- [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption): JSON对象，监听设备位置信息参数
### 回调方法：
- [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback): 获取设备位置信息成功的回调函数
- [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback): 获取设备位置信息失败的回调函数
### 权限：
permissions
~~~
"Geolocation": {
"description": "访问设备位置信息"
}
~~~
# [getCurrentPosition]()
获取当前设备位置信息
~~~
void plus.geolocation.getCurrentPosition( successCB, errorCB, option );
~~~
### 说明：
位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取，由于获取位置信息可能需要较长的时间，当成功获取位置信息后将通过successCB回调函数返回。
### 参数：
- successCB: *( [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback) ) 必选 *获取设备位置信息成功回调函数
- errorCB: *( [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback) ) 可选 *获取设备位置信息失败回调函数
- option: *( [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption) ) 可选 *获取设备位置信息的参数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Geolocation Example</title>
<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.geolocation.getCurrentPosition( function ( p ) {
alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude );
}, function ( e ) {
alert( "Geolocation error: " + e.message );
} );
}
</script>
</head>
<body >
</body>
</html>
~~~
# [watchPosition]()
监听设备位置变化信息
~~~
Number plus.geolocation.watchPosition( successCB, errorCB, option );
~~~
### 说明：
位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取。当位置信息更新后将通过successCB回调函数返回。位置信息获取失败则调用回调函数errorCB。
### 参数：
- successCB: *( [GeolocationSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationSuccessCallback) ) 必选 *
设备位置信息更新成功回调函数
- errorCB: *( [GeolocationErrorCallback](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.GeolocationErrorCallback) ) 可选 *
获取设备位置信息失败回调函数
- option: *( [PositionOption](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.PositionOption) ) 可选 *
监听设备位置信息的参数
### 返回值：
Number : 用于标识位置信息监听器，可通过clearWatch方法取消监听。
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Geolocation Example</title>
<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
plus.geolocation.watchPosition( function ( a ) {
alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude );
}, function ( e ) {
alert( "Geolocation error: " + e.message );
} );
}
</script>
</head>
<body >
</body>
</html>
~~~
# [clearWatch]()
关闭监听设备位置信息
~~~
void plus.geolocation.clearWatch( watchId );
~~~
### 参数：
- watchId: *( Number ) 必选 *
需要取消的位置监听器标识，调用watchPosition方法的返回值。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Geolocation Example</title>
<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
var wid = null;
function onPlusReady() {
plus.geolocation.getCurrentPosition( function ( p ) {
alert( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude );
}, function ( e ) {
alert( "Geolocation error: " + e.message );
} );
}
function cancel() {
plus.geolocation.clearWatch( wid );
wid = null;
}
</script>
</head>
<body >
<input type="button" value="Cancel" onclick="cancel();" ></input>
</body>
</html>
~~~
# [Position]()
JSON对象，设备位置信息数据
~~~
interface Position {
readonly attribute Coordinates coords;
readonly attribute String coordsType;
readonly attribute Number timestamp;
}
~~~
### 属性：
- coords: *([Coordinates](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Coordinates) 类型)*地理坐标信息，包括经纬度、海拔、速度等信息
- coordsType: *(String 类型)*获取到地理坐标信息的坐标系类型
可取以下坐标系类型： “gps”：表示WGS-84坐标系； “gcj02”：表示国测局经纬度坐标系； “bd09”：表示百度墨卡托坐标系； “bd09ll”：表示百度经纬度坐标系。
- timestamp: *(Number 类型)*获取到地理坐标的时间戳信息
时间戳值为从1970年1月1日至今的毫秒数。
# [Coordinates]()
JSON对象，地理坐标信息
~~~
interface Coordinates {
readonly attribute double latitude;
readonly attribute double longitude;
readonly attribute double altitude;
readonly attribute double accuracy;
readonly attribute double altitudeAccuracy;
readonly attribute double heading;
readonly attribute double speed;
}
~~~
### 属性：
- latitude: *(Number 类型)*坐标纬度值
数据类型对象，地理坐标中的纬度值。
- longitude: *(Number 类型)*坐标经度值
数据类型对象，地理坐标中的经度值。
- altitude: *(Number 类型)*海拔信息
数据类型对象，如果无法获取此信息，则此值为空（null）。
- accuracy: *(Number 类型)*地理坐标信息的精确度信息
数据类型对象，单位为米，其有效值必须大于0。
- altitudeAccuracy: *(Number 类型)*海拔的精确度信息
数据类型对象，单位为米，其有效值必须大于0。如果无法获取海拔信息，则此值为空（null）。
- heading: *(Number 类型)*表示设备移动的方向
数据类型对象，范围为0到360，表示相对于正北方向的角度。如果无法获取此信息，则此值为空（null）。如果设备没有移动则此值为NaN。
- speed: *(Number 类型)*表示设备移动的速度
数据类型对象，单位为米每秒（m/s），其有效值必须大于0。如果无法获取速度信息，则此值为空（null）。
# [PositionOption]()
JSON对象，监听设备位置信息参数
### 属性：
- enableHighAccuracy: *(Boolean 类型)*是否高精确度获取位置信息
高精度获取表示需要使用更多的系统资源，默认值为false。
- timeout: *(Number 类型)*获取位置信息的超时时间
单位为毫秒（ms），默认值为不超时。如果在指定的时间内没有获取到位置信息则触发错误回调函数。
- maximumAge: *(Number 类型)*获取位置信息的缓存时间
单位为毫秒（ms），默认值为0（立即更新获取）。如果设备缓存的位置信息超过指定的缓存时间，将重新更新位置信息后再返回。
- provider: *(String 类型)*定位数据的供应者
可取以下供应者： “system”：表示系统定位模块，支持wgs84坐标系； “baidu”：表示百度定位模块，支持gcj02/bd09/bd09ll坐标系。 默认使用“system”值，若指定的provider不存在或无效则返回错误回调。 注意：百度定位模块需要配置百度地图相关参数才能正常使用。
### 平台支持
- Android - 2.2+ (支持)
- iOS - 4.5+ (支持): provider为“baidu”时，仅支持bd09ll坐标系。
- coordsType: *(String 类型)*指定获取的定位数据坐标系类型
可取以下坐标系类型： “wgs84”：表示WGS-84坐标系； “gcj02”：表示国测局经纬度坐标系； “bd09”：表示百度墨卡托坐标系； “bd09ll”：表示百度经纬度坐标系； provider为“system”时，默认使用“wgs84”类型；provider为“baidu”是，默认使用“bd09ll”类型。 如果设置的坐标系类型provider不支持，则返回错误。
# [GeolocationSuccessCallback]()
获取设备位置信息成功的回调函数
~~~
void onSuccess( position ) {
// Get Position code.
}
~~~
### 参数：
- position: *( [Position](http://www.dcloud.io/docs/api/zh_cn/geolocation.shtml#plus.geolocation.Position) ) 必选 *设备的地理位置信息，参考Position
### 返回值：
void : 无
# [GeolocationErrorCallback]()
获取设备位置信息失败的回调函数
~~~
void onError( error ) {
// Handle error
}
~~~
### 参数：
- 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