更新记录

1.0.0（2026-10-29）

首期核心底座发布，基于 uni-app x 内置 <map> 组件声明式属性绑定，一套 .uvue + .uts 三端通用。

平台兼容性

uni-app x(3.8.10)

其他

jntc-tencentmaps-x 腾讯地图组件（uni-app x / UTS）

聚能天成腾讯地图组件，基于 uni-app x 原生 <map> + 腾讯地图 WebService API，提供地图渲染、覆盖物、 地理编码、路线规划、城市选择、POI 详情、地图选点、轨迹回放、打卡范围等能力。

• 全部代码为 UTS（选项式 API + 组合式主组件），支持 App / 小程序 / H5
• 业务弹窗统一 show() → Promise 契约，关闭/取消 resolve(null)
• 图标、文案、KEY 全部集中在 config.json，组件内无魔法字符串

目录

• 1. 快速开始
• 2. 主组件 jntc-tencentmaps-x
• 3. 业务弹窗组件
• 4. 工具函数 mapUtils
• 5. 配置 config.json
• 6. 图标与静态资源
• 7. 平台差异与注意事项
• 8. 常见问题

1. 快速开始

1.1 目录结构

uni_modules/jntc-tencentmaps-x/
├── config.json                          # KEY / 地图默认值 / 文案 / H5 接口域名 联系获取
├── config.uts                           # 配置读取 + 图标常量
├── mapUtils.uts                         # 工具函数（可独立 import）
├── mapApi.uts                           # @loaded 返回 API 的强类型桥接（JNTCMapBridge）
├── types.uts                            # 公共类型定义
├── changelog.md
├── readme.md
├── static/jntc-tencentmaps/             # 图标源文件（需复制到项目根 static/）
└── components/
    ├── jntc-tencentmaps-x/              # 主组件（地图容器）
    ├── jntc-tencentmaps-geolocation/    # 一键定位
    ├── jntc-tencentmaps-location/       # 位置展示
    ├── jntc-tencentmaps-picker/         # 地图选点
    ├── jntc-tencentmaps-route/          # 路线规划
    ├── jntc-tencentmaps-track/          # 轨迹回放
    ├── jntc-tencentmaps-checkin/        # 打卡范围
    ├── jntc-tencentmaps-city/           # 城市选择
    └── jntc-tencentmaps-poi/            # POI 详情

1.2 配置 KEY

编辑插件根目录 config.json，填入腾讯地图 Key（需开通 WebService API）：

{
    "mapKey": "你的腾讯地图KEY"
}

也可以在使用时通过 :map-key="xxx" 传入，优先级高于 config。

1.3 放置图标资源

把 5 个 png 放到项目根目录 static/jntc-tencentmaps/：

static/jntc-tencentmaps/
├── location.png          # 定位按钮图标
├── markerDefault.png     # 默认 marker
├── markerStart.png       # 路线起点
├── markerEnd.png         # 路线终点
└── center.png            # 选点中心图钉

必须是项目根目录的 /static/，不是插件包内的 static —— 插件包内路径不参与 base 重写，运行时拿不到。

1.4 权限与平台配置

小程序（manifest.json → mp-weixin）：

{
    "mp-weixin": {
        "permission": {
            "scope.userLocation": {
                "desc": "用于展示当前位置与周边信息"
            }
        },
        "requiredPrivateInfos": ["getLocation", "onLocationChange"]
    }
}

App（manifest.json → App 模块配置）：

1. 勾选 Maps(地图) → 腾讯地图，填 Key（iOS 还要在 app-ios.distribute.modules.uni-map.tencent.key 填同一个 Key）；
2. 勾选 Geolocation(定位)（推荐系统定位）；
3. Android 需声明定位权限（ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION）。

App 端的 <map> 走原生腾讯地图 SDK，Key 与 WebService Key 是同一个，但必须在 manifest 里配置，否则底图空白。

H5：地图底图由 mapKey 走腾讯 JS SDK，需要在腾讯位置服务后台给该 KEY 配置 Web 端域名白名单； 接口域名见 5. 配置 里的 h5ApiBase。

1.5 最小示例

