Geolocation Document

geolocation

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

方法:

对象:

回调方法:

权限:

permissions

"Geolocation": {
	"description": "访问设备位置信息"
}
			

getCurrentPosition

获取当前设备位置信息

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

说明:

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

参数:

返回值:

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 );
	}, function ( e ) {
		alert( "Geolocation error: " + e.message );
	} );
}
	</script>
	</head>
	<body >
	</body>
</html>
				

watchPosition

监听设备位置变化信息

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

说明:

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

参数:

返回值:

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

平台支持:

示例:

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

clearWatch

关闭监听设备位置信息

void plus.geolocation.clearWatch( watchId );
				

参数:

返回值:

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
var wid = null;
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 );
	} );
}
function cancel() {
	plus.geolocation.clearWatch( wid );
	wid = null;
}
		</script>
	</head>
	<body >
		<input type="button" value="Cancel" onclick="cancel();" ></input>
	</body>
</html>
				

Position

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

interface Position {
	readonly attribute Coordinates coords;
	readonly attribute DOMTimeStamp timestamp;
}
				

属性:

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

属性:

PositionOption

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

属性:

GeolocationSuccessCallback

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

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

参数:

返回值:

void : 无

GeolocationErrorCallback

获取设备位置信息失败的回调函数

void onError( error ) {
	// Handle error
}
				

参数:

返回值:

void : 无