更新记录

1.0.2（2026-05-28） 下载此版本

优化部分代码

1.0.1（2026-01-29） 下载此版本

更改组件静态文件引入错误，更改使用文档错误

1.0.0（2026-01-04） 下载此版本

实现基本功能且可自由扩展

平台兼容性

uni-app(3.7.8)

dq-leaflet 组件使用说明

简洁的 uni-app 渲染层封装，基于 Leaflet，通过 renderjs 在小程序/APP 环境中驱动地图渲染。组件将逻辑层（map.js）与渲染层（map-render.js）解耦，调用方通过在逻辑层调用方法，组件把方法打包为 mapMethods 并传入渲染层执行。适用于需要在 uni-app 中使用 Leaflet 功能但无法直接在原生环境中使用 DOM 的场景。

--

目录

• 简介
• 快速起步
• Props
• 主动方法 API（逻辑层）
• 渲染层（mapModule）说明
• 事件与回调
• 资源加载
• 示例
• 常见问题

--

兼容：适用于 uni-app 使用 renderjs 的场景；Leaflet 资源由组件动态注入，支持自定义脚本/样式扩展。

快速起步

1. 将 uni_modules/dq-leaflet 放入项目 uni_modules 下（已包含 Leaflet 源文件）。
2. 在页面中直接使用组件导出的逻辑层（组件入口为 dq-leaflet.vue）：

示例（页面 template）：

<template>
  <view>
    <dq-leaflet ref="dqmap" :scripts="[]" :links="[]" :options="mapOptions" />
  </view>
</template>

示例（在页面脚本中调用）：

// 假设组件已按常规方式注册
export default {
  mounted() {
    const mapComp = this.$refs.dqmap
    // mapOptions 中包含 center/zoom 等会被传递到 init
  }
}

Props

• scripts: Array - 额外要注入的脚本 URL 列表（可选）。
• links: Array - 额外要注入的 stylesheet URL 列表（可选）。
• options: Object - 初始化地图时的配置对象，会传给 Leaflet 的 L.map（例如 center, zoom, crs 等）。

主动方法 API（逻辑层 map.js）

说明：这些方法由组件逻辑层提供，调用后会把操作发送到渲染层执行。很多方法会返回一个内部生成的 id，用于后续操作或事件绑定。

• init(option) → mapId：创建地图实例，option 为 Leaflet map 的配置（必须包含 id 将用于 DOM id 为 mapView<id>）。
• tile(method, url, options) → layerId：加载底图，method 为 Leaflet 构造器名（例如 tileLayer 或 tileLayer.wmts）；返回图层 id。
• marker(latLng, options) → markerId：创建 marker。
• geoJSON(geo, options) → geoJsonId：创建 GeoJSON 图层，子要素会作为独立图层注册并返回其 id 列表可通过 getLayers 获取。
• featureGroup(layers) / layerGroup(layers) → groupId：创建要素组或图层组，layers 为已存在图层 id 列表。
• layerControl(baselayers, overlays, options) → controlId：创建图层切换控件，参数为 { baselayers: {name: layerId}, overlays: {name: layerId} }。
• getLayers(layerId, callback)：获取指定 geoJSON 或 group 下的子图层 id 列表，结果通过回调返回。
• layerMethod(layerId, methodName, ...args)：在指定图层实例上调用方法；如果最后一个参数为函数，会作为异步回调（通过回调 id 机制返回）。
• createMapMethod(method, ...args) / lMethod(...)：调用 Leaflet 的工厂方法（如 L.icon / L.latLng），并将返回值注册为组件内部 id，返回该 id，方便后续复用。
• 视图与缩放快捷方法：setView(center, zoom, options), panTo(center), flyTo(center, zoom), setZoom(zoom), zoomIn(delta), zoomOut(delta)。
• 控件与图层管理：addBaseLayer(controlId, layerId, name), addOverlay(controlId, layerId, name), addLayer(layerGroupId, layerId), addControl(mapId, controlId), removeLayer(layerId), clearLayers(layerGroupId)。

