Cordova 定位功能在鸿蒙上的实现技术博客

Cordova 定位功能在鸿蒙上的实现技术博客

---

前言

在现代移动应用开发中，定位功能已经成为许多应用的核心特性。无论是地图导航、社交应用、还是生活服务类应用，都需要获取用户的地理位置信息。本文将详细介绍如何在 Cordova 应用中实现定位功能，包括一次性定位和持续定位两种场景。

技术背景

Cordova Geolocation API

Cordova 提供了基于 W3C Geolocation API 的定位插件，支持以下功能：

• 一次性定位 ：使用 getCurrentPosition() 获取当前位置
• 持续定位 ：使用 watchPosition() 监听位置变化
• 停止监听 ：使用 clearWatch() 停止位置监听

定位方式

1. GPS定位：精度高，但耗电量大，需要较长时间
2. 网络定位：基于WiFi和基站，速度快但精度较低
3. 混合定位：结合GPS和网络定位，平衡精度和速度

---

实现步骤

步骤 1: 安装定位插件

首先需要确保已安装 Cordova Geolocation 插件：

# 安装 Cordova Geolocation 插件
cordova plugin add cordova-plugin-geolocation

# 或使用 hcordova（HarmonyOS）
hcordova plugin add cordova-plugin-geolocation

步骤 2: 配置权限

Android 配置

在 platforms/android/app/src/main/AndroidManifest.xml 中添加权限：

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS 配置

在 config.xml 中添加权限说明：

<platform name="ios">
    <config-file target="*-Info.plist" parent="NSLocationWhenInUseUsageDescription">
        <string>应用需要获取您的位置信息以提供基于位置的服务</string>
    </config-file>
</platform>

HarmonyOS 配置

在 module.json5 中添加权限：

{
  "requestPermissions": [
    {
      "name": "ohos.permission.LOCATION",
      "reason": "$string:locationInfo",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "always"
      }
    },
    {
      "name": "ohos.permission.APPROXIMATELY_LOCATION",
      "reason": "$string:locationInfo",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "always"
      }
    }
  ]
}

步骤 3: 等待设备就绪

在使用定位 API 之前，必须等待 deviceready 事件：

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    // Cordova 已就绪，可以使用定位功能
    console.log('设备就绪，可以开始定位');
}

---

核心代码解析

一次性定位实现

基本用法

function getCurrentLocation() {
    navigator.geolocation.getCurrentPosition(
        // 成功回调
        function(position) {
            console.log('定位成功');
            console.log('纬度：', position.coords.latitude);
            console.log('经度：', position.coords.longitude);
        },
        // 失败回调
        function(error) {
            console.error('定位失败：', error);
        }
    );
}

完整实现（带配置选项）

function getCurrentLocation() {
    const button = document.getElementById('get-location-btn');
    const display = document.getElementById('location-display');
    
    // 更新按钮状态
    button.disabled = true;
    button.textContent = '定位中...';
    button.style.opacity = '0.7';
    
    // 显示加载提示
    display.innerHTML = '<p style="color: #666; text-align: center;">正在获取位置信息...</p>';

    // 调用获取当前位置方法
    navigator.geolocation.getCurrentPosition(
        // 成功回调：获取位置信息
        function (position) {
            console.log("定位成功，位置信息如下：");
            console.log("纬度：", position.coords.latitude);
            console.log("经度：", position.coords.longitude);
            console.log("定位精度：", position.coords.accuracy + " 米");
            
            // 在页面上显示位置信息
            displayLocationInfo(position);
            
            // 恢复按钮状态
            button.disabled = false;
            button.textContent = '重新获取位置';
            button.style.opacity = '1';
        },
        // 失败回调：处理定位错误
        function (error) {
            console.error("定位失败：");
            let errorMessage = "";
            
            switch (error.code) {
                case error.PERMISSION_DENIED:
                    console.error("错误码 1：用户拒绝授予定位权限");
                    errorMessage = "错误码 1：用户拒绝授予定位权限";
                    break;
                case error.POSITION_UNAVAILABLE:
                    console.error("错误码 2：位置信息不可用（如设备无GPS信号）");
                    errorMessage = "错误码 2：位置信息不可用（如设备无GPS信号）";
                    break;
                case error.TIMEOUT:
                    console.error("错误码 3：定位请求超时");
                    errorMessage = "错误码 3：定位请求超时";
                    break;
                default:
                    console.error("错误码 4：未知错误");
                    errorMessage = "错误码 4：未知错误";
                    break;
            }
            
            // 显示错误信息
            display.innerHTML = `
                <div style="padding: 15px; background-color: #fee; border-radius: 4px; border-left: 4px solid #f00;">
                    <p style="color: #c00; margin: 0; font-weight: bold;">定位失败</p>
                    <p style="color: #666; margin: 5px 0 0 0;">${errorMessage}</p>
                </div>
            `;
            
            // 恢复按钮状态
            button.disabled = false;
            button.textContent = '获取当前位置';
            button.style.opacity = '1';
        },
        // 配置选项：自定义定位参数
        {
            enableHighAccuracy: true,    // 是否启用高精度定位（GPS）
            timeout: 15000,               // 定位超时时间（毫秒）
            maximumAge: 0                 // 位置缓存有效期（毫秒）
        }
    );
}

