# [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 : 无