更新记录

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;
  • 支持空格分隔多事件名;
  • 地图点击、鼠标移动、簇点击、簇悬停、拖动、缩放、视野变化、尺寸变化、图层与几何增删事件。

快速接入

  1. 模板中直接使用 <tang-map />;
  2. 通过 ref 获取地图控制器;
  3. 创建图层、几何、控件与 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&ltype=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 合法域名,瓦片与图标域名均需加入白名单;

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。