PhoneGap API介紹:Geolocation
作者:佚名 
  本文將介紹PhoneGap API——Geolocation:使得你的應(yīng)用程序可以訪問地理位置信息。geolocation對象提供了對設(shè)備GPS傳感器的訪問。Geolocation提供設(shè)備的位置信息,例如經(jīng)度和緯度。位置信息的常見來源包括全球定位系統(tǒng)(GPS),以及通過諸如IP地址、RFID、WiFi和藍牙的MAC地址、和GSM/CDMA手機ID的網(wǎng)絡(luò)信號所做的推斷。不能保證該API返回的是設(shè)備的真實位置信息。這個API是基于W3C Geo location API Specification實現(xiàn)的。有些設(shè)備已經(jīng)提供了對該規(guī)范的實現(xiàn),對于這些設(shè)備采用內(nèi)置實現(xiàn)而非使用PhoneGap的實現(xiàn)。對于沒有地理位置支持的設(shè)備
 方法:
參數(shù):
對象(只讀):
geolocation.getCurrentPosition
- 返回一個Position對象表示設(shè)備的當(dāng)前位置。
 
- navigator.geolocation.getCurrentPosition(geolocationSuccess,
 - [geolocationError],
 - [geolocationOptions]);
 
參數(shù):
- geolocationSuccess:獲取位置信息成功時調(diào)用的回調(diào)函數(shù),參數(shù)為當(dāng)前的位置信息。
 - geolocationError:(可選項)獲取位置信息出錯時調(diào)用的回調(diào)函數(shù)。
 - geolocationOptions:(可選項)地理位置選項。
 
說明:
- geolocation.getCurrentPositon是一個異步函數(shù)。它回傳一個包含設(shè)備當(dāng)前位置信息的Position對象給geolocationSuccess回調(diào)函數(shù)。如果發(fā)生錯誤,觸發(fā)geolocationError回調(diào)函數(shù)并傳遞一個PositionError對象。
 
支持的平臺:
- Android
 - BlackBerry (OS 4.6)
 - BlackBerry WebWorks (OS 5.0或更高版本)
 - iPhone
 
簡單的范例:
- // 獲取位置信息成功時調(diào)用的回調(diào)函數(shù)
 - // 該方法接受一個“Position”對象,包含當(dāng)前GPS坐標(biāo)信息
 - 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回調(diào)函數(shù)接收一個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);
 - }
 - // 獲取位置信息成功時調(diào)用的回調(diào)函數(shù)
 - 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回調(diào)函數(shù)接收一個PositionError對象
 - function onError(error) {
 - alert('code: ' + error.code + '\n' +
 - 'message: ' + error.message + '\n');
 - }
 - </script>
 - </head>
 - <body>
 - <p id="geolocation">Finding geolocation...</p>
 - </body>
 - </html>
 
- 監(jiān)視設(shè)備的當(dāng)前位置的變化。
 
- var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
 - [geolocationError],
 - [geolocationOptions]);
 
參數(shù):
- geolocationSuccess: 獲取位置信息成功時調(diào)用的回調(diào)函數(shù),參數(shù)為當(dāng)前位置信息。
 - geolocationError:(可選項)獲取位置信息出錯時調(diào)用的回調(diào)函數(shù)。
 - geolocationOptions:(可選項)地理位置選項。
 
返回:
- String:返回的watch id是位置監(jiān)視String:返回的watch id是位置監(jiān)視周期的引用??梢酝ㄟ^geolocation.clearWatch調(diào)用該watch ID以停止對位置變化的監(jiān)視。
 
說明:
- geolocation.watchPosition是一個異步函數(shù)。當(dāng)檢測到設(shè)備的位置發(fā)生改變時,它返回設(shè)備的當(dāng)前位置。當(dāng)設(shè)備檢索到一個新的位置,會觸發(fā)geolocationSuccess回調(diào)函數(shù)并傳遞一個Position對象作為參數(shù)。如果發(fā)生錯誤,會觸發(fā)geolocationError回調(diào)函數(shù)并傳遞一個PositionError對象。
 
