更新记录

1.0.0（2026-07-09）

更新日志

[1.0.1] - 2026-07-09

Bug修复

平台兼容性

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. 搜索 azp-qqmap
3. 点击导入到项目

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

3. 配置manifest.json

Android配置

在 AndroidManifest.xml 中配置腾讯地图Key（插件已内置meta-data，替换Key即可）：

<application>
    <meta-data
        android:name="TencentMapSDK"
        android:value="你的腾讯地图Key" />
</application>

iOS配置

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

{
    "app-ios": {
        "distribute": {
            "modules": {
                "azp-qqmap": {
                    "QQMAP_KEY": "你的iOS腾讯地图Key"
                }
            }
        }
    }
}

同时需在 Info.plist 中添加以下权限描述（插件已内置默认值）：

• NSLocationWhenInUseUsageDescription
• NSLocationAlwaysAndWhenInUseUsageDescription
• NSLocationAlwaysUsageDescription

鸿蒙配置

鸿蒙端使用腾讯地图鸿蒙SDK，需配置对应的Key。

使用方法

基础用法

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

// 1. 初始化定位服务
const options: LocationOptions = {
    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-qqmap'

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

动态修改参数

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

// 修改定位间隔为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 > 0">速度: {{ location.speed }}m/s</text>
            <text v-if="location.direction > 0">方向: {{ 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,
    destroyLocation,
    LocationOptions,
    LocationResult
} from '@/uni_modules/azp-qqmap'

const location = ref<LocationResult>(new LocationResult())

let isStarted = false

// 初始化
onMounted(async () => {
    const options: LocationOptions = {
        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(() => {
    destroyLocation()
})
</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\<boolean>

初始化定位服务。必须在调用其他定位方法之前调用，内部会完成SDK初始化、隐私合规接口调用及监听器创建。

参数：

• options: 定位配置选项

返回：是否初始化成功

startLocation(callback: LocationCallback, errorCallback?: ErrorCallback): Promise\<boolean>

开始持续定位。会先停止已有的定位请求，再重新启动。

参数：

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

返回：是否启动成功

stopLocation(): Promise\<boolean>

停止定位，移除定位监听器。

返回：是否停止成功

getLocationOnce(callback: LocationCallback, errorCallback?: ErrorCallback): Promise\<boolean>

获取单次定位。会暂停持续定位，获取一次位置后自动恢复。超时15秒后自动恢复持续定位。

参数：

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

返回：是否请求成功

checkLocationPermission(): Promise\<boolean>

检查是否已获取定位权限（精确或模糊定位权限）。

返回：是否有定位权限

requestLocationPermission(): Promise\<boolean>

请求定位权限。会弹出系统权限弹窗，3秒后自动检查结果。

返回：是否获取到权限

setLocationOptions(options: LocationOptions): Promise\<boolean>

动态修改定位参数。会合并传入的选项到已有配置，然后重新构建定位请求并启动。

参数：

• options: 新的定位配置（仅传入需要修改的字段）

返回：是否设置成功

destroyLocation(): Promise\<boolean>

销毁定位服务，释放所有资源。调用后需重新调用 initLocation 才能再次使用。

返回：是否销毁成功

常见问题

1. Android打包失败

问题：提示找不到腾讯定位SDK

解决：

1. 确保已在AndroidManifest.xml中配置TencentMapSDK的meta-data Key
2. 制作自定义调试基座后再运行
3. 检查网络连接，SDK依赖 com.tencent.map.geolocation:TencentLocationSdk-openplatform:7.6.1.7 需要从Maven仓库下载

2. iOS后台定位不工作

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

解决：

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

3. 鸿蒙定位权限被拒绝

问题：无法获取位置信息

解决：

1. 在module.json5中声明LOCATION和LOCATION_IN_BACKGROUND权限
2. 引导用户在系统设置中授予权限
3. 检查是否使用了正确的定位场景

4. 定位精度不准确

问题：定位偏差较大

解决：

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

5. 后台定位耗电过快

问题：设备电量消耗过快

解决：

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

6. 定位成功但地址信息为空

问题：定位回调正常，但address等地址字段为空字符串

解决：

1. 确保初始化时设置 needAddress: true
2. 地址解析需要网络连接，检查网络是否正常
3. 纯GPS定位可能无法立即返回地址信息，等待网络定位结果
4. 腾讯地图Key需要正确配置，逆地理编码依赖Key

7. iOS云打包失败

问题：TencentLBS.framework依赖下载失败

解决：

1. 确认已将TencentLBS.framework放置到app-ios目录
2. 更换网络环境或使用代理
3. 使用Mac本地打包
4. 升级HBuilderX到最新版本

注意事项

⚠️ 重要提示：

1. 必须申请腾讯地图Key：使用前务必在腾讯位置服务开放平台申请对应的Key
2. 隐私合规：插件内部已调用 TencentLocationManager.setUserAgreePrivacy(true)，确保在调用任何定位功能前完成隐私合规
3. 仅支持真机调试：模拟器无法获取真实位置信息
4. 权限要求：必须在AndroidManifest.xml中正确配置权限和Key
5. 后台定位限制：部分系统会限制后台定位，需引导用户关闭电池优化
6. 自定义基座：UTS插件包含原生代码，必须制作自定义调试基座才能运行
7. 不可用于金融场景：本插件不适用于金融支付等高安全要求场景

平台依赖

技术支持

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

• 📧 邮箱：azp-qqmap@example.com
• 💬 QQ群：XXXXXXXXX
• 🐛 Issues：GitHub Issues

更新日志

详见 changelog.md

许可证

Copyright © 2026 azp-qqmap. All rights reserved.

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