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對象表示設備的當前位置。

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

當得到一個有效地理位置信息時，此用戶回調函數被調當獲得一個地理位置信息時，此用戶回調函數被調用。

function(position) {
	// 進行處理 
}

參數：

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函數發生錯誤時，此用戶回調函數被調用。

function(error) {
	// 處理錯誤
}

參數：

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模擬器不會返回一個地理位置結果。

{ enableHighAccuracy: true }

Position

包含由geolocation API創建的Position座標信息。

屬性：

coords：一系列地理座標。（Coordinates類型）
timestamp：以毫秒爲單位的coords的創建時間戳。（DOMTimeStamp類型）

說明：

Position對象是由PhoneGap創建和填充的，並通過一個回調函數返回用戶。

支持的平臺：

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中國：www.phonegap.cn

中文討論組：groups.google.com/group/PhoneGapCN

PhoneGap API幫助文檔翻譯—Geolocation（地理位置）

PhoneGap API幫助文檔翻譯—Events（事件）

PhoneGap API幫助文檔翻譯—File（文件）

PhoneGap API幫助文檔翻譯—Geolocation（地理位置）

PhoneGap API幫助文檔翻譯—Compass(羅盤)

PhoneGap API幫助文檔翻譯—Connection（連接）

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結