注意：大多数返回的 id 都是组件内部生成的字符串，请不要在外部对这些 id 做任何变更。

渲染层（mapModule / map-render.js）说明

• 渲染层运行在 renderjs 模块（参见组件文件 dq-leaflet.vue 中 <script lang="renderjs" module="mapModule">），负责实际调用 Leaflet API 并维护实体对象映射（mapLayers, mapLayerGroups 等）。
• 渲染层接收的命令以 mapMethods 的 methods 数组形式批量下发，格式为 [[methodName, options], ...]，并逐一执行。
• 渲染层会将创建的 Leaflet 实例按 id 保存到内部 Map 中；当需要在渲染层向逻辑层回调时（例如事件或方法返回值），会调用逻辑层的 emitEvent / emitCallBack。

事件与回调

• 绑定事件（逻辑层）：onEvent(layerId, eventType, handler) → 返回 funcId。
  • 第一次为某 layerId 的某 eventType 绑定时，会在渲染层为该 layer 实例注册真实的 handler；后续绑定只是把回调加入内部列表。
  • handler(data) 的 data 为渲染层序列化后的对象（已剔除函数，处理循环引用）。
• 解绑事件：offEvent(layerId, type, func?)。
  • 若提供 func（同一函数引用），只解绑该回调；否则解绑该类型的全部回调并从渲染层移除 handler。
• 异步回调（方法结果）：在逻辑层调用 layerMethod(..., callback) 或 getLayers(..., callback) 时，组件内部会生成 funcId 并在渲染层执行完毕后通过 emitCallBack({funcId, data}) 将结果返回并自动删除回调映射。

资源加载

• 组件内置的 Leaflet 资源路径为 uni_modules/dq-leaflet/static/leaflet/，会优先加载组件自带的 leaflet.css 与 leaflet.js。
• 可通过 scripts 与 links props 传入额外资源；loadResource.js 会做幂等校验（避免重复注入相同 URL）。

示例：常见用法

创建地图、加载底图、添加 marker、监听点击：

// 假设组件 ref 为 dqmap
const mapComp = this.$refs.dqmap
const mapId = mapComp.init({ id: 'main', center: [31.23, 121.47], zoom: 10 })
// 加载瓦片
const tileId = mapComp.tile('tileLayer', '//t{s}.tianditu.gov.cn/img_c/wmts?LAYER=img&TILEMATRIXSET=c&SERVICE=WMTS&REQUEST=GetTile&VERSION=1.0.0&STYLE=default&FORMAT=tiles&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=95025b56ea405f40f5a9415b2213dd67', { maxZoom: 19 })
// 添加到地图（如果需要）
mapComp.addLayer(mapId, tileId)
// 添加 marker
const markerId = mapComp.marker([31.23, 121.47], { title: '这里' })
// 绑定点击事件
const handlerId = mapComp.onEvent(markerId, 'click', (e) => {
  console.log('marker clicked', e)
})
// 解绑
mapComp.offEvent(markerId, 'click')

获取 GeoJSON 子图层 id：

const geoId = mapComp.geoJSON(geojsonObj, {})
mapComp.getLayers(geoId, (ids) => {
  console.log('子图层 ids', ids)
})

在图层上调用方法并获取返回值（回调方式）：

mapComp.layerMethod(layerId, 'getBounds', (bounds) => {
  console.log('bounds', bounds)
})

常见问题与注意事项

• DOM id 约定：组件在渲染层使用 DOM id 为 mapView<mapId>（其中 mapId 为 init 返回的 id）。确保 id 唯一。
• 不要在外部修改组件生成的 id 值；id 仅作引用键使用。
• 渲染层会把传入回调在执行后自动移除，避免内存泄漏。
• 若在打包环境中需要使用自定义 CRS（投影），请在 options 中传入 crs 字段，渲染层会尝试使用 L.Proj.CRS。