更新记录

1.0.0（2025-12-23）

• 初始版本
• 支持 Android、iOS、HarmonyOS 三端
• 定位功能：单次定位、持续定位
• 地图功能：地图显示、控制、手势、Marker、折线、圆形、多边形
• 搜索功能：POI 搜索、地理编码、逆地理编码
• 导航功能：驾车导航、步行导航、骑行导航

平台兼容性

uni-app x(4.87)

pow-tmapx 腾讯地图 UTS 插件

• 腾讯地图+定位+导航 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. 【安卓，iOS】打自定义基座（鸿蒙不需要打）
8. 【安卓，iOS】运行到自定义基座，【鸿蒙】直接运行
9. 【鸿蒙，安卓，iOS】参考示例工程的index.uvue中的申请定位权限,单次定位,持续定位方法
10. 【鸿蒙】鸿蒙平台如果想调用持续后台定位，需要参考示例工程的App.uvue，在自己工程的App.uvue的onShow调用tmapOnAppShow()，在onHide调用tmapOnAppHide()
11. 导航使用方式可以仿照powtmap/pages/index/tmap-navi-view.uvue创建一个导航页面，然后仿照powtmap/pages/index/navi.uvue来设置导航参数
12. 【HBuilderX的bug】【鸿蒙】4.87以及之前的hbx，试用插件鸿蒙端无法运行，不是插件问题，是 hbx 问题，要先这样绕过：把插件中的 项目根目录/uni_modules/pow-tmapx/components 目录剪切，粘贴到 uni_modules 之外，让 components 目录和 uni_modules 目录平级，变成 项目根目录/components，然后就能正常运行了

3. 定位功能

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

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

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

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

// 停止定位
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: '天安门'
            }]))
        }
    }
}
</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          // 轴数
  }
}

导航回调事件说明

地图组件方法

地图组件事件