Leaflet.PM 教程:在地图上绘制编辑要素
Leaflet.PM(现已更名为 Leaflet-Geoman)是专门用于在 Leaflet 地图上绘制和编辑几何要素的插件,支持 Marker、Polyline、Polygon、Circle、Rectangle、CircleMarker、LayerGroup 与 GeoJSON 等,并提供绘制、编辑、拖动、切割、旋转和吸附功能。截至 2026 年 11 月,免费版最新包为 @geoman-io/leaflet-geoman-free 2.20.6(2026-11-04 发布),引入后调用 map.pm.addControls() 即可弹出工具栏完成要素创建与修改。旧 leaflet.pm 包已弃用,请先卸载再安装新包;当前兼容 Leaflet 1.x(peer 依赖 ^1.2.0),Leaflet 2.0 尚在迁移中。

如何安装并正确引入
先确保项目已有可用的 Leaflet 底图。如果你还没搭好地图骨架,可先参考本站用 Leaflet.js 构建第一个交互式 Web 地图,再叠加本插件。需要天地图或 WMTS 底图时,也可对照Leaflet 加载天地图 Key 申请与配置和Leaflet 加载 WMTS 瓦片与离线地图。
- 用 npm 安装免费版:在终端执行 npm i @geoman-io/leaflet-geoman-free@^2.20.6。若项目里还有旧包,先执行 npm uninstall leaflet.pm。
- ES6 模块方式(推荐):先 import leaflet 及其 CSS,再 import “@geoman-io/leaflet-geoman-free” 和对应 CSS。必须导入 JS 文件,只引 CSS 会导致 L.PM 未定义。
- CDN 方式:在页面 head 或 body 中引入 unpkg 的 leaflet-geoman.css 与 leaflet-geoman.js(或 .min.js),版本可写 latest 或锁定 2.20.6。
- 引入后插件会自动挂到 L.PM。创建地图实例后,在控制台执行 console.log(L.PM.version) 确认版本,避免框架(如 Vue)里导入顺序错误。
开发构建环境通常要求 Node.js >=20。浏览器端只需 Leaflet 1.x 即可运行。
添加工具栏并开始绘制
地图创建完成后,调用 map.pm.addControls() 即可显示工具栏。常用写法是指定位置并按需开关按钮:
- 执行 map.pm.addControls({ position: ‘topleft’, drawCircleMarker: false, rotateMode: false })。position 可选 topleft、topright 等。
- 工具栏默认开启 drawMarker、drawPolyline、drawPolygon、drawCircle、drawRectangle、editMode、dragMode、cutPolygon、removalMode 等。不想要的按钮在对象里设为 false。
- 进入绘制:map.pm.enableDraw(‘Polygon’, { snappable: true, snapDistance: 20 })。形状名可用 Marker、CircleMarker、Circle、Line、Rectangle、Polygon、Text、Cut。
- 结束当前绘制用 map.pm.finishDraw(),退出绘制模式用 map.pm.disableDraw()。工具栏可随时用 map.pm.removeControls() 或 map.pm.toggleControls() 控制显隐。

图层组建议用 L.FeatureGroup 或 L.GeoJSON,并监听 layeradd / layerremove,否则部分编辑事件可能丢失。绘制完成后图层会自动带上 pm 能力,可直接进入编辑。
| 常用工具栏选项 | 默认值 | 说明 |
|---|---|---|
| position | ‘topleft’ | 工具栏在地图上的位置 |
| drawMarker / drawPolyline / drawPolygon 等 | true | 是否显示对应绘制按钮 |
| editMode / dragMode / cutPolygon / removalMode / rotateMode | true | 是否显示编辑相关按钮 |
| oneBlock | false | 是否把所有按钮收成一块 |
编辑、拖动、切割与全局选项
工具栏的编辑按钮会开启全局编辑模式,也可编程控制。常用全局选项通过 map.pm.setGlobalOptions() 一次设置:
- snappable:是否开启吸附(大量图层时建议 false,避免卡顿)。
- snapDistance:吸附像素距离,常见设 20。
- draggable:图层是否默认可拖。
- allowSelfIntersection:是否允许自相交,设 true 可减少检查开销。
- exitModeOnEscape、finishOnEnter:快捷键行为。
- pinning、snappingOrder、layerGroup、panes、cutAsCircle 等按需配置。
单个图层不想被插件接管时,创建时传入 { pmIgnore: true }。之后若要重新启用,执行 layer.options.pmIgnore = false; L.PM.reInitLayer(layer);。全局 Opt-In 模式可先 L.PM.setOptIn(true),再只对需要的地图/图层传 { pmIgnore: false }。
切割(Cut)可用来从多边形中挖洞;旋转(Rotate)对已有要素生效。Pro 版才有的 Split、Scale、Measure、Freehand、Lasso 等功能在免费版文档中会标星,当前免费版已覆盖日常绘制编辑需求。
验收标准与性能注意点
完成安装后按下面清单自检,确认功能可用:
- 控制台能打印出 L.PM.version,且接近 2.20.6。
- 工具栏出现,点击 Polygon 后能在地图上点击生成顶点并闭合。
- 选中已有多边形后出现顶点手柄,可拖动修改形状;拖动模式可整体移动要素。
- 吸附开启时,新顶点靠近已有顶点会自动贴合。
- 大量要素编辑卡顿时,关闭 snappable 或设置 limitMarkersToCount,并避免频繁自相交检查。
完整 changelog 与发行说明可在 GitHub Releases 页面查看,遇到版本差异以官网文档为准。
常见问题
引入后 map.pm 或 L.PM 一直是 undefined?
绝大多数情况是只导入了 CSS 而没导入 JS,或在创建地图实例之前没有完成 Geoman 的 import。请确认 import 顺序,并在地图创建后立刻 console.log(L.PM.version) 验证;Vue/React 等框架里尤其注意打包后是否把插件打进了主包。
编辑大量图层时地图变得很卡怎么办?
把全局 snappable 设为 false,必要时加 limitMarkersToCount,并允许自相交(allowSelfIntersection: true)。避免在每次编辑事件里做重计算。免费版已足够日常使用,超大规模场景再考虑 Pro 的性能选项。
如何让某些图层完全不受插件影响?
创建图层时加上 { pmIgnore: true }。若之后需要临时启用,改回 false 并调用 L.PM.reInitLayer(layer)。Opt-In 模式下默认全部忽略,只有显式传 pmIgnore: false 的才会初始化。
现在能不能直接用在 Leaflet 2.0 上?
截至 2026 年 11 月尚未完全兼容,维护者仍在迁移。生产环境请继续使用 Leaflet 1.x(推荐测试过的 1.9.x)。需要最新进展可关注官方仓库讨论。
总结:先卸载旧 leaflet.pm,安装 @geoman-io/leaflet-geoman-free 2.20.6,引入后 addControls 即可开箱绘制编辑;绘制时善用 snappable 与 pmIgnore 控制行为,大量图层时优先关吸附。建议从本站 Leaflet 入门教程搭好地图,再叠加本插件,并定期查看 Leaflet-Geoman 官方 GitHub 仓库 获取更新与示例。