更新记录
v2.02(2026-11-17)
无
平台兼容性
uni-app(5.36)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| - | √ | √ | √ | √ | - | √ | √ | - |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| √ | - | - | - | - | - | - | - | - | - | - | - |
适用平台
| 平台 | 支持情况 | 说明 |
|---|---|---|
| H5 | ✅ | |
| App-vue | ✅ | |
| 微信/支付宝等小程序 | ✅ | |
| nvue | ⚠️ 未专门适配 | 组件按 Vue 普通页面与 App-vue 场景实现。 |
详细介绍
tang-map 是一套面向 uni-app 的自研瓦片地图组件。组件内部完成瓦片请求、内存缓存、投影换算、相机更新、手势交互、几何绘制、聚合计算、Popup 与控件覆盖层调度。
与直接封装原生 <map> 不同,tang-map 不依赖平台原生地图组件;全程不假设 window、document 存在,适合需要在 App、H5、小程序中统一地图渲染逻辑的项目。
功能亮点
地图
- 初始中心与缩放级别配置,支持小数级别;
- 单指/单指拖动平移,双指捏合缩放,H5 滚轮缩放;
setCenter、setZoom、zoomIn、zoomOut、setCenterAndZoom;animateCamera动画过渡;fitExtent、fitGeometries、fitLayers视野适配;coordinateToContainerPoint、containerPointToCoordinate坐标互算;- 视野范围
getRegion()。
图层与几何
TmLayer:几何增删查、遍历、清空、范围计算;TmGeoJSONLayer:解析 Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon;TmMarker:图标、默认矢量圆点、标题、锚点、旋转、透明度;TmLineString:颜色、线宽、虚线、虚线数组、线尾箭头、边框;TmPolygon:单环/多环填充与描边;TmCircle:米制半径圆;TmRectangle:外接矩形;TmEllipse:米制长/短轴椭圆;- 几何支持显隐、属性、样式、移除与中心/范围获取。
点聚合
- 屏幕网格聚合,支持
gridSize、maxZoom、minClusterSize、平均中心; - 簇数量分档尺寸渲染;
- 簇点击事件
clusterclick; - H5 簇悬停进入/移出事件;
- 已聚合成员在点击命中时自动跳过,避免隐藏点误触发。
Popup 与控件
TmPopup可挂载到坐标或几何;- 支持纯文本内容、插槽自定义内容、关闭按钮、样式配置;
- 锚点贴边时自动翻转方向;
TmZoomControl缩放按钮;TmScaleControl比例尺控件。
瓦片、投影与坐标系
- 内置高德矢量、高德卫星、百度矢量、四维 预设;
- 支持自定义瓦片 URL、子域名、多层瓦片叠加;
- WGS84、GCJ02、BD09 两两互转;
- 业务坐标与底图坐标系不一致时自动转换;
事件体系
- 地图、图层、几何三级事件;
on、once、off、addEventListener、removeEventListener;- 支持空格分隔多事件名;
- 地图点击、鼠标移动、簇点击、簇悬停、拖动、缩放、视野变化、尺寸变化、图层与几何增删事件。
快速接入
- 模板中直接使用
<tang-map />; - 通过
ref获取地图控制器; - 创建图层、几何、控件与 Popup。
<template>
<view class="page">
<tang-map
ref="mapRef"
:center="center"
:zoom="15"
:tile-layers="tileLayersConfig"
coord-type="gcj02"
:cluster="{ enabled: true, gridSize: 60, maxZoom: 18, minClusterSize: 2, isAverageCenter: true }"
custom-style="height: 420px;"
/>
<view class="toolbar">
<button size="mini" :class="{ active: baseMap === 'gaode' }" @click="switchMap('gaode')">高德</button>
<button size="mini" :class="{ active: baseMap === 'gaodeSatellite' }" @click="switchMap('gaodeSatellite')">卫星+路网</button>
<button size="mini" :class="{ active: baseMap === 'baidu' }" @click="switchMap('baidu')">百度</button>
<button size="mini" :class="{ active: baseMap === 'siwei' }" @click="switchMap('siwei')">四维</button>
<button size="mini" @click="onZoomIn">放大</button>
<button size="mini" @click="onZoomOut">缩小</button>
<button size="mini" @click="onLocate">回到起点</button>
<button size="mini" @click="onFit">自适应范围</button>
<button size="mini" @click="onMyLocation">我的位置</button>
</view>
<view class="status">
<text>中心:{{ centerText }}</text>
<text>缩放:{{ zoomText }}</text>
</view>
<view class="log">
<view v-for="(item, i) in logs" :key="i" class="log-item">{{ item }}</view>
</view>
</view>
</template>
<script setup>
import { ref, computed, } from 'vue'
import {onReady} from '@dcloudio/uni-app'
import {
TmLayer,
TmGeoJSONLayer,
TmMarker,
TmLineString,
TmPolygon,
TmCircle,
TmRectangle,
TmEllipse,
TmPopup,
TmZoomControl,
TmScaleControl
} from '../../components/tang-map/index.js'
const center = [113.32452, 23.099994]
const mapRef = ref(null)
const baseMap = ref('gaode')
let map = null
// 卫星底图叠加路网注记层(双层瓦片演示);其余模式回退单底图预设
const tileLayersConfig = computed(() => {
if (baseMap.value !== 'gaodeSatellite') return baseMap.value
return [
{
id: 'satellite',
tileUrl: 'https://webst0{s}.is.autonavi.com/appmaptile?style=6&x={x}&y={y}&z={z}',
subdomains: ['1', '2', '3', '4']
},
{
id: 'roadnet',
tileUrl:
'https://wprd0{s}.is.autonavi.com/appmaptile?x={x}&y={y}&z={z}&size=1&scl=1&style=8<ype=11',
subdomains: ['1', '2', '3', '4']
}
]
})
function switchMap(key) {
baseMap.value = key
}
const centerText = ref('--')
const zoomText = ref('--')
const logs = ref([])
function pushLog(text) {
console.log(text)
if (logs.value.length > 20) logs.value.pop()
}
onReady(() => {
map = mapRef.value.getMap()
// 控件
map.addControl(new TmZoomControl())
map.addControl(new TmScaleControl())
const layer = new TmLayer('default')
const marker1 = new TmMarker([113.32452, 23.099994], { title: '起点' })
const marker2 = new TmMarker([113.33052, 23.105994], { title: '终点' })
// 聚合演示:周围撒几个点
const extras = [
[113.32252, 23.098994],
[113.32652, 23.101994],
[113.32852, 23.097994],
[113.32152, 23.103994],
[113.32952, 23.102994]
].map((c, i) => new TmMarker(c, { title: `点${i + 1}` }))
const line = new TmLineString(
[
[113.32452, 23.099994],
[113.32752, 23.102994],
[113.33052, 23.105994]
],
{ color: '#2d8cf0', width: 5, dottedLine: true, arrowLine: true }
)
const polygon = new TmPolygon(
[
[113.32052, 23.096994],
[113.32652, 23.096994],
[113.32652, 23.101994],
[113.32052, 23.101994]
],
{ fillColor: 'rgba(45,140,240,0.2)', strokeColor: '#2d8cf0', strokeWidth: 2 }
)
const rectangle = new TmRectangle(
{ xmin: 113.322, ymin: 23.095, xmax: 113.326, ymax: 23.098 },
{ fillColor: 'rgba(46,207,129,0.18)', strokeColor: '#2ecf81' }
)
const ellipse = new TmEllipse([113.328, 23.101], 300, 180, {
fillColor: 'rgba(255,184,0,0.18)',
strokeColor: '#ffb800'
})
const circle = new TmCircle([113.32452, 23.099994], 500, {
fillColor: 'rgba(255,99,99,0.15)',
color: '#ff6363'
})
layer.addGeometry([marker1, marker2, ...extras, line, polygon, rectangle, ellipse, circle])
map.addLayer(layer)
// GeoJSON 图层
const geoJson = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
properties: { name: 'GeoJSON 点' },
geometry: { type: 'Point', coordinates: [113.328, 23.103] }
},
{
type: 'Feature',
properties: {},
geometry: {
type: 'LineString',
coordinates: [
[113.321, 23.098],
[113.324, 23.1]
]
}
}
]
}
map.addLayer(
new TmGeoJSONLayer('geojson', geoJson, {
style: { Point: { title: 'GeoJSON 点' }, LineString: { color: '#7c3aed', width: 3 } }
})
)
// Popup:点击起点显示
const popup = new TmPopup({ content: '起点详情弹窗' })
marker1.on('click', () => {
popup.setCoordinates(marker1.getCenter()).addTo(map).show()
})
map.on('click', (e) => {
pushLog(`click ${e.target ? e.target.type : '地图'} ${JSON.stringify(e.coordinate)}`)
})
map.on('clusterclick', (e) => pushLog(`clusterclick 数量=${e.cluster.count}`))
map.on('moveend', () => refreshStatus())
map.on('zoomend', () => refreshStatus())
refreshStatus()
})
function refreshStatus() {
if (!map) return
const c = map.getCenter()
centerText.value = `${c[0].toFixed(5)}, ${c[1].toFixed(5)}`
zoomText.value = String(Number(map.getZoom()).toFixed(2))
}
function onZoomIn() {
map.animateCamera(map.getCenter(), map.getZoom() + 1, 200)
setTimeout(refreshStatus, 220)
}
function onZoomOut() {
map.animateCamera(map.getCenter(), map.getZoom() - 1, 200)
setTimeout(refreshStatus, 220)
}
function onLocate() {
map.animateCamera(center, 15, 300)
setTimeout(refreshStatus, 320)
}
function onFit() {
const layer = map.getLayer('default')
if (layer) map.fitLayers(layer)
}
function onMyLocation() {
map.moveToLocation()
}
</script>
<style scoped>
.page {
display: flex;
flex-direction: column;
height: 100vh;
}
.toolbar {
display: flex;
gap: 12rpx;
padding: 20rpx;
flex-wrap: wrap;
}
.toolbar button.active {
background: #2d8cf0;
color: #ffffff;
}
.status {
padding: 0 20rpx 20rpx;
display: flex;
flex-direction: column;
gap: 8rpx;
}
.log {
padding: 0 20rpx 20rpx;
}
.log-item {
font-size: 24rpx;
color: #666;
line-height: 1.6;
}
</style>
内置底图预设
| 预设 key | 名称 | 投影 | 底图坐标系 | 级别范围 |
|---|---|---|---|---|
gaode |
高德矢量 | mercator | gcj02 | 4-18 |
gaodeSatellite |
高德卫星 | mercator | gcj02 | 4-18 |
baidu |
百度矢量 | bd09 | bd09 | 4~19 |
siwei |
四维地图 | mercator | gcj02 | 4-18 |
自定义瓦片源
<tang-map
coord-type="gcj02"
:tile-layers="{
tileUrl: 'https://rt{s}.map.gtimg.com/tile?z={z}&x={x}&y={y}&styleid=1',
subdomains: ['0', '1', '2', '3'],
projection: 'mercator',
sourceCoord: 'gcj02'
}"
/>
瓦片模板支持 {z}、{x}、{y}、{s} 占位符;也可传入图层栈数组,实现影像底图 + 路网注记等多层叠加。
注意事项
- 小程序端需在后台配置
downloadFile合法域名,瓦片与图标域名均需加入白名单;

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 2
赞赏 0
下载 12772874
赞赏 1960
赞赏
京公网安备:11010802035340号