MapLibre GL JS 用 maplibre-gl-draw 绘制图形
在 MapLibre GL JS 中用 maplibre-gl-draw 绘制图形,当前更推荐现代化的 @sakuzu/maplibre-gl-draw:安装后调用 createDraw(map) 得到绘图实例,再用 setMode 切换到 draw_point、draw_line、draw_polygon 等模式即可交互绘制与编辑,最后用 document.toGeoJSON() 导出。截至 2026 年 11 月,该库最新版本为 2.2.0(2026-10-10 发布),需配合 MapLibre GL JS 约 6.11.1 及以上,并依赖 WebGL2。若你更习惯旧版 mapbox-gl-draw 的 IControl 写法,也可选用 @birkskyum/maplibre-gl-draw,通过 map.addControl 接入。

两种 maplibre-gl-draw 该怎么选
标题里的 “maplibre-gl-draw” 实际对应多个包,选型时先看你的地图版本、数据量和接入方式。下面按常见 GIS 场景对比两个主要选择(以官方仓库说明为准)。
| 对比项 | @sakuzu/maplibre-gl-draw | @birkskyum/maplibre-gl-draw |
|---|---|---|
| 定位 | 独立 WebGL2 渲染的现代重写,面向大量可编辑地物 | mapbox-gl-draw 的 TypeScript / MapLibre 移植 |
| 接入方式 | createDraw(map),非传统 IControl | map.addControl(new MapLibreDraw()) |
| 能力侧重 | 倾斜、3D 地形、地球仪、跨日界线;约可达 20 万可编辑地物量级 | 模式接近旧版(simple_select、draw_line_string 等),2.1 起含 draw_rectangle |
| 最新信息(截至 2026-11) | 2.2.0(2026-10-10);AGPL-3.0-only | 约 2.1.x;活跃度与下载量相对较低 |
| 适用场景 | 新项目、大数据编辑、需要地形/globe | 从 mapbox-gl-draw 迁移、想沿用 Control 工具栏习惯 |
新项目且 MapLibre 已是 v6,优先看 sakuzu/maplibre-gl-draw 仓库与文档。若必须保持 IControl 交互习惯,再评估 birkskyum/maplibre-gl-draw 仓库。下文步骤以 sakuzu 版为主。
安装与快速上手绘制图形
目标:在已有 MapLibre 地图上画出可编辑的点、线、面,并能导出 GeoJSON。先确认浏览器支持 WebGL2,MapLibre 使用 v6(约 6.11.1+;官方说明 6.12 及之后在耦合点检查通过后亦可)。bundler(尤其 Vite)下务必手动设置 worker,否则底图常空白。
- 安装主包(ESM only;maplibre-gl 为 peerDependency):npm install @sakuzu/maplibre-gl-draw。需要标准工具栏时可再装 @sakuzu/maplibre-gl-draw-ui。
- 引入 MapLibre 样式与库,并用 ?worker&url 等方式把 worker URL 交给 maplibregl.setWorkerUrl(或等价 API),避免相对路径被打包破坏。
- 创建 map 实例后执行 const draw = createDraw(map)。默认一般是 select 模式,并会建一个空图层。
- 调用 draw.setMode(‘draw_polygon’)(或 draw_point、draw_line、draw_circle、draw_freehand、draw_image)开始绘制;双击/回车等结束绘制的交互以官方 drawing 指南为准。
- 监听 draw.on(‘feature.created’, …) 等事件拿到要素;保存用 draw.document.toGeoJSON() 或 toJSON();加载用 await draw.document.load(…);销毁时先 draw.destroy(),再 map.remove()。
无 bundler 时可用 esm.sh 一类 CDN 配合 import map。官方还提供 playground 与 examples,适合先点选模式验证交互再抄进项目。
绘制模式、事件与数据读写怎么用
内置模式(MODES)主要包括:select(默认,选择、移动、缩放、旋转、顶点编辑)、draw_point、draw_line、draw_polygon、draw_circle、draw_freehand、draw_image。业务上通常是:进入绘制模式 → 用户完成一笔 → 回到 select 做微调 → 批量导出。
- 模式切换:draw.setMode(‘draw_line’);画完一笔后根据产品流程切回 select,避免误触继续加点。
- 关键事件:feature.created、以及编辑过程中的变更类事件(以当前版本文档为准),用来同步到你的业务图层或表单。
- 导出:toGeoJSON() 方便对接 PostGIS、GeoServer、前端 GeoJSON 图层;native toJSON() 适合本库往返加载。
- 加载:document.load 支持把已有数据灌回可编辑状态;只读展示可走 read-only 相关能力,避免误改。
- 吸附与几何:snapping 选项(如 tolerancePx)以及 /geometry 子入口提供的纯函数运算,可在 Worker 里算交并差,减轻主线程压力。
createDraw 第二参数可配 defaultMode、snapping、rendering(如 cacheGeometry、timeSlicing)、style 等。大数据非编辑底图可用 datasets;可编辑层与组(layers/groups)分开管理,便于按业务开关显示。

