Geolocation模块管理设备位置信息,用于获取地理位置信息,如经度、纬度等。通过plus.geolocation可获取设备位置管理对象。虽然W3C已经提供标准API获取位置信息,但在某些平台存在差异或未实现,为了保持各平台的统一性,定义此规范接口获取位置信息。
1、方法
1.1、getCurrentPosition: 获取当前设备位置信息
void plus.geolocation.getCurrentPosition( successCB, errorCB, option );
说明:位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取,由于获取位置信息可能需要较长的时间,当成功获取位置信息后将通过successCB回调函数返回。
参数:
successCB: ( GeolocationSuccessCallback ) 必选 获取设备位置信息成功回调函数
errorCB: ( GeolocationErrorCallback ) 可选 获取设备位置信息失败回调函数
option: ( PositionOptions ) 可选 获取设备位置信息的参数
返回值:void : 无
平台支持:Android - 2.2+ (支持): 支持、iOS - 4.3+ (支持): 支持
示例:
[html] view plain copy print?
- <!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>
<!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>
1.2、watchPosition: 监听设备位置变化信息
Number plus.geolocation.watchPosition( successCB, errorCB, option );
说明:位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取。当位置信息更新后将通过successCB回调函数返回。位置信息获取失败则调用回调函数errorCB。
参数:
successCB: ( GeolocationSuccessCallback ) 必选 设备位置信息更新成功回调函数
errorCB: ( GeolocationErrorCallback ) 可选 获取设备位置信息失败回调函数
option: ( PositionOptions ) 可选 监听设备位置信息的参数
返回值:Number : 用于标识位置信息监听器,可通过clearWatch方法取消监听。
平台支持:Android - 2.2+ (支持): 支持,iOS - 4.3+ (支持): 支持
示例:
[html] view plain copy print?
- <!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>
<!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>
1.3、clearWatch: 关闭监听设备位置信息
void plus.geolocation.clearWatch( watchId );
参数:watchId: ( Number ) 必选 需要取消的位置监听器标识,调用watchPosition方法的返回值。
返回值:void : 无
平台支持:Android - 2.2+ (支持): 支持,iOS - 4.3+ (支持): 支持
示例:
[html] view plain copy print?
- <!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() {
- wid = plus.geolocation.watchPosition( 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>
<!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() { wid = plus.geolocation.watchPosition( 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>
2、对象
2.1、Position: JSON对象,设备位置信息数据
interface Position {
readonly attribute Coordinates coords;
readonly attribute String coordsType;
readonly attribute Number timestamp;
readonly attribute Address address;
readonly attribute String addresses;
}
属性:
(1)、coords: (Coordinates 类型 )地理坐标信息,包括经纬度、海拔、速度等信息
(2)、coordsType: (String 类型 )获取到地理坐标信息的坐标系类型,可取以下坐标系类型: “gps”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系。
(3)、timestamp: (Number 类型 )获取到地理坐标的时间戳信息,时间戳值为从1970年1月1日至今的毫秒数。
(4)、address: (Address 类型 )获取到地理位置对应的地址信息,获取地址信息需要连接到服务器进行解析,所以会消耗更多的资源,如果不需要获取地址信息可通过设置PositionOptions参数的geocode属性值为false避免获取地址信息。 如果没有获取到地址信息则返回undefined。平台支持Android - 2.3+ (支持): 使用系统定位模块无法获取位置信息。iOS - 5.1+ (支持): 系统定位模块也支持获取位置信息。
(5)、addresses: (String 类型 )获取完整地址描述信息。如果没有获取到地址信息则返回undefined。平台支持Android - 2.3+ (支持): 使用系统定位模块无法获取位置信息。iOS - 5.1+ (支持): 系统定位模块也支持获取位置信息。
2.2、Address: JSON对象,地址信息
interface Address {
readonly attribute String country;
readonly attribute String province;
readonly attribute String city;
readonly attribute String district;
readonly attribute String street;
readonly attribute String poiName;
readonly attribute String postalCode;
readonly attribute String cityCode;
}
属性:
(1)、country: (String 类型 )国家。如“中国”,如果无法获取此信息则返回undefined。
(2)、province: (String 类型 )省份名称。如“北京市”,如果无法获取此信息则返回undefined。
(3)、city: (String 类型 )城市名称。如“北京市”,如果无法获取此信息则返回undefined。
(4)、district: (String 类型 )区(县)名称。如“朝阳区”,如果无法获取此信息则返回undefined。
(5)、street: (String 类型 )街道和门牌信息。如“酒仙桥路”,如果无法获取此信息则返回undefined。
(6)、poiName: (String 类型 )POI信息。如“电子城.国际电子总部”,如果无法获取此信息则返回undefined。
(7)、postalCode: (String 类型 )邮政编码。如“100016”,如果无法获取此信息则返回undefined。
(8)、cityCode: (String 类型 )城市代码。如“010”,如果无法获取此信息则返回undefined。
2.3、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;
}
属性:
(1)、latitude: (Number 类型 )坐标纬度值。数据类型对象,地理坐标中的纬度值。
(2)、longitude: (Number 类型 )坐标经度值。数据类型对象,地理坐标中的经度值。
(3)、altitude: (Number 类型 )海拔信息。数据类型对象,如果无法获取此信息,则此值为空(null)。
(4)、accuracy: (Number 类型 )地理坐标信息的精确度信息。数据类型对象,单位为米,其有效值必须大于0。
(5)、altitudeAccuracy: (Number 类型 )海拔的精确度信息。数据类型对象,单位为米,其有效值必须大于0。如果无法获取海拔信息,则此值为空(null)。
(6)、heading: (Number 类型 )表示设备移动的方向。数据类型对象,范围为0到360,表示相对于正北方向的角度。如果无法获取此信息,则此值为空(null)。如果设备没有移动则此值为NaN。
(7)、speed: (Number 类型 )表示设备移动的速度。数据类型对象,单位为米每秒(m/s),其有效值必须大于0。如果无法获取速度信息,则此值为空(null)。
2.4、PositionOptions: JSON对象,监听设备位置信息参数
属性:
(1)、enableHighAccuracy: (Boolean 类型 )是否高精确度获取位置信息。高精度获取表示需要使用更多的系统资源,默认值为false。
(2)、timeout: (Number 类型 )获取位置信息的超时时间。单位为毫秒(ms),默认值为不超时。如果在指定的时间内没有获取到位置信息则触发错误回调函数。
(3)、maximumAge: (Number 类型 )获取位置信息的缓存时间。单位为毫秒(ms),默认值为0(立即更新获取)。如果设备缓存的位置信息超过指定的缓存时间,将重新更新位置信息后再返回。
(4)、provider: (String 类型 )优先使用的定位模块。可取以下供应者: "system":表示系统定位模块,支持wgs84坐标系; "baidu":表示百度定位模块,支持gcj02/bd09/bd09ll坐标系; "amap":表示高德定位模板,支持gcj02坐标系。 默认值按以下优先顺序获取(amap>baidu>system),若指定的provider不存在或无效则返回错误回调。 注意:百度/高德定位模块需要配置百度/高德地图相关参数才能正常使用。平台支持Android - 2.2+ (支持),iOS - 4.5+ (支持): provider为“baidu”时,仅支持bd09ll坐标系,暂不支持高德定位模块。
[html] view plain copy print?
- <!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 );
- },{provider:‘baidu‘});
- }
- </script>
- </head>
- <body >
- </body>
- </html>
<!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 ); },{provider:‘baidu‘}); } </script> </head> <body > </body> </html>
(5)、coordsType: (String 类型 )指定获取的定位数据坐标系类型。可取以下坐标系类型: “wgs84”:表示WGS-84坐标系; “gcj02”:表示国测局经纬度坐标系; “bd09”:表示百度墨卡托坐标系; “bd09ll”:表示百度经纬度坐标系; provider为“system”时,默认使用“wgs84”类型;provider为“baidu”是,默认使用“bd09ll”类型。 如果设置的坐标系类型provider不支持,则返回错误。
(6)、geocode: (Boolean 类型 )是否解析地址信息。解析的地址信息保存到Position对象的address、addresses属性中,true表示解析地址信息,false表示不解析地址信息,返回的Position对象的address、addresses属性值为undefined,默认值为true。 如果解析地址信息失败则返回的Position对象的address、addresses属性值为null。
2.5、GeolocationError: JSON对象,定位错误信息
interface GeolocationError {
const Number PERMISSION_DENIED = 1;
const Number POSITION_UNAVAILABLE = 2;
const Number TIMEOUT = 3;
const Number UNKNOWN_ERROR = 4;
readonly attribute Number code;
readonly attribute String message;
}
常量:
PERMISSION_DENIED: (Number 类型 )访问权限被拒绝。系统不允许程序获取定位功能,错误代码常量值为1。
POSITION_UNAVAILABLE: (Number 类型 )位置信息不可用。无法获取有效的位置信息,错误代码常量值为2。
TIMEOUT: (Number 类型 )获取位置信息超时。无法在指定的时间内获取位置信息,错误代码常量值为3。
UNKNOWN_ERROR: (Number 类型 )未知错误。其它未知错误导致无法获取位置信息,错误代码常量值为4。
属性:
code: (Number 类型 )错误代码。取值范围为GeolocationError对象的常量值。
message: (String 类型 )错误描述信息。详细错误描述信息。
3、回调方法
3.1、GeolocationSuccessCallback: 获取设备位置信息成功的回调函数
void onSuccess( position ) {
// Get Position code.
}
参数:position: ( Position ) 必选 设备的地理位置信息,参考Position
返回值:void : 无
示例:
[html] view plain copy print?
- <!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 );
- console.log( "Geolocation info: " + JSON.stringify(p) );
- }, function ( e ) {
- console.log("Gelocation Error: code - "+e.code+"; message - "+e.message);
- } );
- }
- </script>
- </head>
- <body >
- </body>
- </html>
<!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 ); console.log( "Geolocation info: " + JSON.stringify(p) ); }, function ( e ) { console.log("Gelocation Error: code - "+e.code+"; message - "+e.message); } ); } </script> </head> <body > </body> </html>
3.1、GeolocationErrorCallback: 获取设备位置信息失败的回调函数
function void onGeolocationError( GeolocationError error ) {
// Handle error
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息
}
参数:
error: ( GeolocationError ) 必选 获取位置操作的错误信息,可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:void : 无
示例:
[html] view plain copy print?
- <!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 ) {
- console.log( "Geolocation\nLatitude:" + p.coords.latitude + "\nLongitude:" + p.coords.longitude + "\nAltitude:" + p.coords.altitude );
- }, function ( e ) {
- console.log("Gelocation Error: code - "+e.code+"; message - "+e.message);
- switch(e.code) {
- case e.PERMISSION_DENIED:
- alert("User denied the request for Geolocation.");
- break;
- case e.POSITION_UNAVAILABLE:
- alert("Location information is unavailable.");
- break;
- case e.TIMEOUT:
- alert("The request to get user location timed out.");
- break;
- case e.UNKNOWN_ERROR:
- alert("An unknown error occurred.");
- break;
- }
- } );
- }
- </script>
- </head>
- <body >
- </body>
- </html>
原文地址:https://www.cnblogs.com/zxh1919/p/8135783.html