位置信息显示

function displayLocationInfo(position) {
    const display = document.getElementById('location-display');
    
    // 处理时间戳：检查timestamp是否存在且有效
    let locationTime = '未知';
    if (position.timestamp && position.timestamp > 0) {
        // timestamp可能是毫秒数或秒数
        const timestamp = position.timestamp > 1000000000000 
            ? position.timestamp 
            : position.timestamp * 1000;
        locationTime = new Date(timestamp).toLocaleString('zh-CN', {
            year: 'numeric',
            month: '2-digit',
            day: '2-digit',
            hour: '2-digit',
            minute: '2-digit',
            second: '2-digit',
            hour12: false
        });
    } else {
        // 如果timestamp无效，使用当前时间
        locationTime = new Date().toLocaleString('zh-CN', {
            year: 'numeric',
            month: '2-digit',
            day: '2-digit',
            hour: '2-digit',
            minute: '2-digit',
            second: '2-digit',
            hour12: false
        });
    }
    
    // 处理海拔：检查是否为null/undefined，以及是否为有效数值
    let altitudeValue = '不支持';
    if (position.coords.altitude !== null 
        && position.coords.altitude !== undefined 
        && !isNaN(position.coords.altitude)) {
        altitudeValue = position.coords.altitude.toFixed(2) + ' 米';
    }
    
    // 处理海拔精度：检查是否为null/undefined，以及是否为有效数值
    let altitudeAccuracyValue = '不支持';
    if (position.coords.altitudeAccuracy !== null 
        && position.coords.altitudeAccuracy !== undefined 
        && !isNaN(position.coords.altitudeAccuracy)) {
        altitudeAccuracyValue = position.coords.altitudeAccuracy.toFixed(2) + ' 米';
    }
    
    const locationInfo = [
        { label: '纬度', value: position.coords.latitude.toFixed(6) + '°' },
        { label: '经度', value: position.coords.longitude.toFixed(6) + '°' },
        { label: '定位精度', value: position.coords.accuracy 
            ? (position.coords.accuracy.toFixed(2) + ' 米') 
            : '未知' },
        { label: '海拔', value: altitudeValue },
        { label: '海拔精度', value: altitudeAccuracyValue },
        { label: '定位时间', value: locationTime }
    ];

    let html = '';
    locationInfo.forEach(info => {
        html += `
            <div style="margin-bottom: 10px; padding: 8px; background-color: #f8f9fa; border-radius: 4px;">
                <strong style="color: #2980b9; margin-right: 8px;">${info.label}：</strong>
                <span style="color: #555;">${info.value}</span>
            </div>
        `;
    });
    
    // 添加地图链接（可选）
    html += `
        <div style="margin-top: 15px; text-align: center;">
            <a href="https://www.openstreetmap.org/?mlat=${position.coords.latitude}&mlon=${position.coords.longitude}&zoom=15" 
               target="_blank" 
               style="display: inline-block; padding: 8px 16px; background-color: #3498db; color: white; text-decoration: none; border-radius: 4px;">
                在地图上查看
            </a>
        </div>
    `;
    
    display.innerHTML = html;
}

配置选项详解

{
    // enableHighAccuracy: 是否启用高精度定位
    // true: 使用GPS定位，精度高但耗电量大，定位时间长
    // false: 使用网络定位，速度快但精度较低
    enableHighAccuracy: true,
    
    // timeout: 定位超时时间（毫秒）
    // 超过此时间未获取位置则触发失败回调
    timeout: 15000,
    
    // maximumAge: 位置缓存有效期（毫秒）
    // 0: 不使用缓存，每次都获取最新位置
    // 30000: 允许使用30秒内的缓存位置，提高响应速度
    maximumAge: 0
}

