更新记录

1.2.0（2026-10-19）

本插件包含六个组件：

1. jntc-tencentmaps — 基础地图组件

在页面中直接显示地图，支持交互、定位、拖拽等操作。提供标记点、多点标记、路线绘制等覆盖物绘制能力。

2. jntc-tencentmaps-picker — 地图选择器组件

带弹窗的地图选择器，内置自动定位、地址解析、POI 搜索、确认/取消等完整交互流程。点击列表地址先选中预览，底部"确定"按钮确认返回。

3. jntc-tencentmaps-location — 位置展示组件

全屏位置展示弹窗：地图 + 底部店名/地址卡片 + "去这里"导航 + 周边 POI。支持单点展示和多点标记（点击标记切换选中点）。

4. jntc-tencentmaps-route — 路线规划组件

全屏路线规划弹窗：驾车 / 步行 / 骑行三种方式一键切换，展示耗时里程、分步骤路线详情，支持调起第三方地图导航。

5. jntc-tencentmaps-geolocation — 前端定位组件

对标腾讯官方前端定位组件：三级定位链（设备 GPS → H5 前端定位工具 → IP 定位），支持实时定位监听（watchPosition），返回坐标 + 详细地址。

6. jntc-tencentmaps-track — 地图轨迹回放组件

轨迹折线展示 + 平滑回放：播放/暂停、倍速、进度拖动、跟随镜头，支持显示我的当前位置。

平台兼容性

uni-app(3.8.6)

版权与使用限制声明

本软件/插件著作权归聚能天成所有，仅限内部合作场景使用。 本组件底层依赖腾讯位置服务API，本项目已取得腾讯地图商业授权；未经腾讯书面许可，不得将该授权转借、转授第三方使用。 未经权利人书面授权，禁止擅自复制、修改、二次分发、转授权及任何商业使用。 如未经许可违规使用，我方将保留追究侵权者全部法律责任的权利。

Copyright (c) 2026 聚能天成. All rights reserved.

聚能天成腾讯地图组件 jntc-tencentmaps

基于腾讯地图 API 的 uni-app 地图组件，支持地图显示、定位、地址解析、位置选择、全国搜索等功能。

腾讯地图开放平台

安装插件

组件说明

本插件包含六个组件：

1. jntc-tencentmaps — 基础地图组件

在页面中直接显示地图，支持交互、定位、拖拽等操作。提供标记点、多点标记、路线绘制等覆盖物绘制能力。

2. jntc-tencentmaps-picker — 地图选择器组件

带弹窗的地图选择器，内置自动定位、地址解析、POI 搜索、确认/取消等完整交互流程。点击列表地址先选中预览，底部"确定"按钮确认返回。

3. jntc-tencentmaps-location — 位置展示组件

全屏位置展示弹窗：地图 + 底部店名/地址卡片 + "去这里"导航 + 周边 POI。支持单点展示和多点标记（点击标记切换选中点）。

4. jntc-tencentmaps-route — 路线规划组件

全屏路线规划弹窗：驾车 / 步行 / 骑行三种方式一键切换，展示耗时里程、分步骤路线详情，支持调起第三方地图导航。

5. jntc-tencentmaps-geolocation — 前端定位组件

对标腾讯官方前端定位组件：三级定位链（设备 GPS → H5 前端定位工具 → IP 定位），支持实时定位监听（watchPosition），返回坐标 + 详细地址。

6. jntc-tencentmaps-track — 地图轨迹回放组件

轨迹折线展示 + 平滑回放：播放/暂停、倍速、进度拖动、跟随镜头，支持显示我的当前位置。

平台支持

平台	支持方式
H5（移动端 / PC 端）	渲染腾讯地图
App（Android / iOS）	渲染，通过事件队列与逻辑层通信	APP选中打开系统定位
小程序（微信等）	自动切换至 uni.chooseLocation，无需额外适配

