`

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

html5phonegap 
阅读更多

文章源自:http://blog.csdn.net/phonegapcn/article/details/6702864

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对象表示设备的当前位置。

 

navigator.geolocation.getCurrentPosition(geolocationSuccess,   
                                [geolocationError],   
                                [geolocationOptions]);

 参数：

 

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

说明：

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

支持的平台：

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

简单的范例：

 

//	获取位置信息成功时调用的回调函数
//	该方法接受一个“Position”对象，包含当前GPS坐标信息
var onSuccess = function(position) {
	alert('Latitude: '          + position.coords.latitude          + '\n' +
		'Longitude: '         + position.coords.longitude         + '\n' +
		'Altitude: '          + position.coords.altitude          + '\n' +
		'Accuracy: '          + position.coords.accuracy          + '\n' +
		'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
		'Heading: '           + position.coords.heading           + '\n' +
		'Speed: '             + position.coords.speed             + '\n' +
		'Timestamp: '         + new Date(position.timestamp)      + '\n');
};

// onError回调函数接收一个PositionError对象
function onError(error) {
	alert('code: '    + error.code    + '\n' +
		'message: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

 完整的范例：

 

 

<!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:监视设备的当前位置的变化。

 

 

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,  
                                         [geolocationError],  
                                         [geolocationOptions]);

 参数：

 

  • 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

简单的范例：

 

// 获取位置信息成功时调用的回调函数
// 该方法接受一个“Position”对象，包含当前GPS坐标信息
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');
}

// Options: 每隔3秒钟检索一次位置信息
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });

 完整的范例：

 

 

<!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参数指向的设备位置变化监视。

 

navigator.geolocation.clearWatch(watchID);

 参数：

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

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

支持的平台：

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

简单的范例：

// 选项: 每隔3秒钟检索一次位置信息
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });

// ...后继处理...

navigator.geolocation.clearWatch(watchID);

 完整的范例：

<!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类型）

范例：

function geolocationSuccess(position) {
	alert('Latitude: '          + position.coords.latitude          + '\n' +
		'Longitude: '         + position.coords.longitude         + '\n' +
		'Altitude: '          + position.coords.altitude          + '\n' +
		'Accuracy: '          + position.coords.accuracy          + '\n' +
		'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
		'Heading: '           + position.coords.heading           + '\n' +
		'Speed: '             + position.coords.speed             + '\n' +
		'Timestamp: '         + new Date(position.timestamp)      + '\n');
}

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

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

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

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };

 选项：

  • 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类型）

支持的平台：

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

简单的范例：

// 获取位置信息成功后调用的回调函数
var onSuccess = function(position) {
	alert('Latitude: '          + position.coords.latitude          + '\n' +
		'Longitude: '         + position.coords.longitude         + '\n' +
		'Altitude: '          + position.coords.altitude          + '\n' +
		'Accuracy: '          + position.coords.accuracy          + '\n' +
		'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
		'Heading: '           + position.coords.heading           + '\n' +
		'Speed: '             + position.coords.speed             + '\n' +
		'Timestamp: '         + new Date(position.timestamp)      + '\n');
};

// onError回调函数接收一个PositionError对象
function onError(error) {
	alert('code: '    + error.code    + '\n' +
		'message: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

 完整的范例：

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

var onSuccess = function(position) {
	alert('Latitude: '  + position.coords.latitude             + '\n' +
		'Longitude: ' + position.coords.longitude            + '\n' +
		'Timestamp: ' + new Date(position.timestamp * 1000)  + '\n');
};

 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

简单的范例：

// 获取位置信息成功后调用的回调函数
var onSuccess = function(position) {
	alert('Latitude: '          + position.coords.latitude          + '\n' +
		'Longitude: '         + position.coords.longitude         + '\n' +
		'Altitude: '          + position.coords.altitude          + '\n' +
		'Accuracy: '          + position.coords.accuracy          + '\n' +
		'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
		'Heading: '           + position.coords.heading           + '\n' +
		'Speed: '             + position.coords.speed             + '\n' +
		'Timestamp: '         + new Date(position.timestamp)      + '\n');
};

// 获取位置信息出错后调用的回调函数
var onError = function() {
   alert('onError!');
};

navigator.geolocation.getCurrentPosition(onSuccess, onError);

 完整的范例：

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

 

 

 

 

分享到：
| PhoneGap API帮助文档翻译—File（文件）
评论
发表评论

文章已被作者锁定，不允许评论。

相关推荐

    PhoneGap,API帮助文档.zip

    9. **定位（Geolocation）**：定位API利用GPS、Wi-Fi或蜂窝网络来获取设备的地理位置信息，这对于地图应用和基于位置的服务至关重要。 10. **媒体（Media）**：媒体API支持音频播放、录音和回放功能，使得开发者...

    PhoneGap中文API帮助文档

    网上的phonegap中文帮助文档尚少，翻译也不太好，在此收集了一些翻译优秀的文章，并制作成chm的帮助文档，以帮助各位学习,此文档包含了phonegap的主要使用功能，并提供了完整示例

    PhoneGap,API帮助文档翻译整理9-Geolocation_(定位)

    `geolocation.getCurrentPosition` 是 Geolocation API 的关键方法，用于获取设备的当前位置。这个方法是异步的，意味着它不会立即返回结果，而是通过传递给 `geolocationSuccess` 回调函数的 `Position` 对象来传递...

    PhoneGap,API帮助文档翻译整理4-Compass(指南针)

    标题：PhoneGap,API帮助文档翻译整理4-Compass(指南针) 描述：本文档将深入探讨PhoneGap中Compass API的功能与应用，包括如何获取设备的指南针方向、监听指南针变化以及如何处理相关事件。 ### 一、Compass API...

    PhoneGap,API帮助文档翻译整理6-Contacts(通讯录)

    ### PhoneGap Contacts API详解 #### 一、简介 在移动应用开发中，有时我们需要访问用户的通讯录以便于实现社交功能或其他交互式应用需求。PhoneGap（现称Cordova）为开发者提供了一套丰富的API，使得跨平台应用...

    PhoneGap,API帮助文档翻译整理10-Media_(媒体)

    在本篇文档中，我们关注的是 PhoneGap 的 Media API，它提供了对移动设备媒体（如音频）的访问和控制能力。 Media API 提供了对音频文件的操作，包括播放、暂停、停止以及获取当前播放位置等功能。以下是对 Media ...

    PhoneGap,API帮助文档翻译整理7-Events_(消息)

    PhoneGap API 提供了一系列的事件，这些事件可以帮助开发者响应移动设备上的特定操作，从而实现更丰富的用户体验。本文将详细介绍 PhoneGap 中的事件类型及其使用方法。 1. **backbutton**：当用户在 Android 设备...

    PhoneGap,API帮助文档翻译整理5-Device(设备)

    知识点：PhoneGap设备API及其应用 一、PhoneGap设备API概览 PhoneGap是一个开源框架，允许开发者使用HTML、CSS和JavaScript开发跨平台移动应用程序。设备API是PhoneGap提供的核心功能之一，它允许开发者访问设备的...

    Phonegap API （中文版）

    最新的Phonegap api 中文翻译版。让你快速入门。

    PhoneGap,API帮助文档翻译整理2-Camera(相机)

    知识点：PhoneGap的Camera API详解 一、PhoneGap与Camera API简介 PhoneGap是一个开源框架，允许开发者使用HTML，CSS和JavaScript开发跨平台移动应用程序。它通过提供一系列API来访问设备的功能，如摄像头、GPS、...

    PhoneGap,API帮助文档翻译整理8-File_(文件)

    在本篇文档中，我们将重点关注与“文件”相关的 API，包括 `File`、`DirectoryEntry`、`FileReader` 等。 **File API** 是一组用于读取、写入和管理设备文件系统层级结构的接口。这些接口遵循 W3C 的《文件系统 API...

    PhoneGap,API帮助文档翻译整理6-Contacts(通讯录).pdf

    在本文中，我们将围绕PhoneGap框架的API文档进行探讨，特别是在处理移动设备上的通讯录（Contacts）数据时所使用的一系列方法。根据提供的文件信息，我们将会详细解释如何使用PhoneGap API来创建和查找通讯录中的...

    PhoneGap,API帮助文档翻译整理3-Capture(捕捉)

    ### PhoneGap Capture API详解 #### 一、简介 **PhoneGap**是一款开源框架，允许开发者使用HTML、CSS和JavaScript等Web技术开发跨平台移动应用程序。本文档主要介绍**PhoneGap**中的**Capture API**，该API提供了...

    PhoneGap的API组件及使用方法

    4. **地理定位** (Geolocation): `navigator.geolocation`接口提供了获取设备当前位置的能力，支持GPS、Wi-Fi和移动网络定位。 5. **通知** (Notification): 提供了弹出框、振动和声音提示等功能，增强用户交互体验...

    phonegap api中文手册

    本手册为PhoneGap API的中文版指南，旨在为开发者提供全面、详细的API使用指导，帮助其利用PhoneGap框架开发跨平台移动应用。PhoneGap是一款基于HTML、CSS和JavaScript的技术栈，允许开发者构建适用于多个移动操作...

    PhoneGap,API帮助文档翻译整理1-Accelerometer(加速度计)

    ### PhoneGap中的Accelerometer（加速度计）API详解 #### 一、简介 加速度计是一种常见的硬件传感器，被广泛应用于智能手机和平板电脑等移动设备上。它主要用于测量设备在三维空间中的线性加速度，通常包括三个轴...

    PhoneGap API之事件处理.

    5. **地理定位事件**：通过`Geolocation`接口，开发者可以监听位置更新事件。例如，`watchPosition`方法会周期性地返回当前位置，并在位置改变时触发`position`事件。 6. **媒体事件**：使用`Media`对象处理音频...

    Phonegap API中文版

    例如，`Camera` API用于拍照或从相册选择图片，`Geolocation` API获取设备位置信息，`Accelerometer` API监测设备的运动状态。 4. **插件系统**：PhoneGap的核心API可能无法满足所有需求，但其强大的插件系统允许...

    Phonegap_API_中文版

    3. **位置服务**：PhoneGap的Geolocation API让你能够获取设备的地理位置信息，包括经度、纬度、高度、速度等。通过监听`watchPosition`或调用`getCurrentPosition`，你可以实时追踪或获取一次性的位置数据。 4. **...

Magicbox
Global site tag (gtag.js) - Google Analytics