Geolocation 地理位置

优质
小牛编辑
132浏览
2023-12-01

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);

完整的范例:

<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>
<p id="geolocation">Finding geolocation...</p>

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 });

完整的范例:

<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>
<p id="geolocation">Finding geolocation...</p>

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);

完整的范例:

<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>
<p id="geolocation">Finding geolocation...</p>
<button onclick="clearWatch();">Clear Watch</button>

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);

完整的范例:

<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>
<p id="geolocation">Finding geolocation...</p>

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);

完整的范例:

<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>
<div id="myDiv"></div>

Android的特异情况:

altitudeAccuracy: Android设备上不支持该属性,返回值总是null。