<template>
    <view class="page">
        <jntc-tencentmaps-x
            ref="mapRef"
            class="map"
            :longitude="116.411794"
            :latitude="39.9068"
            :zoom="16"
            @loaded="onLoaded"
        />
    </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const mapRef = ref<any>(null)

function onLoaded(api: any): void {
    console.log('地图就绪', api)
}
</script>

<style>
.page { flex: 1; }
.map { flex: 1; width: 100%; height: 100%; }
</style>

2. 主组件 jntc-tencentmaps-x

2.1 Props

2.2 事件

推荐用法：通过 @loaded 拿到的 api 对象调用方法，比 $refs 更稳（UTS 选项式里 $refs 拿 <script setup> 子组件的方法存在时序问题，可能拿到 null）。

2.3 实例方法

视野控制

Marker

覆盖物

addMarker 传入的 marker 结构遵循 uni-app <map> 标准： { id, longitude, latitude, iconPath, width, height, callout, label, anchor } 未传 iconPath 时自动兜底 /static/jntc-tencentmaps/markerDefault.png，未传宽高默认 30×30。

2.4 使用示例

打点 + 自动缩放到所有点

function showPoints(api: any, list: Array<{ lon: number, lat: number, name: string }>): void {
    const markers = list.map((p: any, i: number) => {
        return {
            id: i + 1,
            longitude: p.lon,
            latitude: p.lat,
            iconPath: '/static/jntc-tencentmaps/markerDefault.png',
            width: 30,
            height: 30,
            callout: { content: p.name, color: '#FFFFFF', bgColor: '#2F6BFFFF', padding: 8, borderRadius: 6 }
        }
    })
    api.setMarkers(markers)
    api.fitBoundsWith(markers, { padding: 90 })
}

绘制路线 + 起终点图钉

function drawRoute(api: any, points: Array<{ longitude: number, latitude: number }>): void {
    api.setRoute(points, '#2F6BFFFF', 6)
    api.setLocationMarker(points[0].longitude, points[0].latitude, '起点', '/static/jntc-tencentmaps/markerStart.png')
    api.setLocationMarker(points[points.length - 1].longitude, points[points.length - 1].latitude, '终点', '/static/jntc-tencentmaps/markerEnd.png')
    api.fitBoundsWith(points, { padding: 60 })
}

反向遮罩（区域内高亮，区域外压暗）

api.setMask(ringPoints, 'rgba(0,0,0,0.45)')

3. 业务弹窗组件

所有弹窗组件遵循同一套契约：

// 1. 模板挂载（一次即可，组件内部自己控制显隐）
<jntc-tencentmaps-picker ref="pickerRef" />

// 2. 通过 ref 调用 show()，返回 Promise
const res = await pickerRef.value?.show(options)
if (res == null) {
    // 用户取消 / 关闭
} else {
    // res 是选中结果
}

通用规则

• show() 每次都会返回新的 Promise，重复调用时旧的 Promise 会 resolve(null)
• 用户取消、返回、关闭弹窗 → resolve(null)
• 参数非法（缺经纬度等）→ resolve(null)，不抛异常

3.1 一键定位 geolocation

<jntc-tencentmaps-geolocation ref="geolocationRef" />

geolocationRef.value?.show().then((res: any) => {
    if (res == null) return
    console.log('定位', res.lon, res.lat, res.address)
})

resolve：{ lon, lat, address }，取消为 null。

3.2 位置展示 location

<jntc-tencentmaps-location ref="locationRef" @navigate="onNavigate" @cancel="onCancel" />

// 单点
locationRef.value?.show({
    points: [{ id: 1, longitude: 116.3975, latitude: 39.9087, name: '天安门广场', address: '东城区东长安街' }],
    activeId: 1
})

// 多点（自动缩放到全部点）
locationRef.value?.show({
    points: [
        { id: 1, longitude: 116.4270, latitude: 39.9030, name: '北京站', address: '东城区毛家湾胡同甲13号' },
        { id: 2, longitude: 116.3975, latitude: 39.9087, name: '天安门广场', address: '东城区东长安街' }
    ],
    activeId: 1
})

options

事件：navigate（点击导航）、cancel（关闭） resolve：选中的点对象（含 name），关闭为 null。

3.3 地图选点 picker

