# geolocation

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

## 方法：

- getCurrentPosition: 获取当前设备位置信息
- watchPosition: 监听设备位置变化信息
- clearWatch: 关闭监听设备位置信息

## 对象：

- Position: JSON对象，设备位置信息数据
- Address: JSON对象，地址信息
- Coordinates: JSON对象，地理坐标信息
- PositionOptions: JSON对象，监听设备位置信息参数
- GeolocationError: JSON对象，定位错误信息

## 回调方法：

- GeolocationSuccessCallback: 获取设备位置信息成功的回调函数
- GeolocationErrorCallback: 获取设备位置信息失败的回调函数

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Geolocation": {
    		"description": "位置信息"
    	}
    }
    }

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

- addresses: (String 类型 )获取完整地址描述信息

  如果没有获取到地址信息则返回undefined。

# 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不存在或无效则返回错误回调。 注意：百度/高德定位模块需要配置百度/高德地图相关参数才能正常使用。

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

## 属性：

- code: (Number 类型 )错误代码

  取值范围为GeolocationError对象的常量值。

- message: (String 类型 )错误描述信息

  详细错误描述信息。

# GeolocationSuccessCallback

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

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

## 参数：

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

## 返回值：

void : 无

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