，show() 方法会通过条件编译自动调用 uni.chooseLocation 完成位置选择，返回结构与 App/H5 端保持一致（但不含 adcode、province 等字段）。

坐标系说明

腾讯地图使用 GCJ02（火星坐标系）。

uni.getLocation 返回的是 WGS84 坐标，组件内部已通过 coordTranslate 自动完成 WGS84 → GCJ02 转换，无需手动处理。

若您的业务数据使用其他坐标系（如百度 BD09），需在传入组件前自行转换。

使用示例

<template>
    <view class="page">
        <view class="header">
            <view class="title-row">
                <text class="title">我的位置</text>
                <text class="current-city" v-if="currentCity">当前：{{currentCity}}</text>
            </view>
            <button class="switch-city-btn" @tap="getCity">定位城市</button>
        </view>

        <view class="header" style="margin-top: 50rpx;">
            <view class="title-row">
                <text class="title">选择定位</text>
            </view>
        </view>
        <view class="input-section">
            <view class="input-wrapper">
                <input
                    class="location-input"
                    v-model="selectedLocation"
                    placeholder="请点击右侧按钮选择位置"
                    disabled
                />
                <button class="location-btn" @tap="openLocationPicker">
                    <text>选择位置</text>
                </button>
            </view>

            <view class="info-panel" v-if="locationData">
                <view class="info-header">
                    <text class="info-title">已选位置信息</text>
                    <button class="copy-btn" @tap="copyLocationInfo">复制</button>
                </view>
                <text>经度: {{locationData.longitude}}</text>
                <text>纬度: {{locationData.latitude}}</text>
                <view v-if="locationData && locationData.address">
                    <text>省市区: {{locationData.province}}-{{locationData.city}}-{{locationData.district}}</text>
                    <text>地址: {{locationData.address}}</text>
                </view>
            </view>
        </view>

        <!-- 使用地图选择器组件 -->
        <jntc-tencentmaps-picker
            ref="mapPicker"
            :map-key="mapKey"
            :center="center"
            :on-confirm="handleConfirm"
            :on-cancel="handleCancel">
        </jntc-tencentmaps-picker>
    </view>
</template>
<script>
    export default {
        data() {
            return {
                mapKey: '',   // 你的腾讯地图 API Key（留空则读取 config.js 全局配置）
                selectedLocation: '',
                locationData: null,
                center: [116.3970, 39.9068],
                currentCity: ''
            }
        },
        methods: {
            // 方式一：打开地图选择器（推荐）
            async openLocationPicker() {
                const result = await this.$refs.mapPicker.show();
                if (!result) return; // 用户取消
                console.log('选择的位置:', result);
            },

            // 确认选择回调（与 show() 的 Promise 返回值一致，两种方式可并存）
            handleConfirm(data) {
                this.locationData = data;
                if (data && data.address) {
                    this.selectedLocation = data.address;
                } else {
                    this.selectedLocation = `${data.longitude}, ${data.latitude}`;
                }
                uni.showToast({ title: '位置已选择', icon: 'success' });
            },

            // 取消选择回调
            handleCancel() {
                console.log('取消选择');
            },

            // 方式二：直接获取当前位置（不显示地图）
            async getCity() {
                try {
                    const data = await this.$refs.mapPicker.getLocationDirectly();
                    this.locationData = data;
                    if (data.data && data.data.formatted_addresses) {
                        this.selectedLocation = data.data.address || data.data.formatted_addresses.recommend;
                        const ac = data.data.addressComponent;
                        this.currentCity = ac.city || ac.province || '未知城市';
                    } else {
                        this.selectedLocation = `${data.longitude}, ${data.latitude}`;
                        this.currentCity = '未知城市';
                    }
                } catch (error) {
                    console.error('获取位置失败:', error);
                }
            },

            // 复制位置信息
            copyLocationInfo() {
                if (!this.locationData) return;
                const ld = this.locationData;
                let copyText = `经度：${ld.longitude}\n纬度：${ld.latitude}`;
                if (ld.province || ld.city || ld.district) {
                    copyText += `\n省市区：${ld.province || ''}-${ld.city || ''}-${ld.district || ''}`;
                }
                if (ld.address) {
                    copyText += `\n地址：${ld.address}`;
                }
                uni.setClipboardData({
                    data: copyText,
                    success: () => uni.showToast({ title: '已复制', icon: 'success' }),
                    fail: () => uni.showToast({ title: '复制失败', icon: 'none' })
                });
            }
        }
    }
