更新记录

1.0.7（2026-08-22）

更新说明文档

1.0.6（2026-08-19）

增加导航过程中‘全览状态下选路’的功能

1.0.5（2026-08-18）

支持超远距离导航，安卓端导航顶部增加安全区域，安卓端导航之前申请后台权限

平台兼容性

uni-app(4.29)

uni-app x(4.29)

其他

pow-tencentmap

插件选型

版本说明

• 老版本项目在接入、升级或新增功能前，请先确认当前工程使用的是哪一套原生 SDK，再选择对应的插件版本。
• 如果现有功能还不够，或者需要新增能力，可以在插件市场页面点击 进入交流群 联系沟通。
• 只要原生 SDK 已经提供对应能力，插件内都可以继续支持和扩展实现。

开发文档

UTS 语法
UTS API 插件
UTS 组件插件
Hello UTS

插件定位

pow-tencentmap 是一个 UTS 兼容模式组件插件，目标是让 uni-app 项目 在 Android / iOS 上直接使用腾讯地图、定位、搜索、导航能力。

和 pow-tmapx 的区别：

• pow-tmapx 主要面向 uni-app x
• pow-tencentmap 面向 uni-app 兼容模式
• 当前仅支持 Android、iOS

功能特性

• 腾讯地图组件
• 单次定位
• 持续定位
• 定位权限申请
• 关键词 POI 搜索
• 周边 POI 搜索
• 地理编码
• 逆地理编码
• 驾车导航
• 步行导航
• 骑行导航
• 货车导航
• 多路线预规划
• GPS 导航
• 模拟导航
• 距离计算
• 面积计算

平台支持

• 支持 uni-app
• 支持 Android
• 支持 iOS
• 不支持 H5
• 不支持各类小程序
• 当前不支持 HarmonyOS

使用步骤

1. 导入插件到项目
2. 申请腾讯地图 key
3. Android / iOS 打自定义基座
4. 在应用启动阶段调用 setTencentKey
5. 再调用地图、定位、搜索、导航相关能力

说明：如果在 uni-app x 项目中打出的调试基座启动后闪退，请参考视频教程中的方法处理。

腾讯 key 设置步骤

1. 先在 HBuilderX 中确定好打包使用的包名、签名信息
2. 用对应平台信息去腾讯位置服务后台申请 key
3. 如果需要搜索能力，记得开通 WebService API
4. 如果使用搜索能力，把 secretKey 一并传入 setTencentKey
5. 在打包自定义基座之前，打开插件内安卓端的 uni_modules/pow-tencentmap/utssdk/app-android/AndroidManifest.xml，将其中 TencentMapSDK 的 android:value 设置为你申请的 Android key
6. 打自定义基座或正式包

基础初始化

建议在 App.vue 的 onLaunch 中调用：

import { setTencentKey } from '@/uni_modules/pow-tencentmap'

export default {
    onLaunch() {
        setTencentKey(
            '你的iOSKey',
            '你的AndroidKey',
            '', // harmony 当前不用，传空字符串即可
            '你的SecretKey'
        )
    }
}

主要 API

import {
    setTencentKey,
    checkAndRequestLocationPermission,
    getTencentLocation,
    startTencentLocation,
    stopTencentLocation,
    planTencentNaviRoutes,
    tencentLineDistance,
    tencentCalculateArea,
    searchTencentPoisWithKeywords,
    searchTencentPoisNearby,
    searchTencentGeocode,
    searchTencentRegeocode
} from '@/uni_modules/pow-tencentmap'

定位示例

import {
    checkAndRequestLocationPermission,
    getTencentLocation,
    startTencentLocation,
    stopTencentLocation
} from '@/uni_modules/pow-tencentmap'

checkAndRequestLocationPermission(res => {
    console.log('定位权限结果', res)
})

getTencentLocation({
    needAddress: false,
    timeout: 10
}, res => {
    console.log('单次定位结果', res)
})

startTencentLocation({
    interval: 2000,
    needAddress: false,
    enableBg: true,
    bgTitle: '定位中'
}, res => {
    console.log('持续定位结果', res)
})

stopTencentLocation({}, res => {
    console.log('停止定位', res)
})

地图组件示例