支持的平臺:
- Android
 - BlackBerry (OS 4.6)
 - BlackBerry WebWorks (OS 5.0或更高版本)
 - iPhone
 
簡單的范例:
- // 獲取位置信息成功時調(diào)用的回調(diào)函數(shù)
 - // 該方法接受一個“Position”對象,包含當(dāng)前GPS坐標(biāo)信息
 - function onSuccess(position) {
 - var element = document.getElementById('geolocation');
 - element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br>' +
 - 'Longitude: ' + position.coords.longitude + '<br>' +
 - '<hr>' + element.innerHTML;
 - }
 - // onError回調(diào)函數(shù)接收一個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);
 - }
 - // 獲取位置信息成功時調(diào)用的回調(diào)函數(shù)
 - function onSuccess(position) {
 - var element = document.getElementById('geolocation');
 - element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
 - 'Longitude: ' + position.coords.longitude + '<br />' +
 - <hr />'' + element.innerHTML;
 - }
 - // onError回調(diào)函數(shù)接收一個PositionError對象
 - function onError(error) {
 - alert('code: ' + error.code + '\n' +
 - 'message: ' + error.message + '\n');
 - }
 - </script>
 - </head>
 - <body>
 - <p id="geolocation">Finding geolocation...</p>
 - </body>
 - </html>
 
- 停止watchID參數(shù)指向的設(shè)備位置變化監(jiān)視。
 
- navigator.geolocation.clearWatch(watchID);
 
參數(shù):
- watchID:要清除的watchPosition周期的id。(字符串類型)
 
說明:
- geolocation.clearWatch函數(shù)通過清除watchID指向的geolocation.watchPosition來停止對設(shè)備位置變化的監(jiān)視。
 
支持的平臺:
- 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);
 - }
 - // 獲取位置信息成功時調(diào)用的回調(diào)函數(shù)
 - function onSuccess(position) {
 - var element = document.getElementById('geolocation');
 - element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
 - 'Longitude: ' + position.coords.longitude + '<br />' +
 - '<hr />' + element.innerHTML;
 - }
 - // 清除前述已經(jīng)開始的監(jiān)視
 - function clearWatch() {
 - if (watchID != null) {
 - navigator.geolocation.clearWatch(watchID);
 - watchID = null;
 - }
 - }
 - // onError回調(diào)函數(shù)接收一個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>
 
- 當(dāng)?shù)玫揭粋€有效地理位置信息時,此用戶回調(diào)函數(shù)被調(diào)當(dāng)獲得一個地理位置信息時,此用戶回調(diào)函數(shù)被調(diào)用。
 
- function(position) {
 - // 進行處理
 - }
 
參數(shù):
- position:設(shè)備返回的地理位置信息。(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');
 - }
 
- 當(dāng)geolocation函數(shù)發(fā)生錯誤時,此用戶回調(diào)函數(shù)被調(diào)用。
 
- function(error) {
 - // 處理錯誤
 - }
 
參數(shù):
- error:設(shè)備返回的錯誤信息。(PositionError類型)
 
- 用戶定制地理位置檢索的可選參數(shù)。
 
- { maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
 
選項:
- frequency:以毫秒為單位的檢索位置周期。這個選項并非W3C規(guī)范的一部分,未來會被刪除并用maximumAge來替代該選項。(數(shù)字類型)(默認值:10000)
 - enableHighAccuracy:提供一個表明應(yīng)用程序希望獲得最佳可能結(jié)果的提示。(布爾類型)
 - timeout:允許的以毫秒為單位的最大時間間隔,該時間間隔是從geolocation.getCurrentPosition或geolocation.watchPosition的調(diào)用到相應(yīng)的geolocationSuccess回調(diào)函數(shù)被調(diào)用。(數(shù)字類型)
 - maximumAge:應(yīng)用程序?qū)⒔邮芤粋€緩存的位置信息,當(dāng)該緩存的位置信息的年齡不大于此參數(shù)設(shè)定值,單位是毫秒。(數(shù)字類型)
 