</script>
<style lang="scss" scoped>
    .page {
        min-height: 100vh;
        background: #f5f5f5;
        padding: 32rpx;

        .header {
            margin-bottom: 28rpx;

            .title-row {
                display: flex;
                align-items: center;
                justify-content: space-between;
                margin-bottom: 24rpx;

                .title {
                    font-size: 28rpx;
                    font-weight: bold;
                    color: #333;
                }

                .current-city {
                    font-size: 28rpx;
                    color: #667eea;
                    font-weight: 500;
                }
            }

            .switch-city-btn {
                width: 100%;
                height: 88rpx;
                background: #ffffff;
                color: #333;
                border-radius: 12rpx;
                font-size: 32rpx;
                font-weight: 500;
                border: none;

                &::after {
                    border: none;
                }
            }
        }

        .input-section {
            background: #ffffff;
            border-radius: 24rpx;
            padding: 32rpx;
            box-shadow: 0 4rpx 12rpx rgba(0, 0, 0, 0.05);

            .input-wrapper {
                display: flex;
                align-items: center;
                gap: 24rpx;
                margin-bottom: 32rpx;

                .location-input {
                    flex: 1;
                    height: 88rpx;
                    padding: 0 24rpx;
                    background: #f8f8f8;
                    border-radius: 12rpx;
                    font-size: 28rpx;
                    color: #333;
                }

                .location-btn {
                    width: 200rpx;
                    height: 88rpx;
                    background: #eee;
                    color: #333;
                    border-radius: 12rpx;
                    display: flex;
                    align-items: center;
                    justify-content: center;
                    font-size: 28rpx;
                    border: none;

                    &::after {
                        border: none;
                    }
                }
            }

            .info-panel {
                padding: 24rpx;
                background: #f8f9fa;
                border-radius: 12rpx;

                .info-header {
                    display: flex;
                    align-items: center;
                    justify-content: space-between;
                    margin-bottom: 16rpx;
                }

                .info-title {
                    font-size: 28rpx;
                    font-weight: bold;
                    color: #333;
                }

                .copy-btn {
                    width: 120rpx;
                    height: 56rpx;
                    line-height: 56rpx;
                    font-size: 24rpx;
                    background: #667eea;
                    color: #fff;
                    border-radius: 8rpx;
                    border: none;

                    &::after {
                        border: none;
                    }
                }

                text {
                    display: block;
                    font-size: 26rpx;
                    color: #666;
                    line-height: 1.8;
                }
            }
        }
    }
</style>

使用方式

方式一：直接获取当前位置

调用 getLocationDirectly()，无需显示地图，直接返回坐标和地址信息。适用于快速定位、切换城市等场景。

• 无地图界面，直接返回结果
• 自动获取设备位置 + 逆地理编码
• 内置加载提示和错误处理
• 支持 async/await

方式二：地图选择器

调用 show()，显示地图弹窗供用户手动选择位置。适用于填写地址、选择坐标等场景。

• 地图弹窗 + 拖拽选点
• 打开即自动定位
• 全国范围 POI 搜索（支持跨区域搜索）
• 拖拽地图自动获取地址 + 周边地点推荐
• 搜索结果按距离排序
• 内置确认/取消交互

