更新记录

1.0.3（2026-05-11）

修复 ios 导航

1.0.2（2026-05-10）

ios端导航调试完成

1.0.1（2026-04-17）

增加导航功能

平台兼容性

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. 再调用地图、定位、搜索、导航相关能力

腾讯 key 设置步骤

1. 先在 HBuilderX 中确定好打包使用的包名、签名信息
2. 用对应平台信息去腾讯位置服务后台申请 key
3. 如果需要搜索能力，记得开通 WebService API
4. 如果使用搜索能力，把 secretKey 一并传入 setTencentKey
5. 打自定义基座或正式包

基础初始化

建议在 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、起终点、导航模式等参数带到真正导航页

当前示例页面可以参考：

• 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