<jntc-tencentmaps-picker ref="pickerRef" :center="[116.411794, 39.9068]" />

pickerRef.value?.show().then((res: any) => {
    if (res == null) return
    console.log('选点', res.longitude, res.latitude, res.address)
})

说明：组件内置搜索（支持中文 / 拼音 / 首字母缩写）、POI 列表、拖动地图取中心点。 中心图钉 + 右下角定位按钮已内置，无需额外配置。

resolve：{ longitude, latitude, address, ... }，取消为 null。

3.4 路线规划 route

<jntc-tencentmaps-route ref="routeRef" @navigate="onNavigate" @cancel="onCancel" />

routeRef.value?.show({
    to: { lon: 116.3975, lat: 39.9087, name: '天安门广场' },
    from: { lon: 116.4270, lat: 39.9030, name: '我的位置' }   // 不传则自动定位
})

options

resolve：路线结果（含 mode、distance、duration、polyline、steps），关闭为 null。 注意：距离单位米，耗时单位分钟。路线详情步骤列表来自 steps。

导航行为（点「开始导航」）：

• App：先探测已安装的地图 App（高德 / 腾讯 / 百度 / 苹果地图），装了多个弹系统 ActionSheet 让用户选，只有一个直接跳转，都没有回退 uni.openLocation 内置地图页；
• 小程序：uni.openLocation；
• H5：新开腾讯地图网页版路线规划。

3.5 轨迹回放 track

<jntc-tencentmaps-track ref="trackRef" />

trackRef.value?.show({
    points: [
        { lon: 116.3975, lat: 39.9087 },
        { lon: 116.4100, lat: 39.9100 },
        { lon: 116.4200, lat: 39.9120 }
    ],
    lineColor: '#2F6BFF',
    duration: 12000          // 总时长 ms，不传按点数自动算（8s ~ 30s）
})

options

resolve：关闭时为 null。

3.6 打卡范围 checkin

<jntc-tencentmaps-checkin ref="checkinRef" :radius="500" />

checkinRef.value?.show({
    lon: 116.411794,
    lat: 39.9068,
    radius: 500,
    name: '演示打卡点'
})

options：{ lon/center:[lon,lat], lat, radius, name } resolve：{ distance }（打卡时距目标点米数），取消为 null。

3.7 城市选择 city

<jntc-tencentmaps-city ref="cityRef" />

cityRef.value?.show().then((res: any) => {
    if (res == null) return
    console.log('选中城市', res.name, res.adcode, res.lon, res.lat)
})

说明：内置 A-Z 字母索引（点击有高亮反馈）、拼音 / 首字母搜索、全量城市列表缓存 7 天。 首次加载会请求腾讯 district 接口（约 3600 条原始数据，过滤后约 400 个真·市级）。

resolve：{ id, name, fullName, adcode, province, provinceAdcode, lon, lat, pinyin, pinyinInitials, firstLetter }，取消为 null。

3.8 POI 详情 poi

<jntc-tencentmaps-poi ref="poiRef" />

poiRef.value?.show({
    id: '7110202163774313209',     // 腾讯 POI id，有 id 才会拉详情接口
    name: '天安门广场',
    address: '东城区东长安街',
    lon: 116.3975,
    lat: 39.9087
})

options

展示内容：主图 banner、分类标签、地址、营业时间、可拨打电话、热门标签、店铺介绍、门店照片、 推荐菜品、用户评价、底部「电话 / 去这里」。 点图片会打开全屏预览（左右滑动切换、点击空白或 ✕ 关闭，previewImages 按点击索引定位）； 点电话会自动截取第一个号码并过滤非拨号字符（腾讯接口常返回 028-8888 8888 / 028-9999 9999 这种多号码）； 点「去这里」的导航行为同 3.4 route。

resolve：{ name, lon, lat, ... }（去这里的目标点），关闭为 null。 POI id 可从 searchPlace() 返回项的 hotPointID 获得。

4. 工具函数 mapUtils

mapUtils.uts 可脱离组件单独使用：

import {
    getLocation,
    getAddressByLocation,
    geocodeAddress,
    searchPlace,
    getRoutePlan,
    getPoiDetail,
    getPoiRichDetail,
    getAllCitiesWithCache,
    getDistance,
    wgs84ToGcj02,
    gcj02ToWgs84,
    coordTranslate,
    ipGeolocation
} from '@/uni_modules/jntc-tencentmaps-x/mapUtils.uts'

