PhoneGap API帮助文档翻译—Geolocation（地理位置） PhoneGap API帮助文档翻译—Geolocation（地理位置）

samwong

浏览: 282161 次
性别:
来自: 北京

最近访客更多访客>>

wenjinshan

ShangJinDeLiuMang

dotfeng

kingrom

博主相关

博客

微博

相册

留言

关于我

文章分类

社区版块

存档分类

PhoneGap API帮助文档翻译—Geolocation（地理位置）

“

geolocation对象提供了对设备GPS传感器的访问。

Geolocation提供设备的位置信息，例如经度和纬度。位置信息的常见来源包括全球定位系统（GPS），以及通过诸如IP地址、RFID、WiFi和蓝牙的MAC地址、和GSM/CDMA手机ID的网络信号所做的推断。不能保证该API返回的是设备的真实位置信息。

这个API是基于W3C Geo location API Specification实现的。有些设备已经提供了对该规范的实现，对于这些设备采用内置实现而非使用PhoneGap的实现。对于没有地理位置支持的设备，PhoneGap的实现应该是完全兼容W3C规范。

方法：

geolocation.getCurrentPosition
geolocation.watchPosition
geolocation.clearWatch

参数：

geolocationSuccess
geolocationError
geolocationOptions

对象(只读)：

Position
PositionError
Coordinates

geolocation.getCurrentPosition

返回一个Position对象表示设备的当前位置。

参数：

geolocationSuccess：获取位置信息成功时调用的回调函数，参数为当前的位置信息。
geolocationError：（可选项）获取位置信息出错时调用的回调函数。
geolocationOptions：（可选项）地理位置选项。

说明：

geolocation.getCurrentPositon是一个异步函数。它回传一个包含设备当前位置信息的Position对象给geolocationSuccess回调函数。如果发生错误，触发geolocationError回调函数并传递一个PositionError对象。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false);
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		navigator.geolocation.getCurrentPosition(onSuccess, onError);
	}
	
	// 获取位置信息成功时调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '           + position.coords.latitude              + '<br />' +
							'Longitude: '          + position.coords.longitude             + '<br />' +
							'Altitude: '           + position.coords.altitude              + '<br />' +
							'Accuracy: '           + position.coords.accuracy              + '<br />' +
							'Altitude Accuracy: '  + position.coords.altitudeAccuracy      + '<br />' +
							'Heading: '            + position.coords.heading               + '<br />' +
							'Speed: '              + position.coords.speed                 + '<br />' +
							'Timestamp: '          + new Date(position.timestamp)          + '<br />';
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
</body>
</html>

geolocation.watchPosition

监视设备的当前位置的变化。

参数：

geolocationSuccess： 获取位置信息成功时调用的回调函数，参数为当前位置信息。
geolocationError：（可选项）获取位置信息出错时调用的回调函数。
geolocationOptions：（可选项）地理位置选项。

返回值：

String：返回的watch id是位置监视String：返回的watch id是位置监视周期的引用。可以通过geolocation.clearWatch调用该watch ID以停止对位置变化的监视。

说明：

geolocation.watchPosition是一个异步函数。当检测到设备的位置发生改变时，它返回设备的当前位置。当设备检索到一个新的位置，会触发geolocationSuccess回调函数并传递一个Position对象作为参数。如果发生错误，会触发geolocationError回调函数并传递一个PositionError对象。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	var watchID = null;
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		// 每隔3秒钟更新一次
		var options = { frequency: 3000 };
		watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
	}
	
	// 获取位置信息成功时调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
							'Longitude: ' + position.coords.longitude     + '<br />' +
							<hr />''      + element.innerHTML;
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
</body>
</html>

geolocation.clearWatch

停止watchID参数指向的设备位置变化监视。

参数：

watchID：要清除的watchPosition周期的id。（字符串类型）

说明：

