wx-tilemap

微信小程序自定义瓦片地图组件 — 基于 Mercator 投影的轻量级地图引擎。

特性

• 自定义瓦片源（默认高德地图，支持替换为任意 {x}/{y}/{z} 瓦片服务）
• 覆盖图层（Overlay） — 支持叠加手绘地图、景区平面图等半透明图片覆盖层
• 定位蓝点（Location） — GPS 实时定位，带动画脉冲效果
• 标记点（Marker）— 支持自定义图标、标题、气泡弹窗
• 折线（Polyline）— 支持虚线、箭头端点
• 多边形（Polygon）— 支持填充色、描边、虚线
• 手势交互 — 单指拖动（含惯性）、双指缩放、双击放大
• 飞行动画（flyTo）、适配范围（fitBounds）
• 缩放控件 + 比例尺 + 边界限制（maxBounds）
• 零外部依赖，纯微信原生 API 实现

安装

npm install wx-tilemap

在微信开发者工具中执行 工具 → 构建 npm。

快速开始

1. 注册组件

在页面 .json 文件中：

{
  "usingComponents": {
    "tilemap": "wx-tilemap/tilemap/index"
  }
}

2. 使用组件

<tilemap
  id="map"
  center="{{center}}"
  zoom="{{zoom}}"
  markers="{{markers}}"
  polylines="{{polylines}}"
  polygons="{{polygons}}"
  showZoomControl="{{true}}"
  showScaleControl="{{true}}"
  maxBounds="{{bounds}}"
  bind:click="onMapClick"
  bind:markertap="onMarkerTap"
  bind:zoomchange="onZoomChange"
  bind:moveend="onMoveEnd"
/>

3. 调用方法

const map = this.selectComponent('#map');
map.setView(39.916, 116.397, 17);
map.flyTo(31.230, 121.474, 14, { duration: 800 });
map.fitBounds(points, { padding: 50 });

API

Properties

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | tileUrl | String | 高德瓦片 URL | 瓦片地址模板，支持 {x} {y} {z} {s} 占位符 | | tileSubdomains | String | '1234' | 瓦片子域名轮换字符 | | minZoom | Number | 3 | 最小缩放级别 | | maxZoom | Number | 20 | 最大缩放级别 | | zoom | Number | 16 | 初始缩放级别 | | center | Object | { lat: 39.909, lng: 116.397 } | 初始中心坐标 | | markers | Array | [] | 标记点数组 | | polylines | Array | [] | 折线数组 | | polygons | Array | [] | 多边形数组 | | showZoomControl | Boolean | false | 显示缩放控件 | | showScaleControl | Boolean | false | 显示比例尺 | | maxBounds | Object | null | 限制平移范围 { southWest, northEast } | | overlayImage | String | '' | 覆盖图 URL（手绘地图、景区平面图） | | overlayBounds | Object | null | 覆盖图地理范围 { southWest: {lat,lng}, northEast: {lat,lng} } | | overlayOpacity | Number | 0.6 | 覆盖图透明度（0~1） | | showLocation | Boolean | false | 显示定位蓝点（自动获取 GPS 位置） |

Markers 格式

{
  id: 'marker-1',
  latitude: 39.916,
  longitude: 116.397,
  iconPath: '/assets/marker.png',
  title: '标题',
  width: 32,
  height: 32,
  callout: { content: '气泡内容' }
}

Polylines 格式

{
  points: [{ latitude: 39.91, longitude: 116.39 }, { latitude: 39.92, longitude: 116.40 }],
  color: '#07c160',
  width: 3,
  dashArray: '8,4',
  arrowLine: true
}

Polygons 格式

{
  points: [{ latitude, longitude }, ...],
  fillColor: 'rgba(7,193,96,0.15)',
  color: '#07c160',
  width: 2,
  dashArray: '6,3'
}

方法

| 方法 | 参数 | 说明 | |------|------|------| | setView(lat, lng, zoom, options?) | options: { animate } | 设置视图（默认飞行动画） | | flyTo(lat, lng, zoom, options?) | options: { duration } | 飞行动画（默认 600ms） | | panTo(lat, lng, options?) | options: { duration } | 平移动画（默认 300ms） | | zoomIn() | — | 放大一级 | | zoomOut() | — | 缩小一级 | | getCenter() | — | 返回 { lat, lng } | | getZoom() | — | 返回缩放级别 | | fitBounds(bounds, options?) | bounds: [{latitude, longitude}] | 适配范围，options: { padding, animate, duration } | | invalidateSize() | — | 容器尺寸变化后刷新 | | setUserLocation(lat, lng) | — | 外部设置用户位置（供 wx.onLocationChange 回调使用） |

事件

| 事件 | detail | 说明 | |------|--------|------| | click | { latlng: { lat, lng } } | 地图单击 | | markertap | { marker } | 标记点点击 | | zoomchange | { zoom, center } | 缩放变化 | | moveend | { center, zoom } | 移动结束 |

覆盖图层（手绘地图）

<tilemap
  overlayImage="https://your-cdn.com/hand-drawn-map.png"
  overlayBounds="{{overlayBounds}}"
  overlayOpacity="{{0.5}}"
/>

data: {
  overlayBounds: {
    southWest: { lat: 39.9150, lng: 116.3895 },
    northEast: { lat: 39.9255, lng: 116.4050 }
  }
}

覆盖图会自动跟随地图平移和缩放，适合叠加景区手绘地图、室内平面图等。

定位蓝点

<tilemap showLocation="{{true}}" />

开启后自动调用 wx.getLocation（gcj02 坐标系）获取位置，并显示带脉冲动画的蓝点。

持续追踪位置变化：

wx.onLocationChange((res) => {
  const map = this.selectComponent('#map');
  map.setUserLocation(res.latitude, res.longitude);
});

瓦片源示例

// 高德地图（默认）
tileUrl: 'https://webrd0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}'
tileSubdomains: '1234'

// OpenStreetMap
tileUrl: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
tileSubdomains: 'abc'

License

MIT