更新记录

1.0.0（2026-07-08）

更新日志

[1.0.0] - 2026-07-02

新增功能

• ✨ 支持Android、iOS、鸿蒙三平台持续定位
• 实现后台无限制定位功能
• ✨ 支持高精度/低功耗定位模式切换
• ✨ 支持单次定位和持续定位
• ✨ 支持获取详细地址信息（逆地理编码）
• 支持方向、速度、海拔等位置信息
• ✨ 支持自定义定位间隔和最小位移变化
• ✨ 提供完整的权限管理和检查机制

Android特性

• 使用高德地图SDK v9.5.0

平台兼容性

uni-app(4.0)

uni-app x(4.0)

其他

高德持续定位插件

支持Android、iOS、鸿蒙的高德持续定位插件，实现后台无限制定位功能

功能特性

✅ 三平台支持：完美适配Android、iOS、鸿蒙系统
✅ 后台无限制定位：应用切换到后台仍可持续获取位置信息
✅ 高精度定位：支持GPS+基站+WiFi融合定位
✅ 灵活配置：可自定义定位间隔、精度模式、最小位移等参数
✅ 地址解析：自动获取省市区街道等详细地址信息
✅ 权限管理：提供完整的权限检查和请求机制
✅ 易于集成：简洁的API接口，快速上手

适用场景

• 外卖配送：实时跟踪骑手位置
• 📦 物流运输：货物轨迹全程监控
• 🏃 运动健身：跑步、骑行路线记录
• 👨👩‍👧‍👦 家人守护：老人小孩位置共享
• 🚗 车辆管理：车队行驶轨迹监控
• 📍 资产管理：贵重物品位置追踪

安装说明

1. 获取高德地图Key

1. 访问 高德开放平台
2. 注册账号并创建应用
3. 添加Key，选择服务平台（Android/iOS）
4. 复制生成的Key备用

注意：Android和iOS需要分别申请Key

2. 导入插件

在HBuilderX中：

1. 右键项目 → 从插件市场导入插件
2. 搜索 amap-location
3. 点击导入到项目

或手动复制 uni_modules/amap-location 目录到项目的 uni_modules 文件夹

3. 配置manifest.json

Android配置

在 manifest.json → App原生插件配置 → android → modules 中添加：

{
    "app-android": {
        "distribute": {
            "modules": {
                "amap-location": {
                    "AMAP_KEY": "你的Android高德Key"
                }
            }
        }
    }
}

iOS配置

在 manifest.json → App原生插件配置 → ios → modules 中添加：

{
    "app-ios": {
        "distribute": {
            "modules": {
                "amap-location": {
                    "AMAP_KEY": "你的iOS高德Key"
                }
            }
        }
    }
}

鸿蒙配置

鸿蒙端Key为可选配置，如使用高德SDK则需配置。

使用方法

基础用法

import { 
    initLocation, 
    startLocation, 
    stopLocation,
    LocationOptions,
    LocationResult
} from '@/uni_modules/azp-amap'

// 1. 初始化定位服务
const options: LocationOptions = {
    key: '你的高德Key',           // 必需
    interval: 3000,                // 定位间隔3秒
    highAccuracy: true,            // 高精度模式
    needAddress: true,             // 需要地址信息
    backgroundLocation: true,      // 开启后台定位
    notificationTitle: '定位服务',  // Android通知标题
    notificationContent: '正在定位中' // Android通知内容
}

const success = await initLocation(options)
if (!success) {
    console.error('初始化失败')
    return
}

// 2. 请求定位权限
const hasPermission = await checkLocationPermission()
if (!hasPermission) {
    const granted = await requestLocationPermission()
    if (!granted) {
        console.error('未获取定位权限')
        return
    }
}

// 3. 开始持续定位
await startLocation(
    (result: LocationResult) => {
        console.log('定位成功:', result)
        console.log(`经度: ${result.longitude}, 纬度: ${result.latitude}`)
        console.log(`精度: ${result.accuracy}米`)

        if (result.address) {
            console.log(`地址: ${result.address}`)
        }
    },
    (error) => {
        console.error('定位失败:', error)
    }
)

// 4. 停止定位（页面卸载时调用）
onUnmounted(() => {
    stopLocation()
})

单次定位

import { getLocationOnce } from '@/uni_modules/azp-amap'

// 获取单次定位
await getLocationOnce(
    (result) => {
        console.log('单次定位结果:', result)
    },
    (error) => {
        console.error('单次定位失败:', error)
    }
)

动态修改参数

import { setLocationOptions } from '@/uni_modules/azp-amap'

// 修改定位间隔为5秒
await setLocationOptions({
    interval: 5000,
    highAccuracy: false  // 切换为低功耗模式
})

完整示例

<template>
    <view class="container">
        <view class="info">
            <text>纬度: {{ location.latitude }}</text>
            <text>经度: {{ location.longitude }}</text>
            <text>精度: {{ location.accuracy }}米</text>
            <text v-if="location.address">地址: {{ location.address }}</text>
            <text v-if="location.speed">速度: {{ location.speed }}m/s</text>
            <text v-if="location.direction">方向: {{ location.direction }}°</text>
        </view>

        <button @click="startLocate">开始定位</button>
        <button @click="stopLocate">停止定位</button>
        <button @click="getLocation">单次定位</button>
    </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { 
    initLocation, 
    startLocation, 
    stopLocation,
    getLocationOnce,
    checkLocationPermission,
    requestLocationPermission,
    LocationOptions,
    LocationResult
} from '@/uni_modules/amap-location'

const location = ref<LocationResult>({
    latitude: 0,
    longitude: 0,
    accuracy: 0,
    timestamp: 0
})