小程序端调用 show() 会自动使用 uni.chooseLocation，返回结构与 App/H5 一致（不含 adcode 等扩展字段）。

扩展组件使用示例

位置展示 jntc-tencentmaps-location

展示门店/地址位置，用户可查看周边、调起导航。

<jntc-tencentmaps-location ref="location" :map-key="mapKey" />

// 单点展示
this.$refs.location.show({
    longitude: 116.397,
    latitude: 39.908,
    name: '门店A',
    address: '北京市东城区xx路1号'
});

// 多点展示：地图自动缩放包含全部点，点击标记切换底部卡片
this.$refs.location.show({
    points: [
        { longitude: 116.397, latitude: 39.908, name: '门店A', address: 'xx路1号' },
        { longitude: 116.405, latitude: 39.915, name: '门店B', address: 'xx路2号', iconUrl: '/static/shop.png' },
        { longitude: 116.412, latitude: 39.902, name: '门店C', address: 'xx路3号' }
    ],
    activeId: 1   // 可选，初始激活第几个（从 1 开始）
});

• 单点 / 多点两种模式，兼容单点旧用法
• 底部卡片展示店名、地址，多点时带 1/N 序号
• "去这里"导航：App 拉起高德/腾讯/百度，H5 打开腾讯路线规划，小程序 uni.openLocation
• 周边 POI 弹层，选中可切换展示点

路线规划 jntc-tencentmaps-route

规划起点到终点的路线，支持切换出行方式、查看分步骤详情、调起导航。

<jntc-tencentmaps-route ref="route" :map-key="mapKey" />

this.$refs.route.show({
    // from 不传则自动定位当前位置
    from: { longitude: 116.397, latitude: 39.908, name: '我的位置' },
    to: { longitude: 116.405, latitude: 39.915, name: '门店A', address: 'xx路1号' },
    mode: 'driving',      // 可选：driving 驾车 / walking 步行 / bicycling 骑行，默认 driving
    fullscreen: true      // 可选：默认全屏
});

• 驾车 / 步行 / 骑行一键切换，路线按方式自动变色
• 展示耗时、里程、分步骤路线详情（可展开）
• "开始导航"按当前方式映射第三方地图参数

前端定位 jntc-tencentmaps-geolocation

三级定位链自动降级，支持实时位置监听，对标腾讯官方前端定位组件。

<jntc-tencentmaps-geolocation ref="geo" :map-key="mapKey" />

// 单次定位（打开弹窗）
const result = await this.$refs.geo.show();
// result = { lon, lat, type: 'gps'|'h5'|'ip', address, province, city, district, street, street_number, adcode }

// 实时定位监听（弹窗可以不开）
this.$refs.geo.startWatch((pos) => {
    console.log('位置更新：', pos.lon, pos.lat, pos.type);
}, { interval: 10000 });

// 停止监听
this.$refs.geo.stopWatch();

• 定位链：设备 GPS → H5 前端定位工具（GCJ02 直出）→ IP 定位，逐级降级
• 实时监听：H5 走官方组件 watchPosition，App 走 plus.geolocation，小程序走 startLocationUpdate，失败自动降级轮询
• 拿到坐标自动逆地理编码补全详细地址
• 组件挂载后即可调 startWatch 作纯后台定位服务

H5 端使用前端定位工具需在腾讯控制台为该 Key 勾选"前端定位组件"权限，并将域名加入白名单。

地图轨迹回放 jntc-tencentmaps-track

轨迹折线展示 + 平滑回放动画，支持显示我的当前位置。

<jntc-tencentmaps-track ref="track" :map-key="mapKey" />