---

常见问题与解决方案

问题 1: 定位时间显示为 1970 年

原因 ：position.timestamp 可能为 0、无效值或格式不正确（秒数而非毫秒数）。

解决方案：

// 检查timestamp是否存在且有效
if (position.timestamp && position.timestamp > 0) {
    // 处理秒数和毫秒数两种情况
    const timestamp = position.timestamp > 1000000000000 
        ? position.timestamp      // 毫秒数
        : position.timestamp * 1000; // 秒数，转换为毫秒
    locationTime = new Date(timestamp).toLocaleString('zh-CN');
} else {
    // 如果timestamp无效，使用当前时间
    locationTime = new Date().toLocaleString('zh-CN');
}

问题 2: 海拔和海拔精度显示为 0

原因：设备可能不支持海拔信息，或者值为 0（海平面），需要区分"不支持"和"值为0"。

解决方案：

// 检查是否为null/undefined，以及是否为有效数值
let altitudeValue = '不支持';
if (position.coords.altitude !== null 
    && position.coords.altitude !== undefined 
    && !isNaN(position.coords.altitude)) {
    altitudeValue = position.coords.altitude.toFixed(2) + ' 米';
}

问题 3: 权限被拒绝

原因：用户拒绝了定位权限请求。

解决方案：

case error.PERMISSION_DENIED:
    // 提示用户需要权限
    alert('需要位置权限才能使用此功能，请在设置中开启定位权限');
    // 可以引导用户跳转到设置页面
    break;

问题 4: 定位超时

原因：GPS信号弱或网络问题导致定位时间过长。

解决方案：

// 增加超时时间
timeout: 30000,  // 30秒

// 或者降低精度要求
enableHighAccuracy: false,  // 使用网络定位，速度更快

问题 5: 在浏览器中测试时定位不可用

原因：Cordova Geolocation API 只能在原生应用中运行。

解决方案：

• 使用模拟器或真实设备测试
• 在浏览器中可以使用 HTML5 Geolocation API 进行 UI 测试
• 使用 cordova serve 在浏览器中测试界面，但定位功能需要在设备上测试

---

性能优化建议

1. 合理使用缓存

// 如果不需要实时位置，可以使用缓存提高响应速度
{
    maximumAge: 30000,  // 使用30秒内的缓存位置
    timeout: 10000
}

2. 根据场景选择定位精度

// 导航应用：需要高精度
{
    enableHighAccuracy: true,
    timeout: 20000
}

// 天气应用：网络定位即可
{
    enableHighAccuracy: false,
    timeout: 10000,
    maximumAge: 60000  // 使用1分钟内的缓存
}

3. 错误重试机制

let retryCount = 0;
const MAX_RETRIES = 3;

function getCurrentLocationWithRetry() {
    navigator.geolocation.getCurrentPosition(
        function(position) {
            retryCount = 0;  // 成功后重置计数
            displayLocationInfo(position);
        },
        function(error) {
            if (retryCount < MAX_RETRIES) {
                retryCount++;
                console.log(`定位失败，重试第 ${retryCount} 次...`);
                setTimeout(getCurrentLocationWithRetry, 2000);
            } else {
                console.error('定位失败，已达到最大重试次数');
                showError('定位失败，请检查网络和GPS设置');
            }
        },
        {
            enableHighAccuracy: true,
            timeout: 15000,
            maximumAge: 0
        }
    );
}

4. 节流处理

let lastLocationTime = 0;
const LOCATION_INTERVAL = 5000;  // 5秒内只定位一次

function getCurrentLocationThrottled() {
    const now = Date.now();
    if (now - lastLocationTime < LOCATION_INTERVAL) {
        console.log('定位请求过于频繁，已忽略');
        return;
    }
    lastLocationTime = now;
    getCurrentLocation();
}

5. 内存管理

// 如果使用 watchPosition，记得在不需要时清除
let watchId = null;

function startWatching() {
    watchId = navigator.geolocation.watchPosition(
        function(position) {
            updateLocation(position);
        },
        function(error) {
            console.error('定位错误：', error);
        }
    );
}

function stopWatching() {
    if (watchId !== null) {
        navigator.geolocation.clearWatch(watchId);
        watchId = null;
    }
}