4.1 定位类

getLocation 返回 WGS84，腾讯地图用 GCJ02，打点前必须 wgs84ToGcj02 转换，否则偏移约 500 米。

4.2 坐标转换类

4.3 地理编码 / 搜索类

searchPlace 的 options：

boundary 是腾讯接口必填参数。内部按 adcode+坐标 → 仅 adcode → 仅坐标 → 全国 四级降级构造， 返回值已解析为 { name, address, lon, lat, distance, hotPointID, addressComponent }。

getAddressByLocation 返回：

{
    formatted_addresses: { recommend: string, rough: string },
    address: string,
    address_component: { province, city, district, street, street_number, adcode },
    location: { lon, lat },
    adcode: string,
    pois: Array<{ title, address, location: { lon, lat }, distance, id }>
}

4.4 路线类

• mode：driving / walking / bicycling / ebicycling
• 返回 { mode, distance(米), duration(分钟), polyline: [{lon,lat}], steps: [{instruction,distance,duration}] }
• 内部自动解压腾讯差分压缩坐标串，业务无需处理

4.5 工具类

const meters = getDistance(39.9068, 116.411794, 31.2304, 121.4737)  // 北京 → 上海

5. 配置 config.json

{
    "mapKey": "你的 KEY",
    "h5ApiBase": "",
    "mapConfig": {
        "defaultCenter": [116.411794, 39.9068],
        "defaultZoom": 16,
        "defaultSearchRadius": 1000,
        "defaultSearchCount": 10,
        "fitZoomOffset": -1
    },
    "texts": {
        "common": {},
        "route": {},
        "location": {},
        "picker": {},
        "track": {},
        "geolocation": {},
        "checkin": {},
        "city": {},
        "poi": {}
    }
}

代码中通过 config.uts 读取：

import { getMapKey, getTexts, getH5ApiBase, MAP_CONFIG, DEFAULT_MAP_KEY } from '@/uni_modules/jntc-tencentmaps-x/config.uts'

配置是编译期打进包里的：改完 config.json 需重新编译才生效。

6. 图标与静态资源

config.uts 导出 5 个图标常量，统一指向项目根目录：

import { ICON_LOCATION, ICON_MARKER_DEFAULT, ICON_MARKER_START, ICON_MARKER_END, ICON_CENTER }
// 值分别是：
// /static/jntc-tencentmaps/location.png
// /static/jntc-tencentmaps/markerDefault.png
// /static/jntc-tencentmaps/markerStart.png
// /static/jntc-tencentmaps/markerEnd.png
// /static/jntc-tencentmaps/center.png

为什么不用 base64：

所以 marker 类图标必须用本地文件路径，统一放项目根 static/ 最省心。

7. 平台差异与注意事项

7.1 坐标系

• uni.getLocation({ type: 'wgs84' }) → WGS84
• 腾讯地图底图 / marker / polyline → GCJ02
• 打点前请务必 wgs84ToGcj02(lon, lat) 转换

7.2 uni-app x 布局

• <view> 默认 flex-direction: column（与 H5 默认 row 不同）
• 横排容器必须显式写 flex-direction: row，否则元素会竖着堆叠
• 横向滚动 scroll-view 需要 enable-flex + 明确高度，且不建议套在纵向 scroll-view 内（手势会冲突）

7.3 弹窗调用方式

// 推荐：@loaded 拿 API 对象
function onLoaded(api: any): void {
    api.setMarkers([...])
}

// 不推荐：$refs 调 <script setup> 子组件方法（可能拿到 null）

弹窗组件内部统一用 @loaded 传入的 mapAPI 对象，不依赖 $refs。

@loaded 给到的 api 是 any，App 端不能直接调用其方法；插件内部用 mapApi.uts 的 JNTCMapBridge 包装（new JNTCMapBridge(api) 后用强类型方法调用）。业务代码若在 App 端也要调用，建议同样用这个桥接类：

import { JNTCMapBridge } from '@/uni_modules/jntc-tencentmaps-x/mapApi.uts'

