更新记录

1.1.1（2026-11-04）

修复安卓端内存泄露，支持蒸汽模式

1.1.0（2026-11-03）

路线规划完成后，往上游回调出三端的完整路线

1.0.10（2026-09-24）

更新 readme

平台兼容性

uni-app x(4.87)

pow-tmapx 腾讯地图 UTS 插件

插件选型

版本说明

• 老版本项目在接入、升级或新增功能前，请先确认当前工程使用的是哪一套原生 SDK，再选择对应的插件版本。

• 如果现有功能还不够，或者需要新增能力，可以在插件市场页面点击 进入交流群 联系沟通。

• 只要原生 SDK 已经提供对应能力，插件内都可以继续支持和扩展实现。

• 腾讯地图+定位+导航 UTS 插件，支持 Android、iOS、HarmonyOS 三端。

• 仅支持 uniappx 项目

功能特性

已支持

• 定位功能

  • 单次定位
  • 持续定位
  • 停止定位
  • 后台定位
  • 定位权限检查

• 地图功能

  • 地图显示
  • 地图类型切换（普通/卫星/夜间/3D沉浸）
  • 地图控制（中心点、缩放级别）
  • 路况显示
  • 指南针、比例尺控制
  • 手势控制（缩放/拖拽/旋转/倾斜）
  • 自身位置显示

• 覆盖物功能

  • Marker 标注（支持气泡callout）
  • 折线
  • 纹理折线
  • 圆形
  • 多边形

• 搜索功能

  • 关键词搜索 POI
  • 周边搜索 POI
  • 地理编码（地址转坐标）
  • 逆地理编码（坐标转地址）

• 导航功能

  • 驾车导航
  • 步行导航
  • 骑行导航
  • 货车导航
  • GPS实时导航
  • 模拟导航
  • TTS语音播报

• 工具功能

  • 距离计算
  • 面积计算
  • 坐标转换

使用方式

1. 在插件市场导入本插件到工程中（试用也可以）
2. 项目根目录manifest.json 的安卓配置targetSdkVersion填 33 或者以上
3. 【鸿蒙】把示例工程根目录中的harmony-configs复制到自己工程根目录
4. 【鸿蒙】鸿蒙不用打自定义基座，直接仿照示例工程中的 index.uvue 中的getHarmonyAppId()方法，在自己项目中调用getHarmonyAppId()获取鸿蒙的 专属appIdentifier
5. 申请腾讯地图的key
   1. 鸿蒙要把专属appIdentifier粘贴到腾讯地图key的申请页面
   2. 如果要用 poi 搜索功能，需要勾选 webservice 并且把 secretkey 复制下来，传到下一步骤中的 setTencentKey内
6. 【鸿蒙，安卓，iOS】在App.uvue中的onLaunch方法中，调用插件的setTencentKey方法
7. 【仅安卓】处理安卓打基座注意事项，在下一小节
8. 【安卓，iOS】打自定义基座（鸿蒙不需要打）
9. 【安卓，iOS】运行到自定义基座，【鸿蒙】直接运行
10. 【鸿蒙，安卓，iOS】参考示例工程的index.uvue中的申请定位权限,单次定位,持续定位方法
11. 【鸿蒙】鸿蒙平台如果想调用持续后台定位，需要参考示例工程的App.uvue，在自己工程的App.uvue的onShow调用tmapOnAppShow()，在onHide调用tmapOnAppHide()
12. 导航使用方式可以仿照powtmap/pages/index/tmap-navi-view.uvue创建一个导航页面，然后仿照powtmap/pages/index/navi.uvue来设置导航参数
13. 【HBuilderX的bug】【鸿蒙】hbx，试用插件鸿蒙端无法运行，不是插件问题，是 hbx 问题，要先这样绕过：把插件中的 项目根目录/uni_modules/pow-tmapx/components 目录剪切，粘贴到 uni_modules 之外，让 components 目录和 uni_modules 目录平级，变成 项目根目录/components，然后就能正常运行了

Android 云打包注意事项

1. 请在项目根目录的 manifest.json 中，为 app-android.distribute 增加下面的配置：

"app-android": {
  "distribute": {
    "targetSdkVersion": "33",
    "packagingOptions": [
      "exclude 'google/protobuf/*.proto'"
    ]
  }
}