this.$refs.track.show({
    points: [   // GCJ02，按时间顺序
        { longitude: 116.397, latitude: 39.908, time: 1729045200000 },
        { longitude: 116.401, latitude: 39.910, time: 1729045260000 },
        { longitude: 116.405, latitude: 39.913 }   // time 可选，有则自动统计全程时长
    ],
    lineColor: '#2F6BFF',  // 可选，轨迹线颜色
    duration: 15000,       // 可选，回放总时长 ms
    autoPlay: false,       // 可选，是否自动播放
    follow: true,          // 可选，回放时地图是否跟随
    fullscreen: false,     // 可选，默认半屏
    myLocation: true,      // 可选，是否自动显示我的位置（默认跟随 showMyLocation prop）
    playIcon: '/static/car.png',  // 可选，回放点自定义图标（不传为内置蓝色圆点）
    playText: '张三 · 巡查车'     // 可选，回放点上方显示的文字（不传则不显示）
});

• 按累计里程线性插值平滑回放（非点间跳变）
• 播放 / 暂停、1x / 2x / 4x 倍速、进度条拖动实时预览、跟随镜头开关
• 绿色起点 / 蓝色终点图钉，轨迹带方向箭头
• 回放点支持自定义图标 + 上方文字标签；回放中可用 setPlayText() 动态换文字
• 内置"我的当前位置"：蓝点显示 + 定位按钮

API 文档

jntc-tencentmaps-picker（地图选择器）

Props

Methods

返回数据结构

show() 确认选择时返回：

{
    longitude: 116.404,      // 经度
    latitude: 39.915,        // 纬度
    name: '天安门广场',       // 地点名称
    address: '北京市东城区...', // 详细地址
    adcode: '110100',        // 行政区码
    province: '北京市',       // 省份
    city: '北京市',          // 城市
    district: '东城区'       // 区县
}

小程序端通过 uni.chooseLocation 返回，仅包含 longitude、latitude、name、address 四个字段。

getLocationDirectly() 返回：

{
    longitude: 116.404,
    latitude: 39.915,
    data: {
        // 逆地理编码完整结果
        formatted_address: '北京市东城区...',
        address: '北京市东城区...',
        addressComponent: { province, city, district, street, ... },
        formatted_addresses: { recommend, rough },
        adcode: '110100',
        pois: [...],           // 周边 POI 列表
        location: { lon, lat }
    }
}

jntc-tencentmaps（基础地图组件）

Props

Methods

以上 set* 方法的覆盖物在地图重建后会自动恢复；组件卸载时自动清理，跨弹窗切换无残留。

jntc-tencentmaps-location（位置展示）

Props

Methods

jntc-tencentmaps-route（路线规划）

Props

Methods

jntc-tencentmaps-geolocation（前端定位）

Props

Methods

jntc-tencentmaps-track（地图轨迹回放）

Props

Methods

工具函数

组件内置工具函数位于 mapUtils.js，可直接引入使用：

import { getAddressByLocation, searchPlace, getDistance, coordTranslate } from '@/uni_modules/jntc-tencentmaps/components/jntc-tencentmaps/mapUtils.js';

getAddressByLocation(lon, lat, mapKey) — 逆地理编码

根据坐标获取地址信息，同时返回周边 POI 列表。

返回： Promise<Object>

const data = await getAddressByLocation(116.404, 39.915, '你的KEY');
console.log(data.formatted_address);    // 完整地址
console.log(data.addressComponent);     // 省市区等
console.log(data.pois);                 // 周边 POI 列表

getLocationByAddress(address, mapKey) — 正地理编码

根据地址获取坐标。

返回： Promise<Object> — { lon, lat, ... }

const loc = await getLocationByAddress('北京市天安门广场', '你的KEY');
console.log(loc.lon, loc.lat);

searchPlace(keyword, mapKey, options) — 全国地点搜索

支持全国范围 POI 搜索，不受当前位置限制。

参数：

• keyword (String): 搜索关键词
• mapKey (String): API Key
• options (Object): 可选参数
  • lon / lat (Number): 当前位置坐标，用于计算距离
  • radius (Number): 搜索半径（米），默认 5000
  • adcode (String): 行政区码，限定搜索范围
  • page_size (Number): 每页返回数量，默认 20
  • page_index (Number): 页码，默认 1

