MapLibre GL JS 用 maplibre-gl-measures 量测距离面积
在 MapLibre GL JS 中使用 maplibre-gl-measures 插件,可通过绘制线量测距离(长度)、绘制多边形量测面积。该插件支持公制与英制单位、固定单位、自定义样式、数字格式化以及 onRender/onCreate 回调,并提供 TypeScript 定义,安装后用 map.addControl 添加控件即可启用。截至 2026 年 11 月,最新版本为 0.0.21,peerDependencies 要求 maplibre-gl >=2.1.6,已测试兼容至 6.x。使用前必须保证地图 style 包含有效的 glyphs 字体服务,否则测量标签不会显示。

如何安装并添加 maplibre-gl-measures 控件
面向会动手的 GIS 开发者,推荐用包管理器安装,便于锁定版本与类型声明。也可直接用 CDN 快速验证。
- 使用 npm:执行 npm install –save maplibre-gl-measures。
- 使用 yarn:执行 yarn add maplibre-gl-measures。
- CDN 方式:在页面引入 https://unpkg.com/maplibre-gl-measures@0.0.21/dist/maplibre-gl-measures.js(或 @latest),同时确保已引入 MapLibre GL JS 及其 CSS。
- 在地图初始化后添加控件:先创建 map 实例,再执行 map.addControl(new MeasuresControl(), ‘top-left’)。模块写法为 import MeasuresControl from ‘maplibre-gl-measures’;TypeScript 可同时导入 MeasuresControlOptions。
插件内部依赖 @mapbox/mapbox-gl-draw 与 @turf/turf,但默认关闭了 draw 的原生控件并使用自定义按钮与样式,因此通常无需额外引入 mapbox-gl-draw 的 CSS。完整源码、选项说明与更新记录见 maplibre-gl-measures 官方 GitHub 仓库。

常用配置选项与单位选择
构造 MeasuresControl 时可传入选项对象,控制语言、单位系统、小数位数、是否只显示总长以及样式。单位默认 metric,也可固定单一单位或让系统按数值自动缩放。
| 选项 | 说明 | 常用取值/默认 |
|---|---|---|
| units | 单位系统 | ‘metric’(默认)或 ‘imperial’ |
| fixedLengthUnit | 固定长度单位 | mm / cm / m / km / in / ft / yd / mi |
| fixedAreaUnit | 固定面积单位 | mm² / cm² / m² / km² / ha / in² / ft² / yd² / ac / mi² |
| minimumFractionDigits / maximumFractionDigits | 数字小数位 | 按需设置,配合数字格式化 |
| unitsGroupingSeparator | 千分位分隔符 | 字符串,如 ‘,’ |
| showOnlyTotalLineLength | 线测量是否只显示总长 | true(默认) |
| lang | 界面语言 | 按需传入 |
| onRender / onCreate | 渲染与创建回调 | 函数,用于拿到测量结果做后续处理 |
长度与面积计算底层使用 turf.length 与 turf.area。若业务只需要公制且固定用“米/平方公里”,直接设 fixedLengthUnit: ‘m’、fixedAreaUnit: ‘km²’ 即可,避免单位自动跳变带来的阅读成本。
样式自定义与暗黑模式适配
通过 style 对象可精细控制文字、中点、线与面的视觉效果,方便嵌入已有 GIS 系统的配色规范。
- text:radialOffset(默认 0.5)、letterSpacing(0.05)、color(默认 ‘#D20C0C’)、haloColor(’#fff’)、haloWidth(10)、font(默认 ‘Klokantech Noto Sans Bold’)。
- common:中点半径等公共参数。
- lengthMeasurement:线颜色与线宽。
- areaMeasurement:填充色与透明度。
插件支持暗黑模式相关样式调整。测量图层在 0.0.10 及以后版本会置于其他图层之上,避免被底图或业务图层遮挡。自定义完成后,建议在浅色与深色底图各验收一次标签对比度。
必须满足的 glyphs 要求与验收标准
测量结果以文本图层显示,因此地图 style 必须包含 glyphs 属性(指向可用的字体服务),例如指向 OpenMapTiles 或 demotiles.maplibre.org 的字体端点。默认字体为 Klokantech Noto Sans Bold,若字体不匹配或 glyphs 缺失,线/面可以画出来,但距离与面积数字不会出现。
- 检查 style JSON 是否有 “glyphs”: “https://…/{fontstack}/{range}.pbf” 一类配置。
- 确认所用字体栈包含插件默认字体,或在 style 选项里改成你实际提供的字体。
- 本地开发时若使用自托管字体,务必把字体文件放进构建工具的 assets,并保证服务路径正确。
- 验收标准:能成功绘制折线并看到长度标注;能绘制闭合多边形并看到面积标注;切换单位后数值与单位同步更新;回调能拿到正确结果;移除控件后图层与交互干净消失。
版本与依赖细节可对照仓库内的 package.json 文件 核对。
常见问题
测量线/面能画出来,但数字标签不显示怎么办?
绝大多数情况是 style 缺少 glyphs 或字体不匹配。补上正确的 glyphs URL,并确保包含默认字体(或改 style.font),本地项目还要检查 assets 是否把字体文件正确拷贝到可访问路径。
出现 “global is not defined” 报错怎么处理?
部分打包环境(例如某些 Angular 配置)会触发该问题。在入口 HTML 或启动脚本里加一行 var global = global || window; 通常即可解决。
如何确认当前用的是最新版本?
截至 2026 年 11 月,仓库标记的最新版本为 0.0.21。用 npm/yarn 安装时建议显式写版本号,或定期查看 GitHub Releases,避免缓存导致仍停留在旧版。
是否需要单独引入 mapbox-gl-draw 的 CSS?
一般不需要。插件内部使用自定义样式并关闭了 draw 的默认控件,只需保证 MapLibre 自身的 CSS 已正确引入即可。
maplibre-gl-measures 能快速为 MapLibre GL JS 补齐距离与面积量测能力,关键是安装正确版本、配置好 glyphs,再按业务选择单位与样式。建议先在测试地图上完成“能画、能显示数字、能回调”的验收,再接入正式项目;同时把控件位置与配色纳入你们现有的 WebGIS 规范,避免后期反复调整。