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>