---

持续定位实现

除了一次性定位，Cordova 还支持持续定位：

let watchId = null;

// 开始持续定位
function startWatchingPosition() {
    watchId = navigator.geolocation.watchPosition(
        function(position) {
            console.log('位置更新：', position.coords.latitude, position.coords.longitude);
            updateLocationOnMap(position);
        },
        function(error) {
            console.error('定位错误：', error);
        },
        {
            enableHighAccuracy: true,
            timeout: 15000,
            maximumAge: 5000  // 5秒内的缓存
        }
    );
}

// 停止定位
function stopWatchingPosition() {
    if (watchId !== null) {
        navigator.geolocation.clearWatch(watchId);
        watchId = null;
        console.log('已停止位置监听');
    }
}

---

完整示例代码

HTML 结构

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>定位功能示例</title>
    <style>
        .location-container {
            max-width: 600px;
            margin: 20px auto;
            padding: 20px;
            background-color: #fff;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0,0,0,0.1);
        }
        .location-btn {
            width: 100%;
            padding: 12px 20px;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
            border: none;
            border-radius: 6px;
            font-size: 16px;
            font-weight: bold;
            cursor: pointer;
            margin-bottom: 20px;
        }
        .location-btn:disabled {
            opacity: 0.7;
            cursor: not-allowed;
        }
        .location-info {
            font-size: 14px;
            line-height: 1.8;
        }
        .info-item {
            margin-bottom: 10px;
            padding: 8px;
            background-color: #f8f9fa;
            border-radius: 4px;
        }
        .info-label {
            color: #2980b9;
            font-weight: bold;
            margin-right: 8px;
        }
    </style>
</head>
<body>
    <div class="location-container">
        <h2>位置信息</h2>
        <button id="get-location-btn" class="location-btn" onclick="getCurrentLocation()">
            获取当前位置
        </button>
        <div id="location-display" class="location-info"></div>
    </div>
    
    <script src="cordova.js"></script>
    <script src="js/index.js"></script>
</body>
</html>

JavaScript 代码

// 等待设备就绪
document.addEventListener('deviceready', function() {
    console.log('设备就绪，定位功能可用');
}, false);

// 获取当前位置
function getCurrentLocation() {
    const button = document.getElementById('get-location-btn');
    const display = document.getElementById('location-display');
    
    button.disabled = true;
    button.textContent = '定位中...';
    display.innerHTML = '<p style="color: #666; text-align: center;">正在获取位置信息...</p>';

    navigator.geolocation.getCurrentPosition(
        function(position) {
            displayLocationInfo(position);
            button.disabled = false;
            button.textContent = '重新获取位置';
        },
        function(error) {
            handleLocationError(error);
            button.disabled = false;
            button.textContent = '获取当前位置';
        },
        {
            enableHighAccuracy: true,
            timeout: 15000,
            maximumAge: 0
        }
    );
}

// 显示位置信息
function displayLocationInfo(position) {
    // ... (使用前面提供的 displayLocationInfo 函数)
}

// 处理定位错误
function handleLocationError(error) {
    // ... (使用前面提供的错误处理代码)
}

---

总结

本文详细介绍了如何在 Cordova 应用中实现定位功能，包括：

1. 基础实现 ：使用 getCurrentPosition() 获取当前位置
2. 错误处理：完善的错误处理和用户提示
3. 数据格式化：正确处理时间戳、海拔等数据
4. 性能优化：缓存、节流、重试等优化策略
5. 持续定位 ：使用 watchPosition() 实现位置监听

关键要点

• ✅ 必须等待 deviceready 事件后才能使用定位 API
• ✅ 需要配置相应的平台权限
• ✅ 合理设置定位参数（精度、超时、缓存）
• ✅ 完善的错误处理和用户提示
• ✅ 注意时间戳格式转换（秒/毫秒）
• ✅ 正确处理海拔等可选数据

最佳实践

1. 权限处理：在请求定位前先检查权限状态
2. 用户体验：提供清晰的加载状态和错误提示
3. 性能优化：根据应用场景选择合适的定位精度和缓存策略
4. 错误恢复：实现重试机制，提高定位成功率
5. 资源管理：及时清理不需要的定位监听

希望本文能帮助开发者更好地理解和实现 Cordova 定位功能。如有问题，欢迎交流讨论！

---

作者 : 坚果派开发团队
最后更新 : 2025年
版本: 1.0