<template>
    <pow-tencentmap
        ref="mapRef"
        class="map"
        @load="onMapLoad"
        @mapLoaded="onMapLoaded"
        @mapRendered="onMapRendered"
    ></pow-tencentmap>
</template>

<script>
export default {
    methods: {
        onMapLoad() {
            const mapRef = this.$refs.mapRef
            mapRef.setMapCenter('116.397455,39.909187', true)
            mapRef.setMapZoom(14, true)
            mapRef.addMarkers(JSON.stringify([{
                id: 'marker_1',
                lat: 39.909187,
                lng: 116.397455,
                title: '天安门'
            }]))
        },
        onMapLoaded(e) {
            console.log('地图完成加载', e)
        },
        onMapRendered(e) {
            console.log('地图首帧渲染', e)
        }
    }
}
</script>

<style>
.map {
    width: 750rpx;
    height: 600rpx;
}
</style>

搜索示例

import {
    searchTencentPoisWithKeywords,
    searchTencentPoisNearby,
    searchTencentGeocode,
    searchTencentRegeocode
} from '@/uni_modules/pow-tencentmap'

searchTencentPoisWithKeywords({
    keyword: '咖啡',
    city: '上海',
    pageIndex: 1,
    pageSize: 10
}, res => {
    console.log('关键词搜索结果', res)
})

searchTencentPoisNearby({
    keyword: '地铁站',
    lat: 31.2304,
    lng: 121.4737,
    radius: 1000,
    pageIndex: 1,
    pageSize: 10
}, res => {
    console.log('周边搜索结果', res)
})

searchTencentGeocode({
    address: '上海市浦东新区世纪大道100号'
}, res => {
    console.log('地理编码结果', res)
})

searchTencentRegeocode({
    lat: 31.2304,
    lng: 121.4737,
    getPoi: true
}, res => {
    console.log('逆地理编码结果', res)
})

路线预规划示例

planTencentNaviRoutes 用于先规划多条路线，再在页面上让用户选择。

import { planTencentNaviRoutes } from '@/uni_modules/pow-tencentmap'

planTencentNaviRoutes({
    startLat: 31.2304,
    startLng: 121.4737,
    startName: '起点',
    endLat: 31.2000,
    endLng: 121.5000,
    endName: '终点',
    naviType: 'drive'
}, res => {
    console.log('路线规划结果', res)
    // res.routes 内会返回候选路线
})

真正导航页说明

本插件的导航推荐分为两步：

1. 在参数页先调用 planTencentNaviRoutes 规划候选路线
2. 用户选中路线后，把 routeId、起终点、导航模式等参数带到真正导航页

Android/iOS 驾车/货车导航可以在参数中增加 enableOverviewRouteSelection: true，开启导航过程中进入全览后点击备选路线切换主路线；不传或传 false 时关闭。步行和骑行导航不支持该能力。

uni.navigateTo({
    url: `/pages/index/tmap-navi-view?params=${encodeURIComponent(JSON.stringify({
        naviType: 'drive',
        naviMode: 'gps',
        enableOverviewRouteSelection: true,
        // 其他起终点和 routeId 参数...
    }))}`
})

当前示例页面可以参考：

• pages/index/navi.nvue
• pages/index/tmap-navi-view.nvue

工具方法示例

import {
    tencentLineDistance,
    tencentCalculateArea
} from '@/uni_modules/pow-tencentmap'

const distance = tencentLineDistance(31.2304, 121.4737, 31.2200, 121.4900)
console.log('直线距离', distance)

const area = tencentCalculateArea(31.2400, 121.4600, 31.2200, 121.4900)
console.log('面积', area)

注意事项

1. 必须先调用 setTencentKey，否则地图、定位、搜索、导航都不会正常工作
2. Android 需要打自定义基座后再测试
3. 搜索相关接口依赖腾讯位置服务的 WebService 能力，缺少 secretKey 时可能失败
4. 导航页建议使用独立页面，不要在复杂滚动容器中频繁销毁重建
5. 真机调试优先，不建议只靠模拟器判断导航效果

参考工程

• 兼容模式思路可参考 pow-amapall
• 腾讯原生能力封装可参考 pow-tmapx
• 当前仓库示例页面位于 pages/index

更新记录

详见 changelog.md