返回： Promise<Array> — POI 列表，每项包含 name、address、lon、lat、distance 等

coordTranslate(lon, lat, type, mapKey) — 坐标系转换

腾讯官方接口转换，失败时自动降级至本地算法。

参数：

• type: 1 = WGS84 → GCJ02（默认），3 = GCJ02 → WGS84

返回： Promise<Object> — { lon, lat }

ipGeolocation(mapKey) — IP 定位

通过 IP 获取大致位置，作为 GPS 定位失败的降级方案。

返回： Promise<Object> — { lon, lat }

getDistance(lon1, lat1, lon2, lat2) — 距离计算

计算两个坐标点之间的球面距离。

返回： Number — 距离（米）

getRoutePlan(mode, from, to, mapKey) — 路线规划

按出行方式规划路线，自动解压腾讯 polyline 差分坐标。

参数：

• mode (String): driving 驾车 / walking 步行 / bicycling 骑行 / ebicycling 电动自行车
• from / to (Object): { lon, lat }（GCJ02）

返回： Promise<Object> — { distance(米), duration(分钟), polyline: [{lon,lat}], steps: [{instruction, distance, duration}] }

const route = await getRoutePlan('driving', { lon: 116.397, lat: 39.908 }, { lon: 116.405, lat: 39.915 }, '你的KEY');
console.log(route.distance, route.duration, route.polyline);

getGljsUrl(mapKey) — 动态获取 GL JS SDK 地址

从配置的接口动态获取腾讯 GL JS SDK 加载地址，成功后模块级缓存（整个应用生命周期只请求一次），失败返回空字符串。

返回： Promise<String> — SDK 加载地址

配置说明

在 config.js 中配置全局默认值：

// 默认腾讯地图 KEY（使用者传 mapKey prop 时会覆盖此值）插件中获取
const DEFAULT_MAP_KEY = "你的KEY";

// 地图默认配置
const MAP_CONFIG = {
    defaultCenter: [116.411794, 39.9068],  // 默认中心点
    defaultZoom: 16,                        // 默认缩放
    defaultSearchRadius: 1000,              // 默认搜索半径（米）
    defaultSearchCount: 20,                 // 默认返回条数
};

注意事项

1. API Key：组件需要腾讯地图 API Key 才能工作，前往 腾讯地图开放平台 申请。可通过 prop 传入或在 config.js 中全局配置。

2. 坐标系：腾讯地图使用 GCJ02 坐标系。uni.getLocation 返回的 WGS84 坐标已由组件自动转换，无需手动处理。

3. 定位权限：使用定位功能需在 manifest.json 中配置定位权限，App 端还需在 sdkConfigs 中配置地图 SDK Key。

4. 小程序权限：小程序端使用 uni.chooseLocation 需在 manifest.json → mp-weixin → requiredPrivateInfos 中声明 chooseLocation。

5. 网络请求：地址解析和搜索功能依赖网络请求，需确保网络畅通。小程序端还需在后台配置 request 合法域名。

6. 性能优化：

   • 地图组件较重，建议按需加载
   • 避免在列表中同时渲染多个地图组件
   • 使用 v-if 而不是 v-show 控制地图显示

常见问题

Q: 地图不显示？

• API Key 是否正确
• 网络是否正常
• 地图容器是否设置了高度
• 域名白名单是否包含当前域名（H5 端）

Q: 定位失败？

• 是否在 manifest.json 配置了定位权限
• 用户是否授权了定位权限
• 设备定位服务是否开启

Q: 地址获取失败？

• API Key 是否有效
• 网络请求是否正常
• 坐标是否在中国境内

Q: 小程序端无法使用地图选择器？

小程序端已自动适配为 uni.chooseLocation，无需额外处理。但需在 manifest.json 中声明 requiredPrivateInfos。