geolocation.clearWatch函数通过清除watchID指向的geolocation.watchPosition来停止对设备位置变化的监视。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	var watchID = null;
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		// 每隔3秒钟更新一次
		var options = { frequency: 3000 };
		watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
	}
	
	// 获取位置信息成功时调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
						   'Longitude: ' + position.coords.longitude     + '<br />' +
						   '<hr />'      + element.innerHTML;
	}
	
	// 清除前述已经开始的监视
	function clearWatch() {
		if (watchID != null) {
			navigator.geolocation.clearWatch(watchID);
			watchID = null;
		}
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
	<button onclick="clearWatch();">Clear Watch</button>
</body>
</html>

geolocationSuccess

当得到一个有效地理位置信息时，此用户回调函数被调当获得一个地理位置信息时，此用户回调函数被调用。

参数：

position：设备返回的地理位置信息。（Position类型）

范例：

geolocationError

当geolocation函数发生错误时，此用户回调函数被调用。

参数：

error：设备返回的错误信息。（PositionError类型）

geolocationOptions

用户定制地理位置检索的可选参数。

选项：

frequency：以毫秒为单位的检索位置周期。这个选项并非W3C规范的一部分，未来会被删除并用maximumAge来替代该选项。（数字类型）（默认值：10000）
enableHighAccuracy：提供一个表明应用程序希望获得最佳可能结果的提示。（布尔类型）
timeout：允许的以毫秒为单位的最大时间间隔，该时间间隔是从geolocation.getCurrentPosition或geolocation.watchPosition的调用到相应的geolocationSuccess回调函数被调用。（数字类型）
maximumAge：应用程序将接受一个缓存的位置信息，当该缓存的位置信息的年龄不大于此参数设定值，单位是毫秒。（数字类型）

Android的特异情况：

除非enableHighAccuracy选项被设定为true，否则Android 2.X模拟器不会返回一个地理位置结果。

Position

包含由geolocation API创建的Position坐标信息。

属性：

coords：一系列地理坐标。（Coordinates类型）
timestamp：以毫秒为单位的coords的创建时间戳。（DOMTimeStamp类型）

说明：

Position对象是由PhoneGap创建和填充的，并通过一个回调函数返回用户。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PHoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		navigator.geolocation.getCurrentPosition(onSuccess, onError);
	}
	
	// 获取位置信息成功后调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '           + position.coords.latitude              + '<br />' +
							'Longitude: '          + position.coords.longitude             + '<br />' +
							'Altitude: '           + position.coords.altitude              + '<br />' +
							'Accuracy: '           + position.coords.accuracy              + '<br />' +
							'Altitude Accuracy: '  + position.coords.altitudeAccuracy      + '<br />' +
							'Heading: '            + position.coords.heading               + '<br />' +
							'Speed: '              + position.coords.speed                 + '<br />' +
							'Timestamp: '          + new Date(position.timestamp)          + '<br />';
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
</body>
</html>

iPhone的特异情况：

timestamp：单位为秒而非毫秒。

一种变通方法是手动将时间戳转换为毫秒（*1000）：

PositionError

当发生错误时，一个PositionError对象会传递给geolocationError回调函数。

属性：

code：一个在下面常量列表中定义的错误代码。
message：说明错误细节的错误信息。

常量：

PositionError.PERMISSIONPositionError.PERMISSION_DENIED：权限被拒绝
PositionError.POSITION_UNAVAILABLE：位置不可用
PositionError.TIMEOUT：超时

说明：

当使用Geolocation发生错误时，一个PositionError对象会作为geolocationError回调函数的参数传递给用户。

Coordinates

一系列用来描述位置的地理坐标信息的属性。

属性：

latitude：以十进制表示的纬度。（数字类型）
longitude：以十进制表示的经度。（数字类型）
altitude：位置相对于椭圆球面的高度，单位为米。（数字类型）
accuracy：以米为单位的纬度和经度坐标的精度水平。（数字类型）
altitudeAccuracy：以米为单位的高度坐标的精度水平。（数字类型）
heading：运动的方向，通过相对正北做顺时针旋转的角度指定。（数字类型）
speed：以米/秒为单位的设备当前地面速度。（数字类型）

说明：