如果你的 manifest.json 里已经有 app-android.distribute 配置，只需要把 packagingOptions 合并进去即可。

2. 在项目/uni_modules/pow-tmapx/utssdk/app-android/AndroidManifest.xml内把TencentMapSDK的value 改成自己的腾讯后台申请的key值

3. 定位功能

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

// 检查定位权限
checkAndRequestLocationPermission(res => {
    console.log('权限状态:', res)
})

// 单次定位
getTencentLocation({
    needAddress: true
}, res => {
    console.log('定位结果:', res)
    console.log('定位POI列表:', res.poiList)
})

// 持续定位
startTencentLocation({
    interval: 2000,
    needAddress: true,
}, res => {
    console.log('持续定位:', res)
    console.log('持续定位POI列表:', res.poiList)
})

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

4. 地图组件

<template>
    <pow-tmapx
        ref="mapRef"
        class="map"
        :center="'116.398111,39.91054'"
        :zoomLevel="12"
        @load="onMapLoad"
        @mapLoaded="onMapLoaded"
        @markerClick="onMarkerClick"
    ></pow-tmapx>
</template>

<script>
export default {
    methods: {
        onMapLoad() {
            console.log('地图加载完成')
        },
        onMapLoaded(e) {
            console.log('地图已加载')
        },
        onMarkerClick(e) {
            console.log('Marker点击:', e.detail)
        },

        // 调用地图方法
        addMarker() {
            const mapRef = this.$refs['mapRef']
            mapRef.$callMethod('addMarkers', JSON.stringify([{
                id: 'marker1',
                lat: 39.909187,
                lng: 116.397455,
                title: '天安门'
            }]))
        },

        removeSomeMarkers() {
            const mapRef = this.$refs['mapRef']
            mapRef.$callMethod('removeSomeMarkers', JSON.stringify({
                ids: ['marker1', 'marker2']
            }))
        }
    }
}
</script>

5. 工具函数

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

// 计算距离
const distance = tencentLineDistance(lat1, lng1, lat2, lng2)

// 计算面积
const area = tencentCalculateArea(lat1, lng1, lat2, lng2)

6. 搜索功能

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

// 关键词搜索 POI
// 代码示例待添加

// 周边搜索 POI
// 代码示例待添加

// 地理编码
// 代码示例待添加

// 逆地理编码
// 代码示例待添加

搜索参数说明

关键词搜索参数

周边搜索参数

地理编码参数

逆地理编码参数

7. 导航功能

导航功能分为两个页面：导航配置页面和导航视图页面。

导航配置页面 (navi.uvue)

用于设置导航参数，选择导航类型和模式。

代码示例待添加

导航视图页面 (tmap-navi-view.uvue)

实际显示导航界面的页面，使用 pow-tmap-navi 组件。

代码示例待添加

导航组件方法说明

路线规划参数说明

{
  "startLat": 39.909187,    // 起点纬度
  "startLng": 116.397455,   // 起点经度
  "endLat": 39.917839,      // 终点纬度
  "endLng": 116.397029,     // 终点经度
  "naviType": "drive",      // 导航类型: drive/walk/ride/truck
  "naviMode": "gps",        // 导航模式: gps/simulate
  "enableTTS": true,        // 是否开启语音播报
  "simulateSpeed": 60,      // 模拟导航速度（米/秒），仅模拟模式有效
  // 货车专用参数(仅 naviType 为 truck 时有效)
  "truckOptions": {
    "height": 4.2,          // 车高(米)
    "width": 2.5,           // 车宽(米)
    "length": 12,           // 车长(米)
    "weight": 20,           // 车重(吨)
    "axisCount": 4          // 轴数
  }
}

导航回调事件说明

路线坐标说明

calculateRoute 和 recalculateRoute 成功时会返回路线几何数据，可用于把导航路线实时同步给其他端：

• points: 字符串数组，每个元素格式为 "lng,lat"（经度在前，纬度在后）
• coords: 对象数组，每个元素格式为 { lat: number, lon: number }
• paths: 全部规划路线，每项包含 routeId、pathId、tag、allLength、allTime、trafficLightCount、tollCost、distance、points、coords
• path: 当前选中的第一条路线，与 paths[0] 相同
• routeId / selectedRouteId: 当前选中的路线 ID

地图组件方法

地图组件事件