PhoneGap API介紹：Geolocation

作者：佚名 2011-12-22 09:27:36

本文將介紹PhoneGap API——Geolocation:使得你的應(yīng)用程序可以訪問地理位置信息。geolocation對象提供了對設(shè)備GPS傳感器的訪問。Geolocation提供設(shè)備的位置信息，例如經(jīng)度和緯度。位置信息的常見來源包括全球定位系統(tǒng)（GPS），以及通過諸如IP地址、RFID、WiFi和藍(lán)牙的MAC地址、和GSM/CDMA手機(jī)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è)備

方法：

geolocation.getCurrentPosition
geolocation.watchPosition
geolocation.clearWatch

參數(shù)：

geolocationSuccess
geolocationError
geolocationOptions

對象(只讀)：

Position
PositionError
Coordinates

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>

geolocation.watchPosition

監(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>

geolocation.clearWatch

停止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>

geolocationSuccess

當(dāng)?shù)玫揭粋€有效地理位置信息時，此用戶回調(diào)函數(shù)被調(diào)當(dāng)獲得一個地理位置信息時，此用戶回調(diào)函數(shù)被調(diào)用。

function(position) { 
    // 進(jìn)行處理 
}

參數(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'); 
}

geolocationError

當(dāng)geolocation函數(shù)發(fā)生錯誤時，此用戶回調(diào)函數(shù)被調(diào)用。

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

參數(shù)：

error：設(shè)備返回的錯誤信息。（PositionError類型）

geolocationOptions

用戶定制地理位置檢索的可選參數(shù)。

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

選項：

frequency：以毫秒為單位的檢索位置周期。這個選項并非W3C規(guī)范的一部分，未來會被刪除并用maximumAge來替代該選項。（數(shù)字類型）（默認(rèn)值：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 }

Position

包含由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'); 
};

PositionError

當(dāng)發(fā)生錯誤時，一個PositionError對象會傳遞給geolocationError回調(diào)函數(shù)。

屬性：

code：一個在下面常量列表中定義的錯誤代碼。
message：說明錯誤細(xì)節(jié)的錯誤信息。

常量：

PositionError.PERMISSIONPositionError.PERMISSION_DENIED：權(quán)限被拒絕
PositionError.POSITION_UNAVAILABLE：位置不可用
PositionError.TIMEOUT：超時

說明：

當(dāng)使用Geolocation發(fā)生錯誤時，一個PositionError對象會作為geolocationError回調(diào)函數(shù)的參數(shù)傳遞給用戶。

Coordinates

一系列用來描述位置的地理坐標(biāo)信息的屬性。

屬性：

latitude：以十進(jìn)制表示的緯度。（數(shù)字類型）
longitude：以十進(jìn)制表示的經(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中國

PhoneGap API Geolocation