作为Position对象的一部分，Coordinates对象是由PhoneGap创建和填充的。该Position对象会作为一个回调函数的参数返回用户。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Geolocation Position Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 设置一个当PhoneGap加载完毕后触发的事件
	document.addEventListener("deviceready", onDeviceReady, false);
	
	// PhoneGap加载完毕并就绪
	function onDeviceReady() {
		navigator.geolocation.getCurrentPosition(onSuccess, onError);
	}
	
	// 显示位置信息中的“Position”属性
	function onSuccess(position) {
		var div = document.getElementById('myDiv');
	
		div.innerHTML = 'Latitude: '             + position.coords.latitude  + '<br/>' +
						'Longitude: '            + position.coords.longitude + '<br/>' +
						'Altitude: '             + position.coords.altitude  + '<br/>' +
						'Accuracy: '             + position.coords.accuracy  + '<br/>' +
						'Altitude Accuracy: '    + position.coords.altitudeAccuracy  + '<br/>' +
						'Heading: '              + position.coords.heading   + '<br/>' +
						'Speed: '                + position.coords.speed     + '<br/>';
	}
	
	// 如果获取位置信息出现问题，则显示一个警告
	function onError() {
		alert('onError!');
	}
 
</script>
</head>
<body>
	<div id="myDiv"></div></body>
</html>

Android的特异情况：

altitudeAccuracy： Android设备上不支持该属性，返回值总是null。

“

geolocation对象提供了对设备GPS传感器的访问。

方法：

geolocation.getCurrentPosition
geolocation.watchPosition
geolocation.clearWatch

参数：

geolocationSuccess
geolocationError
geolocationOptions

对象(只读)：

Position
PositionError
Coordinates

geolocation.getCurrentPosition

返回一个Position对象表示设备的当前位置。

参数：

geolocationSuccess：获取位置信息成功时调用的回调函数，参数为当前的位置信息。
geolocationError：（可选项）获取位置信息出错时调用的回调函数。
geolocationOptions：（可选项）地理位置选项。

说明：

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

geolocation.watchPosition

监视设备的当前位置的变化。

参数：

geolocationSuccess： 获取位置信息成功时调用的回调函数，参数为当前位置信息。
geolocationError：（可选项）获取位置信息出错时调用的回调函数。
geolocationOptions：（可选项）地理位置选项。

返回值：

String：返回的watch id是位置监视String：返回的watch id是位置监视周期的引用。可以通过geolocation.clearWatch调用该watch ID以停止对位置变化的监视。

说明：

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	var watchID = null;
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		// 每隔3秒钟更新一次
		var options = { frequency: 3000 };
		watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
	}
	
	// 获取位置信息成功时调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
							'Longitude: ' + position.coords.longitude     + '<br />' +
							<hr />''      + element.innerHTML;
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
</body>
</html>

geolocation.clearWatch

停止watchID参数指向的设备位置变化监视。

参数：

watchID：要清除的watchPosition周期的id。（字符串类型）

说明：

