geolocation

Geolocation模块管理设备位置信息，用于获取地理位置信息，如经度、纬度等。通过plus.geolocation可获取设备位置管理对象。虽然W3C已经提供标准API获取位置信息，但在某些平台存在差异或未实现，为了保持各平台的统一性，定义此规范接口获取位置信息。

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Geolocation": {
  7.         "description": "位置信息"
  8.     }
  9. }
  10. }
  11.

getCurrentPosition

获取当前设备位置信息

  2. void plus.geolocation.getCurrentPosition(successCB, errorCB, option);
  3.

说明：

位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取，由于获取位置信息可能需要较长的时间，当成功获取位置信息后将通过successCB回调函数返回。

参数：

返回值：

void: 无

平台支持：

  • Android- 2.2+(支持): 支持
  • iOS- 4.3+(支持): 支持

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <title>Geolocation Example</title>
  7.     <script type="text/javascript" >
  8. // 扩展API加载完毕后调用onPlusReady回调函数 
  9. document.addEventListener('plusready', onPlusReady, false);
  10. // 扩展API加载完毕，现在可以正常调用扩展API
  11. function onPlusReady(){
  12.     plus.geolocation.getCurrentPosition(function(p){
  13.         alert('Geolocation\nLatitude:' + p.coords.latitude + '\nLongitude:' + p.coords.longitude + '\nAltitude:' + p.coords.altitude);
  14.     }, function(e){
  15.         alert('Geolocation error: ' + e.message);
  16.     } );
  17. }
  18.     </script>
  19.     </head>
  20.     <body >
  21.     </body>
  22. </html>
  23.

uni-app使用plus注意事项

watchPosition

监听设备位置变化信息

  2. Number plus.geolocation.watchPosition(successCB, errorCB, option);
  3.

说明：

位置信息将通过手机GPS设备或其它信息如IP地址、移动网络信号获取。当位置信息更新后将通过successCB回调函数返回。位置信息获取失败则调用回调函数errorCB。

参数：

返回值：

Number: 用于标识位置信息监听器，可通过clearWatch方法取消监听。

平台支持：

  • Android- 2.2+(支持): 支持
  • iOS- 4.3+(支持): 支持

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8">
  6.     <title>Geolocation Example</title>
  7.     <script type="text/javascript" >
  8. // 扩展API加载完毕后调用onPlusReady回调函数 
  9. document.addEventListener('plusready', onPlusReady, false);
  10. // 扩展API加载完毕，现在可以正常调用扩展API
  11. function onPlusReady(){
  12.     plus.geolocation.watchPosition(function(p){
  13.             alert('Geolocation\nLatitude:' + p.coords.latitude + '\nLongitude:' + p.coords.longitude + '\nAltitude:' + p.coords.altitude);
  14.     }, function(e){
  15.         alert('Geolocation error: ' + e.message);
  16.     } ); 
  17. }
  18.     </script>
  19.     </head>
  20.     <body >
  21.     </body>
  22. </html>
  23.

uni-app使用plus注意事项

clearWatch

关闭监听设备位置信息

  2. void plus.geolocation.clearWatch(watchId);
  3.

参数：

  • watchId: (Number)必选 需要取消的位置监听器标识，调用watchPosition方法的返回值。

返回值：

void: 无

平台支持：

  • Android- 2.2+(支持): 支持
  • iOS- 4.3+(支持): 支持

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.         <meta charset="utf-8">
  6.         <title>Geolocation Example</title>
  7.         <script type="text/javascript" >
  8. // 扩展API加载完毕后调用onPlusReady回调函数
  9. document.addEventListener('plusready', onPlusReady, false);
  10. // 扩展API加载完毕，现在可以正常调用扩展API
  11. var wid = null;
  12. function onPlusReady(){
  13.     wid = plus.geolocation.watchPosition(function(p){
  14.         alert('Geolocation\nLatitude:' + p.coords.latitude + '\nLongitude:' + p.coords.longitude + '\nAltitude:' + p.coords.altitude);
  15.     }, function(e){
  16.         alert('Geolocation error: ' + e.message);
  17.     });
  18. }
  19. function cancel(){
  20.     plus.geolocation.clearWatch(wid);
  21.     wid = null;
  22. }
  23.         </script>
  24.     </head>
  25.     <body >
  26.         <input type="button" value="Cancel" onclick="cancel();"></input>
  27.     </body>
  28. </html>
  29.

uni-app使用plus注意事项

Position

JSON对象，设备位置信息数据


interface Position {
    readonly attribute Coordinates coords;
    readonly attribute String coordsType;
    readonly attribute Number timestamp;
    readonly attribute Address address;
    readonly attribute String addresses;
}

属性：

  • coords: (Coordinates类型)地理坐标信息，包括经纬度、海拔、速度等信息

  • coordsType: (String类型)获取到地理坐标信息的坐标系类型可取以下坐标系类型："wgs84"：表示WGS-84坐标系；"gcj02"：表示国测局经纬度坐标系；"bd09"：表示百度墨卡托坐标系，仅百度定位支持；"bd09ll"：表示百度经纬度坐标系，仅百度定位支持。

  • timestamp: (Number类型)获取到地理坐标的时间戳信息时间戳值为从1970年1月1日至今的毫秒数。

  • address: (Address类型)获取到地理位置对应的地址信息获取地址信息需要连接到服务器进行解析，所以会消耗更多的资源，如果不需要获取地址信息可通过设置PositionOptions参数的geocode属性值为false避免获取地址信息。如果没有获取到地址信息则返回undefined。

