html5+ geolocation-位置信息

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 类型 )_获取到地理坐标信息的坐标系类型

  可取以下坐标系类型： “gps”：表示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”类型；provider为“baidu”是，默认使用“bd09ll”类型。 如果设置的坐标系类型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 : 无

<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
		<meta name="HandheldFriendly" content="true" />
		<meta name="MobileOptimized" content="320" />
		<title>Hello H5+</title>
		<script type="text/javascript">
			var watchId;
			function geoInf(position) {
				var str = "";
				str += "地址：" + position.addresses + "\n"; //获取地址信息
				str += "坐标类型：" + position.coordsType + "\n";
				var timeflag = position.timestamp; //获取到地理位置信息的时间戳；一个毫秒数；
				str += "时间戳：" + timeflag + "\n";
				var codns = position.coords; //获取地理坐标信息；
				var lat = codns.latitude; //获取到当前位置的纬度；
				str += "纬度：" + lat + "\n";
				var longt = codns.longitude; //获取到当前位置的经度
				str += "经度：" + longt + "\n";
				var alt = codns.altitude; //获取到当前位置的海拔信息；
				str += "海拔：" + alt + "\n";
				var accu = codns.accuracy; //地理坐标信息精确度信息；
				str += "精确度：" + accu + "\n";
				var altAcc = codns.altitudeAccuracy; //获取海拔信息的精确度；
				str += "海拔精确度：" + altAcc + "\n";
				var head = codns.heading; //获取设备的移动方向；
				str += "移动方向：" + head + "\n";
				var sped = codns.speed; //获取设备的移动速度；
				str += "移动速度：" + sped;
				console.log(JSON.stringify(position));
				outLine(str);
			}

			function getPos() {
				console.log("获取位置信息:");
				plus.geolocation.getCurrentPosition(geoInf, function (e) {
					console.log("获取位置信息失败：" + e.message);
				}, {
					geocode: false
				});
			}

			function watchPos() {
				if (watchId) {
					return;
				}
				watchId = plus.geolocation.watchPosition(function (p) {
					console.log("监听位置变化信息:");
					geoInf(p);
				}, function (e) {
					console.log("监听位置变化信息失败：" + e.message);
				}, {
					geocode: false
				});
			}

			function clearWatch() {
				if (watchId) {
					console.log("停止监听位置变化信息");
					plus.geolocation.clearWatch(watchId);
					watchId = null;
				}
			}
			// 通过定位模块获取位置信息
			function getGeocode() {
				console.log("获取定位位置信息:");
				plus.geolocation.getCurrentPosition(geoInf, function (e) {
					console.log("获取定位位置信息失败：" + e.message);
				}, {
					geocode: true
				});
			}

		</script>
	</head>
	<body>
		<header id="header">
			<div class="nvbt iback" onclick="back()"></div>
			<div class="nvtt">Geolocation</div>
			<div class="nvbt idoc" onclick="openDoc('Geolocation Document','/doc/geolocation.html')"></div>
		</header>
		<div id="dcontent" class="dcontent">
			<br />
			<ul class="dlist">
				<li class="ditem" onclick="getPos()">获取设备位置信息</li>
				<li class="ditem" onclick="watchPos()">监听设备位置信息</li>
				<li class="ditem" onclick="clearWatch()">停止监听</li>
			</ul>
			<br />
			<div class="button" onclick="getGeocode()">获取定位信息</div>
			<p class="des">
				Android平台推荐配置高德或百度定位，避免在部分设备（如三星、HTC等）可能无法获取位置信息的问题。
			</p>
		</div>
		<div id="output">
			Geolocation可获取设备位置信息，包括经度、纬度、高度等信息。
		</div>
	</body>
</html>