let isStarted = false

// 初始化
onMounted(async () => {
    const options: LocationOptions = {
        key: '你的高德Key',
        interval: 3000,
        highAccuracy: true,
        needAddress: true,
        backgroundLocation: true,
        notificationTitle: '位置跟踪',
        notificationContent: '正在记录您的位置信息'
    }

    await initLocation(options)
})

// 开始定位
async function startLocate() {
    if (isStarted) return

    // 检查权限
    const hasPermission = await checkLocationPermission()
    if (!hasPermission) {
        const granted = await requestLocationPermission()
        if (!granted) {
            uni.showToast({ title: '需要定位权限', icon: 'none' })
            return
        }
    }

    // 开始定位
    await startLocation(
        (result) => {
            location.value = result
            console.log('位置更新:', result)
        },
        (error) => {
            uni.showToast({ 
                title: `定位失败: ${error.message}`, 
                icon: 'none' 
            })
        }
    )

    isStarted = true
    uni.showToast({ title: '已开始定位', icon: 'success' })
}

// 停止定位
async function stopLocate() {
    if (!isStarted) return

    await stopLocation()
    isStarted = false
    uni.showToast({ title: '已停止定位', icon: 'success' })
}

// 单次定位
async function getLocation() {
    await getLocationOnce(
        (result) => {
            location.value = result
            uni.showToast({ title: '定位成功', icon: 'success' })
        },
        (error) => {
            uni.showToast({ 
                title: `定位失败: ${error.message}`, 
                icon: 'none' 
            })
        }
    )
}

// 页面卸载时清理
onUnmounted(() => {
    stopLocation()
})
</script>

<style>
.container {
    padding: 20px;
}

.info {
    margin-bottom: 20px;
    padding: 15px;
    background-color: #f5f5f5;
    border-radius: 8px;
}

.info text {
    display: block;
    margin-bottom: 8px;
    font-size: 14px;
}

button {
    margin-top: 10px;
}
</style>

API文档

LocationOptions

定位配置选项

LocationResult

定位结果

方法说明

initLocation(options: LocationOptions): Promise

初始化定位服务

参数：

• options: 定位配置选项

返回：是否初始化成功

startLocation(callback: LocationCallback, errorCallback?: ErrorCallback): Promise

开始持续定位

参数：

• callback: 定位结果回调函数
• errorCallback: 错误回调函数（可选）

返回：是否启动成功

stopLocation(): Promise

停止定位

返回：是否停止成功

getLocationOnce(callback: LocationCallback, errorCallback?: ErrorCallback): Promise

获取单次定位

参数：

• callback: 定位结果回调函数
• errorCallback: 错误回调函数（可选）

返回：是否请求成功

checkLocationPermission(): Promise

检查定位权限

返回：是否有定位权限

requestLocationPermission(): Promise

请求定位权限

返回：是否获取到权限

setLocationOptions(options: LocationOptions): Promise

设置定位参数

参数：

• options: 新的定位配置

返回：是否设置成功

destroyLocation(): Promise

销毁定位服务

返回：是否销毁成功

常见问题

1. Android打包失败

问题：提示找不到高德SDK

解决：

1. 确保已在manifest.json中配置AMAP_KEY
2. 制作自定义调试基座后再运行
3. 检查网络连接，重新下载依赖

2. iOS后台定位不工作

问题：应用切换到后台后定位停止

解决：

1. 在Xcode中启用Background Modes → Location updates
2. 确保请求了NSLocationAlwaysAndWhenInUseUsageDescription权限
3. 在Info.plist中添加正确的权限描述
4. 用户需在系统设置中允许"始终"访问位置

3. 鸿蒙定位权限被拒绝

问题：无法获取位置信息

解决：

1. 在module.json5中声明LOCATION和LOCATION_IN_BACKGROUND权限
2. 引导用户在系统设置中授予权限
3. 检查是否使用了正确的scenario（建议使用0x301导航场景）

4. 定位精度不准确

问题：定位偏差较大

解决：

1. 设置highAccuracy: true使用高精度模式
2. 确保在室外开阔环境测试
3. 等待GPS信号稳定（首次定位可能需要较长时间）
4. 检查是否开启了WiFi和移动数据辅助定位

5. 后台定位耗电过快

问题：设备电量消耗过快

解决：

1. 增大interval定位间隔（如设置为5000或10000）
2. 设置distanceFilter最小位移（如设置为10米）
3. 使用低功耗模式highAccuracy: false
4. 仅在必要时开启后台定位

6. iOS云打包失败

问题：CocoaPods依赖下载失败

解决：

1. 清除CocoaPods缓存：pod cache clean --all
2. 更换网络环境或使用代理
3. 使用Mac本地打包
4. 升级HBuilderX到最新版本

注意事项

⚠️ 重要提示：

1. 必须申请高德Key：使用前务必在高德开放平台申请对应的Key
2. 仅支持真机调试：模拟器无法获取真实位置信息
3. 权限要求：必须在manifest.json中正确配置权限和Key
4. 后台定位限制：部分系统会限制后台定位，需引导用户关闭电池优化
5. 隐私合规：使用定位功能需在隐私政策中明确说明
6. 不可用于金融场景：本插件不适用于金融支付等高安全要求场景

技术支持

如有问题，欢迎通过以下方式联系我们：

• 邮箱：amap-location@example.com
• 💬 Q***：XXXXXXXXX
• 🐛 Issues：GitHub Issues

更新日志

详见 changelog.md

许可证

Copyright © 2026 amap-location. All rights reserved.

商业使用请联系作者获取授权。