配置要求、许可与常见踩坑
把环境一次配对齐,比事后排查“地图白屏、画不上去”省事。
- 运行环境:WebGL2 + ES2020;与 MapLibre GL JS v6 支持的浏览器范围一致。不支持把 sakuzu 硬接到 MapLibre v5。
- Worker:v6 在 Vite 等打包后必须显式 setWorkerUrl,这是官方 getting-started 强调的步骤。
- 许可:@sakuzu/maplibre-gl-draw 为 AGPL-3.0-only;闭源商用需向权利方(资料中为 Kasika, Inc.)另行获取商业许可,上线前先确认合规。
- 性能:可编辑地物冲到很大数量时打开 timeSlicing、合理用缓存,并把不可编辑底数放到 datasets;真正编辑层控制在可交互范围。
- 框架:无强制框架依赖,React / Vue / Svelte 有 frameworks 指南;记得在组件卸载时 destroy,避免 WebGL 上下文泄漏。
- 与 birkskyum 混用注意:模式名、事件名、Control 生命周期都不相同,不要假设 API 一一对应。
验收建议:能画出闭合面并在 select 下拖顶点;刷新后 load 同一份 GeoJSON 形状一致;倾斜或 globe 模式下图形仍可贴合地表(若你业务需要);destroy 后无残留图层与报错。
常见问题
画了图形但地图是空白或报错?
优先检查 MapLibre worker 是否已 setWorkerUrl,以及浏览器是否 WebGL2。Vite 下未正确引入 maplibre-gl-worker 时,底图与绘制层都可能异常。确认 peer 的 maplibre-gl 版本在约 6.11.1+。
想用矩形或自由手绘,模式名是什么?
sakuzu 版内置含 draw_circle、draw_freehand 等;矩形若必须用,可看 birkskyum 在 2.1 起增加的 draw_rectangle,或用多边形约束实现。以你所选包的 MODES / CHANGELOG 为准,不要混用两套模式名。
十几万要素还能流畅编辑吗?
sakuzu 设计目标提到约可达 20 万可编辑地物量级,但仍取决于机器、样式复杂度与是否开启 timeSlicing 等。实践上把静态底数与可编辑层拆开,并用 /table 等入口做数据准备更稳妥。
商业项目可以直接 npm 上生产吗?
AGPL-3.0-only 对闭源分发约束很严。开源合规可按 AGPL 使用;闭源产品请走商业许可或改选许可更匹配的方案,不要事后补救。
总结:MapLibre GL JS 上绘制图形,优先用 @sakuzu/maplibre-gl-draw 的 createDraw + setMode 流程,配好 v6 worker 与 WebGL2,用 toGeoJSON 对接后续 GIS 链路;需要旧式 Control 时再评估 birkskyum 移植版。建议先在官方 playground 跑通一种面绘制与导出,再把同一套 destroy / load 生命周期嵌进你的页面,并尽早确认 AGPL 与业务许可是否匹配。