MapLibre GL JS 用 maplibre-gl-measures 量测距离面积

编程与开发
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

在 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 在 MapLibre 地图上量测距离与面积的效果示意

如何安装并添加 maplibre-gl-measures 控件

面向会动手的 GIS 开发者,推荐用包管理器安装,便于锁定版本与类型声明。也可直接用 CDN 快速验证。

  1. 使用 npm:执行 npm install –save maplibre-gl-measures。
  2. 使用 yarn:执行 yarn add maplibre-gl-measures。
  3. CDN 方式:在页面引入 https://unpkg.com/maplibre-gl-measures@0.0.21/dist/maplibre-gl-measures.js(或 @latest),同时确保已引入 MapLibre GL JS 及其 CSS。
  4. 在地图初始化后添加控件:先创建 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 仓库。

maplibre-gl-measures 的 GitHub 仓库主页截图
maplibre-gl-measures 的 GitHub 仓库主页截图(截图来源:github.com)

常用配置选项与单位选择

构造 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 缺失,线/面可以画出来,但距离与面积数字不会出现。

  1. 检查 style JSON 是否有 “glyphs”: “https://…/{fontstack}/{range}.pbf” 一类配置。
  2. 确认所用字体栈包含插件默认字体,或在 style 选项里改成你实际提供的字体。
  3. 本地开发时若使用自托管字体,务必把字体文件放进构建工具的 assets,并保证服务路径正确。
  4. 验收标准:能成功绘制折线并看到长度标注;能绘制闭合多边形并看到面积标注;切换单位后数值与单位同步更新;回调能拿到正确结果;移除控件后图层与交互干净消失。

版本与依赖细节可对照仓库内的 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 规范,避免后期反复调整。