geolocation.clearWatch函数通过清除watchID指向的geolocation.watchPosition来停止对设备位置变化的监视。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	var watchID = null;
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		// 每隔3秒钟更新一次
		var options = { frequency: 3000 };
		watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
	}
	
	// 获取位置信息成功时调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
						   'Longitude: ' + position.coords.longitude     + '<br />' +
						   '<hr />'      + element.innerHTML;
	}
	
	// 清除前述已经开始的监视
	function clearWatch() {
		if (watchID != null) {
			navigator.geolocation.clearWatch(watchID);
			watchID = null;
		}
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
	<button onclick="clearWatch();">Clear Watch</button>
</body>
</html>

geolocationSuccess

当得到一个有效地理位置信息时，此用户回调函数被调当获得一个地理位置信息时，此用户回调函数被调用。

参数：

position：设备返回的地理位置信息。（Position类型）

范例：

geolocationError

当geolocation函数发生错误时，此用户回调函数被调用。

参数：

error：设备返回的错误信息。（PositionError类型）

geolocationOptions

用户定制地理位置检索的可选参数。

选项：

frequency：以毫秒为单位的检索位置周期。这个选项并非W3C规范的一部分，未来会被删除并用maximumAge来替代该选项。（数字类型）（默认值：10000）
enableHighAccuracy：提供一个表明应用程序希望获得最佳可能结果的提示。（布尔类型）
timeout：允许的以毫秒为单位的最大时间间隔，该时间间隔是从geolocation.getCurrentPosition或geolocation.watchPosition的调用到相应的geolocationSuccess回调函数被调用。（数字类型）
maximumAge：应用程序将接受一个缓存的位置信息，当该缓存的位置信息的年龄不大于此参数设定值，单位是毫秒。（数字类型）

Android的特异情况：

除非enableHighAccuracy选项被设定为true，否则Android 2.X模拟器不会返回一个地理位置结果。

Position

包含由geolocation API创建的Position坐标信息。

属性：

coords：一系列地理坐标。（Coordinates类型）
timestamp：以毫秒为单位的coords的创建时间戳。（DOMTimeStamp类型）

说明：

Position对象是由PhoneGap创建和填充的，并通过一个回调函数返回用户。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

<!DOCTYPE html>
<html>
<head>	
<title>Device Properties Example</title>
 
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
 
	// 等待加载PHoneGap
	document.addEventListener("deviceready", onDeviceReady, false); 
	
	// PhoneGap加载完毕
	function onDeviceReady() {
		navigator.geolocation.getCurrentPosition(onSuccess, onError);
	}
	
	// 获取位置信息成功后调用的回调函数
	function onSuccess(position) {
		var element = document.getElementById('geolocation');
		element.innerHTML = 'Latitude: '           + position.coords.latitude              + '<br />' +
							'Longitude: '          + position.coords.longitude             + '<br />' +
							'Altitude: '           + position.coords.altitude              + '<br />' +
							'Accuracy: '           + position.coords.accuracy              + '<br />' +
							'Altitude Accuracy: '  + position.coords.altitudeAccuracy      + '<br />' +
							'Heading: '            + position.coords.heading               + '<br />' +
							'Speed: '              + position.coords.speed                 + '<br />' +
							'Timestamp: '          + new Date(position.timestamp)          + '<br />';
	}
	
	// onError回调函数接收一个PositionError对象
	function onError(error) {
		alert('code: '    + error.code    + '\n' +
			'message: ' + error.message + '\n');
	}
 
</script>
</head>
<body>
	<p id="geolocation">Finding geolocation...</p>
</body>
</html>

iPhone的特异情况：

timestamp：单位为秒而非毫秒。

一种变通方法是手动将时间戳转换为毫秒（*1000）：

PositionError

当发生错误时，一个PositionError对象会传递给geolocationError回调函数。

属性：

code：一个在下面常量列表中定义的错误代码。
message：说明错误细节的错误信息。

常量：

PositionError.PERMISSIONPositionError.PERMISSION_DENIED：权限被拒绝
PositionError.POSITION_UNAVAILABLE：位置不可用
PositionError.TIMEOUT：超时

说明：

当使用Geolocation发生错误时，一个PositionError对象会作为geolocationError回调函数的参数传递给用户。

Coordinates

一系列用来描述位置的地理坐标信息的属性。

属性：

latitude：以十进制表示的纬度。（数字类型）
longitude：以十进制表示的经度。（数字类型）
altitude：位置相对于椭圆球面的高度，单位为米。（数字类型）
accuracy：以米为单位的纬度和经度坐标的精度水平。（数字类型）
altitudeAccuracy：以米为单位的高度坐标的精度水平。（数字类型）
heading：运动的方向，通过相对正北做顺时针旋转的角度指定。（数字类型）
speed：以米/秒为单位的设备当前地面速度。（数字类型）

说明：

作为Position对象的一部分，Coordinates对象是由PhoneGap创建和填充的。该Position对象会作为一个回调函数的参数返回用户。

支持的平台：

Android
BlackBerry (OS 4.6)
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

完整的范例：

Android的特异情况：

altitudeAccuracy： Android设备上不支持该属性，返回值总是null。

分享到：

PhoneGap API帮助文档翻译—Notification（ ... | PhoneGap API帮助文档翻译—Events（事件） ...

2012-02-01 23:18
浏览 574
评论(0)
查看更多

发表评论

您还没有登录,请您登录后再发表评论

最近访客更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论

PhoneGap API帮助文档翻译—Geolocation（地理位置） PhoneGap API帮助文档翻译—Geolocation（地理位置）

PhoneGap API帮助文档翻译—Geolocation（地理位置）

评论

发表评论

相关推荐

最近访客 更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论

PhoneGap API帮助文档翻译—Geolocation（地理位置） PhoneGap API帮助文档翻译—Geolocation（地理位置）

PhoneGap API帮助文档翻译—Geolocation（地理位置）

评论

发表评论

相关推荐

最近访客更多访客>>