HTML5 Geolocation 地理定位API - 完整指南

简介

Geolocation API 是 HTML5 引入的强大功能，它允许网页请求访问用户的地理位置信息。通过该 API，开发者可以获取用户的经度、纬度、海拔高度、移动速度等详细信息。该 API 基于 GPS、Wi-Fi、基站等多种定位方式，现代浏览器通常能够提供相当准确的定位结果。

注意事项

使用地理定位需要用户明确授权
必须在 HTTPS（生产环境）或 localhost（开发环境）下使用
部分浏览器可能不支持该 API，需要进行兼容性检查
定位精度受设备硬件和网络环境影响

基本 API 使用

使用navigator.geolocation对象获取当前位置信息。最常用的方法是getCurrentPosition()，它接受一个成功回调函数作为参数。

获取当前位置

if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(
        function(position) {
            var lat = position.coords.latitude;
            var lon = position.coords.longitude;
            console.log("纬度: " + lat + ", 经度: " + lon);
        },
        function(error) {
            console.log("获取位置失败: " + error.message);
        }
    );
} else {
    console.log("浏览器不支持地理定位");
}

getCurrentPosition()方法可以接受三个参数：

successCallback - 成功获取位置时的回调函数
errorCallback - 获取位置失败时的回调函数（可选）
options - 配置选项对象（可选）

位置信息详解

成功回调函数返回的 Position 对象包含coords属性，其中包含了丰富的位置信息：

coords 属性说明

navigator.geolocation.getCurrentPosition(function(position) {
    // 基本坐标
    console.log(position.coords.latitude);   // 纬度
    console.log(position.coords.longitude);  // 经度
    console.log(position.coords.accuracy);   // 精度（米）
    
    // 高级信息
    console.log(position.coords.altitude);          // 海拔（米）
    console.log(position.coords.altitudeAccuracy);  // 海拔精度
    console.log(position.coords.heading);           // 方向（0-360度）
    console.log(position.coords.speed);              // 速度（米/秒）
    
    // 时间戳
    console.log(position.timestamp);
});

提示

altitude、heading、speed 等属性可能返回 null，因为并非所有设备都支持这些功能。在使用前建议进行 null 检查。

配置选项

通过第三个参数可以配置定位的行为，包括精度、超时时间等：

配置选项

var options = {
    enableHighAccuracy: true,   // 高精度模式（可能更慢）
    timeout: 5000,                // 超时时间（毫秒）
    maximumAge: 300000           // 缓存有效时间（毫秒）
};

navigator.geolocation.getCurrentPosition(success, error, options);

enableHighAccuracy - 设为 true 会尝试使用 GPS 等高精度方式，但响应可能较慢
timeout - 设置请求超时时间，超时后会调用错误回调
maximumAge - 允许使用缓存的定位结果，0 表示不使用缓存

错误处理

定位可能因为多种原因失败，错误回调会接收到一个 PositionError 对象：

错误处理示例

function showError(error) {
    switch(error.code) {
        case error.PERMISSION_DENIED:
            alert("用户拒绝定位请求");
            break;
        case error.POSITION_UNAVAILABLE:
            alert("无法获取位置信息");
            break;
        case error.TIMEOUT:
            alert("定位请求超时");
            break;
        case error.UNKNOWN_ERROR:
            alert("发生未知错误");
            break;
    }
}

持续位置追踪

除了获取单次位置，Geolocation API 还支持持续追踪用户位置，适用于导航、运动记录等场景：

watchPosition 示例

// 开始追踪位置
var watchId = navigator.geolocation.watchPosition(
    function(position) {
        console.log("新位置: " + position.coords.latitude + ", " + position.coords.longitude);
    },
    function(error) {
        console.log("追踪错误: " + error.message);
    },
    { enableHighAccuracy: true }
);

// 停止追踪
// navigator.geolocation.clearWatch(watchId);

完整示例

下面是一个完整的地理位置获取示例：

💻 在线代码编辑器

👁️ 预览效果