Android的特異情況:
- 除非enableHighAccuracy選項被設(shè)定為true,否則Android 2.X模擬器不會返回一個地理位置結(jié)果。
 
- { enableHighAccuracy: true }
 
- 包含由geolocation API創(chuàng)建的Position坐標(biāo)信息。
 
屬性:
- coords:一系列地理坐標(biāo)。(Coordinates類型)
 - timestamp:以毫秒為單位的coords的創(chuàng)建時間戳。(DOMTimeStamp類型)
 
說明:
- Position對象是由PhoneGap創(chuàng)建和填充的,并通過一個回調(diào)函數(shù)返回用戶。
 
支持的平臺:
- Android
 - BlackBerry (OS 4.6)
 - BlackBerry WebWorks (OS 5.0或更高版本)
 - iPhone
 
簡單的范例:
- // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
 - 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回調(diào)函數(shù)接收一個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);
 - }
 - // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
 - 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回調(diào)函數(shù)接收一個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:單位為秒而非毫秒。
 
一種變通方法是手動將時間戳轉(zhuǎn)換為毫秒(*1000):
- var onSuccess = function(position) {
 - alert('Latitude: ' + position.coords.latitude + '\n' +
 - 'Longitude: ' + position.coords.longitude + '\n' +
 - 'Timestamp: ' + new Date(position.timestamp * 1000) + '\n');
 - };
 
- 當(dāng)發(fā)生錯誤時,一個PositionError對象會傳遞給geolocationError回調(diào)函數(shù)。
 
屬性:
- code:一個在下面常量列表中定義的錯誤代碼。
 - message:說明錯誤細節(jié)的錯誤信息。
 
常量:
- PositionError.PERMISSIONPositionError.PERMISSION_DENIED:權(quán)限被拒絕
 - PositionError.POSITION_UNAVAILABLE:位置不可用
 - PositionError.TIMEOUT:超時
 
說明:
- 當(dāng)使用Geolocation發(fā)生錯誤時,一個PositionError對象會作為geolocationError回調(diào)函數(shù)的參數(shù)傳遞給用戶。
 
- 一系列用來描述位置的地理坐標(biāo)信息的屬性。
 
屬性:
- latitude:以十進制表示的緯度。(數(shù)字類型)
 - longitude:以十進制表示的經(jīng)度。(數(shù)字類型)
 - altitude:位置相對于橢圓球面的高度,單位為米。(數(shù)字類型)
 - accuracy:以米為單位的緯度和經(jīng)度坐標(biāo)的精度水平。(數(shù)字類型)
 - altitudeAccuracy:以米為單位的高度坐標(biāo)的精度水平。(數(shù)字類型)
 - heading:運動的方向,通過相對正北做順時針旋轉(zhuǎn)的角度指定。(數(shù)字類型)
 - speed:以米/秒為單位的設(shè)備當(dāng)前地面速度。(數(shù)字類型)
 
說明:
- 作為Position對象的一部分,Coordinates對象是由PhoneGap創(chuàng)建和填充的。該Position對象會作為一個回調(diào)函數(shù)的參數(shù)返回用戶。
 
支持的平臺:
- Android
 - BlackBerry (OS 4.6)
 - BlackBerry WebWorks (OS 5.0或更高版本)
 - iPhone
 
簡單的范例:
- // 獲取位置信息成功后調(diào)用的回調(diào)函數(shù)
 - 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');
 - };
 - // 獲取位置信息出錯后調(diào)用的回調(diào)函數(shù)
 - 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">
 - // 設(shè)置一個當(dāng)PhoneGap加載完畢后觸發(fā)的事件
 - 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/>';
 - }
 - // 如果獲取位置信息出現(xiàn)問題,則顯示一個警告
 - function onError() {
 - alert('onError!');
 - }
 - </script>
 - </head>
 - <body>
 - <div id="myDiv"></div></body>
 - </html>
 
Android的特異情況:
- altitudeAccuracy: Android設(shè)備上不支持該屬性,返回值總是null。
 
責(zé)任編輯:佚名 
                    來源:
                    PhoneGap中國
 














 
 
 
 
 
 
 