平台支持

  • Android - 2.3+ (支持): 使用系统定位模块无法获取位置信息。
  • iOS - 5.1+ (支持): 系统定位模块也支持获取位置信息。
    • addresses: (String类型)获取完整地址描述信息如果没有获取到地址信息则返回undefined。

平台支持

  • Android - 2.3+ (支持): 使用系统定位模块无法获取位置信息。
  • iOS - 5.1+ (支持): 系统定位模块也支持获取位置信息。

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 streetNum;
    readonly attribute String poiName;
    readonly attribute String postalCode;
    readonly attribute String cityCode;
}

属性：

  • country: (String类型)国家如“中国”，如果无法获取此信息则返回undefined。

  • province: (String类型)省份名称如“北京市”，如果无法获取此信息则返回undefined。

  • city: (String类型)城市名称如“北京市”，如果无法获取此信息则返回undefined。

  • district: (String类型)区（县）名称如“朝阳区”，如果无法获取此信息则返回undefined。

  • street: (String类型)街道信息如“酒仙桥路”，如果无法获取此信息则返回undefined。

  • streetNum: (String类型)获取街道门牌号信息如“3号”，如果无法获取此信息则返回undefined。

  • poiName: _(String类型)_POI信息如“电子城．国际电子总部”，如果无法获取此信息则返回undefined。

  • postalCode: (String类型)邮政编码如“100016”，如果无法获取此信息则返回undefined。

  • cityCode: (String类型)城市代码如“010”，如果无法获取此信息则返回undefined。

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）。

PositionOptions

JSON对象，监听设备位置信息参数

属性：

  • enableHighAccuracy: (Boolean类型)是否高精确度获取位置信息高精度获取表示需要使用更多的系统资源，默认值为false。

  • timeout: (Number类型)获取位置信息的超时时间单位为毫秒（ms），默认值为不超时。如果在指定的时间内没有获取到位置信息则触发错误回调函数。

  • maximumAge: (Number类型)获取位置信息的间隔时间单位为毫秒（ms），默认值为5000（即5秒）。调用plus.geolocation.watchPosition时为更新位置信息的间隔时间。注意：在不同定位模块下支持范围值可能不同，如百度定位模块的间隔范围为大于等于1秒，如果设置的值小于最小值则使用最小值。

  • provider: (String类型)优先使用的定位模块可取以下供应者："system"：表示系统定位模块，支持wgs84坐标系；"baidu"：表示百度定位模块，支持gcj02/bd09/bd09ll坐标系；"amap"：表示高德定位模块，支持gcj02坐标系。默认值按以下优先顺序获取（amap>baidu>system），若指定的provider不存在或无效则返回错误回调。注意：百度/高德定位模块需要配置百度/高德地图相关参数才能正常使用。

平台支持

  • Android - 2.2+ (支持)
  • iOS - 4.5+ (支持): HBuilderX2.4.3+版本支持高德定位模块，默认使用优先级（amap>baidu>system）；HBuilderX2.4.2及以前版本不支持高德定位模块，默认使用系统定位模块。

<!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>

  • coordsType: (String类型)指定获取的定位数据坐标系类型可取以下坐标系类型："wgs84"：表示WGS-84坐标系；"gcj02"：表示国测局经纬度坐标系；"bd09"：表示百度墨卡托坐标系；"bd09ll"：表示百度经纬度坐标系；provider为"system"时，支持wgs84坐标系，默认使用"wgs84"坐标系；provider为"baidu"时，支持gcj02/bd09/bd09ll坐标系，默认使用"gcj02"坐标系；provider为"amap"时，支持gcj02坐标系，默认使用"gcj02"坐标系。如果设置的坐标系类型provider不支持，则返回错误。

  • geocode: (Boolean类型)是否解析地址信息解析的地址信息保存到Position对象的address、addresses属性中，true表示解析地址信息，false表示不解析地址信息，返回的Position对象的address、addresses属性值为undefined，默认值为true。如果解析地址信息失败则返回的Position对象的address、addresses属性值为null。

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;
}

常量：

  • PERMISSIONDENIED: (Number类型)_访问权限被拒绝系统不允许程序获取定位功能，错误代码常量值为1。

  • POSITIONUNAVAILABLE: (Number类型)_位置信息不可用无法获取有效的位置信息，错误代码常量值为2。

  • TIMEOUT: (Number类型)获取位置信息超时无法在指定的时间内获取位置信息，错误代码常量值为3。

  • UNKNOWNERROR: (Number类型)_未知错误其它未知错误导致无法获取位置信息，错误代码常量值为4。

属性：

  • code: (Number类型)错误代码取值范围为GeolocationError对象的常量值。

  • message: (String类型)错误描述信息详细错误描述信息。

GeolocationSuccessCallback

获取设备位置信息成功的回调函数


void onSuccess( position ) {
    // Get Position code.
}

参数：

  • position: (Position)必选 设备的地理位置信息，参考Position

返回值：

void: 无

示例：


<!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>

uni-app使用plus注意事项

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

示例：


<!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>

uni-app使用plus注意事项