PhoneGap API介绍：Geolocation-51CTO.COM

方法：

geolocation.getCurrentPosition
geolocation.watchPosition
geolocation.clearWatch

参数：

geolocationSuccess
geolocationError
geolocationOptions

对象(只读)：

Position
PositionError
Coordinates

返回一个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。