API Reference

Plugins

Native.js


geolocation

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

方法：

对象：

回调方法：

模块：

5+功能模块（permissions）


{
// ...
"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(){
	wid = plus.geolocation.watchPosition(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 String coordsType;
	readonly attribute Number timestamp;
	readonly attribute Address address;
	readonly attribute String addresses;
}

属性：

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

属性：

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

属性：

PositionOptions

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

属性：

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

常量：

属性：

GeolocationSuccessCallback

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


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

参数：

返回值：

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>

GeolocationErrorCallback

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


function void onGeolocationError( GeolocationError error ) {
	// Handle error
	var code = error.code; // 错误编码
	var message = error.message; // 错误描述信息
}

参数：

返回值：

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>