let bridge: JNTCMapBridge | null = null
function onLoaded(api: any): void {
    bridge = new JNTCMapBridge(api)
    bridge.setCenter(116.3975, 39.9087)
}

7.4 UTS 限制（实测踩坑）

• 模板里不能直接使用模块导入的常量/函数，选项式组件需在 data() 中声明（如 iconLocation: ICON_LOCATION as string）， 模板只能调用组件自身成员方法
• 不支持索引签名 { [key: string]: any }，也不支持 Record<K,V> 的对象字面量 {}； 复杂结构请用具名 type，接外部 JSON 时用 UTSJSONObject + jget() 取值
• 模板/实例上引用的变量必须显式声明类型（不能是 any），否则 App 编译报「找不到名称」
• 条件编译平台标识：uni-app x 用 #ifdef APP / APP-ANDROID / APP-IOS； APP-PLUS 是 uni-app js 引擎版专用，在 uni-app x 里整块代码会被剔除（这是“写了却没生效”的常见原因）
• <text> 之外的元素设置 font-size / color / line-height / text-align / white-space / text-overflow 会告警且不生效， 文字必须放在 <text> 里
• 数组字面量是定长数组：const a: number[] = [0] 之后写 a[1] 会 IndexOutOfBoundsException，动态增长用 push()
• swiper 的 current 在 App 端首次渲染不生效（总是停在第一张），需要按索引精确显示时不要依赖它
• 数值格式化用 toFixed() 是安全的；toStr / toNum 统一走 mapUtils.uts，不要用 String()/Number() 全局构造

7.5 平台能力差异

调不通时组件会 reject / 返回 null，不会崩溃。

regionchange：App 端原生事件类型是 UniMapRegionChangeEvent（不是 JSON 对象），组件内部已统一归一化为 { type, causedBy, longitude, latitude, scale } 再抛出，业务按这个结构用即可；同时组件会把用户捏合后的真实 缩放级别回写到内部 scale，保证后续 fitBounds 能正确自适应。

8. 常见问题

Q1：地图不显示 marker

1. 检查 /static/jntc-tencentmaps/markerDefault.png 是否存在
2. 检查 marker 是否传了 iconPath（未传会自动兜底，但文件必须存在）
3. 若通过 $refs 调方法，改用 @loaded 的 api 对象

Q2：marker 显示位置偏移约 500 米

坐标是 WGS84 但地图是 GCJ02。用 wgs84ToGcj02 转换后再打点。

Q3：城市列表第一次打开很慢

首次会拉腾讯 district 全量数据（约 3600 条）再过滤成约 400 个城市，之后 7 天走本地缓存。 想强制刷新可 uni.removeStorageSync('jntc_tencentmaps_all_cities_v3')。

Q4：POI 详情只有名称和地址

show() 没传 id（或 poiId）时不会请求接口。id 可来自 searchPlace() 返回的 hotPointID。

Q5：搜索结果为空

检查 mapKey 是否开通了 WebService API 的「地点搜索」权限；searchPlace 的 boundary 已自动处理。

Q6：选点弹窗看不到中心图钉

确认主组件传了 :show-center-icon="true"（picker 组件已内置开启）。

Q7：点「导航」没反应 / 没弹出地图选择框

1. App 端先探测已安装的地图 App，多个才弹 ActionSheet；只有一个直接跳；一个都没装会回退 uni.openLocation。
2. 控制台会打印 [route] openMapNavigation ok / no map app installed, fallback to uni.openLocation， 以及失败时的 openLocation fail: <errMsg>，按日志定位。
3. iOS 上要能识别高德/腾讯/百度，云打包需在 LSApplicationQueriesSchemes 里声明 iosamap / qqmap / baidumap，否则 canOpenURL 恒为 false，只能走内置地图页。

Q8：H5 打开接口报跨域 / 404

接口域名由 config.json 的 h5ApiBase 决定（仅 H5 生效）：留空用内置默认 https://apis.map.ttssl.top， 在线环境填你的域名后需重新编译。若服务端未开 CORS，请让后端在响应上加 Access-Control-Allow-Origin（注意 Nginx 的 add_header 要加 always，否则 GET/POST 不生效）。

更新记录

见 changelog.md。