做行政区划类的可视化需求我猜你迟早会遇到这样一个效果地图上目标区域高亮显示周围区域被半透明遮罩压暗视觉焦点一下子就落到了目标区域上。这个效果在可视化大屏、政务平台、招商系统里非常常见业内一般叫“掩膜”英文叫 mask。最近我把这套东西用 SpringBoot Leaflet 完整跑了一遍从后端边界数据接口到前端掩膜绘制全都打通了这篇文章就把整个实战过程和踩坑记录整理出来。项目的核心诉求不复杂后端用 SpringBoot 提供行政区划边界数据前端用 Leaflet 渲染地图并通过掩膜把非目标区域压暗。适合正在做地图可视化、需要给行政区划做高亮聚焦的开发者参考无论你是刚开始接触 Leaflet还是已经在项目里集成过地图这篇都能给你一条能直接落地的路子。1. 需求拆解行政区划掩膜到底是个什么效果1.1 先说清楚“掩膜”要解决什么问题很多刚接触地图开发的朋友容易把掩膜理解成“给目标区域加一层高亮蒙版”其实这是两回事。高亮蒙版是做加法在目标区域上面叠一个半透明颜色区域本身变亮掩膜是做减法先在整个地图上盖一层灰色或暗色蒙版然后把目标区域挖空相当于一束聚光灯打下去周边暗、中心亮。从产品视角看这两种方案的观感差异非常大。掩膜让用户不需要刻意寻找目标区域在哪因为周边环境被压暗目标区域自然跳出来。特别是在展示某个地级市或区县的数据时如果只做区域填充周围地图信息太丰富视觉焦点容易被干扰。掩膜相当于帮用户把视线锁死。从实现视角看掩膜的核心不是怎么画“亮”而是怎么画“暗”。你要有一个覆盖整个视口的遮罩形状同时在遮罩上给目标区域挖一个洞。这个“挖洞”操作看起来简单实际涉及几何构造、渲染规则、坐标系对齐这几个关键点任何一个环节不对效果都会翻车。1.2 为什么选 SpringBoot Leaflet而不是重型 GIS 方案我之前见过不少团队为了一个高亮效果把 GeoServer、PostGIS 全上了一遍杀鸡用牛刀。行政区划边界数据本质上就是一个 GeoJSON 文件完全不需要依赖重型 GIS 服务。SpringBoot 在这里的角色是数据服务层负责把边界 GeoJSON 文件读取出来通过 HTTP 接口交给前端。它本身不参与任何地图渲染也不需要做空间计算。选 SpringBoot 的最大理由是团队熟悉、生态成熟和现有的认证、网关、日志体系能无缝对接前端只关心 fetch 拿到 GeoJSON 字符串然后交给 Leaflet 解析。Leaflet 的定位是轻量开源地图库主打 2D Web 地图渲染核心包压缩后大概 40KB 左右。相比 Mapbox GL 需要 WebGL 和小程序服务Leaflet 的 SVG/Canvas 渲染方案在行政区划这种低频更新的场景下完全够用。它的插件生态也很丰富官方提供的 geoJSON 图层方法开箱即用掩膜这种效果不需要额外装复杂插件用原生 API 加自定义逻辑就能实现。1.3 整体数据流与模块划分整个项目的数据流非常清晰我建议你从一开始就按三层拆数据源头行政区划 GeoJSON 文件按层级组织省、市、县放在 SpringBoot 的 resources 目录。后端接口层SpringBoot 提供/api/district/{code}/boundary接口返回标准 GeoJSON。前端渲染层Leaflet 负责加载底图瓦片请求边界数据绘制行政区划图层和掩膜图层。这里有一个容易忽略的设计点边界数据尽量在后端做缓存和压缩不要每次请求都重新读文件。行政区划边界文件少则几十 KB多则数 MB尤其是省级边界数据原始精度可能非常大如果接口不做任何处理前端渲染帧率会被拖垮。这个问题我在第 4 部分会专门展开。2. 边界数据准备与 SpringBoot 接口设计2.1 行政区划边界数据从哪来怎么选这是做行政区划项目第一个绕不开的问题。开发阶段用开源边界数据没问题但上线前一定要换成官方来源或具备审图资质的合规版本。国内项目里常见的数据来源是省市测绘部门发布的标准地图服务、天地图服务以及部分开源社区整理的 GeoJSON 数据。无论用哪种都要确认坐标系、属性字段、边界精度是否满足需求。坐标系的坑非常典型。多数在线底图服务如高德、百度使用的是 GCJ-02 加密坐标系而开源 GeoJSON 边界数据很多是 WGS-84 坐标。如果你的边界数据是 WGS-84直接叠加到 GCJ-02 底图上边界会偏移几百米掩膜看起来就像没对准。最稳妥的做法是统一使用同一个坐标系要么选 WGS-84 底图比如 OSM 瓦片要么在数据接口层做坐标转换。我用的是 OSM 底图加 WGS-84 数据全程不涉及坐标转换省了很多事。数据格式方面一个行政区划的边界最终要变成 GeoJSON 的 Feature。Feature 的 geometry 可以是 Polygon也可以是 MultiPolygon取决于这个区域是不是由多个不连通地块组成。比如带岛屿的行政区划geometry 类型通常是 MultiPolygon。前端掩膜处理必须兼容这两种情况不能假设所有区域都是单个闭合多边形。2.2 后端接口GeoJSON 返回与文件缓存SpringBoot 接口的设计我这里给一个非常简洁但是能直接落地的版本。核心思路是把 GeoJSON 文件作为静态资源管理通过行政区划代码作为入参Service 层做内存缓存避免重复 IO。RestController RequestMapping(/api/district) CrossOrigin(origins *) public class DistrictController { private final DistrictService districtService; public DistrictController(DistrictService districtService) { this.districtService districtService; } GetMapping(value /{code}/boundary, produces application/geojson) public ResponseEntityString getBoundary(PathVariable String code) { String geoJson districtService.loadBoundary(code); if (geoJson null) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok(geoJson); } }Service public class DistrictService { private final MapString, String cache new ConcurrentHashMap(); public String loadBoundary(String code) { return cache.computeIfAbsent(code, this::readFromClasspath); } private String readFromClasspath(String code) { try { Resource resource new ClassPathResource(geojson/ code .json); if (resource.exists()) { return StreamUtils.copyToString(resource.getInputStream(), StandardCharsets.UTF_8); } } catch (IOException e) { log.error(读取边界文件失败: {}, code, e); } return null; } }这个实现有几个细节值得说。computeIfAbsent是线程安全的多用户同时请求同一个行政区划代码时只会有一个线程真正执行文件读取其余的走缓存返回性能压力很小。application/geojson是 GeoJSON 官方建议的 MIME 类型虽然前端用普通application/json也能解析但保持规范可以避免某些网络中间层对响应内容的误判。CrossOrigin是开发期最简单的跨域处理方式项目上线后如果走网关代理这个注解可以去掉。文件目录结构我习惯按行政区划代码组织比如resources/geojson/410100.json一个文件对应一个区域。这样做的好处是接口路径和数据文件一一对应没有额外的路由逻辑。如果你要支持省市区三级下钻也可以把每个层级的边界文件分别放到province/、city/、district/子目录然后在 Service 层加一个层级参数。不过要注意一个市级边界文件可能包含市辖区、县、县级市的边界前端做掩膜的时候用哪个 geometry取决于你要高亮的是整个市还是某一个区。2.3 数据精度与体积控制这里必须强调一下边界数据的抽稀问题。我从开源数据源拿到的某地级市边界原始 GeoJSON坐标点数量超过 4 万文件大小约 3MB。直接用这份数据做前端渲染首次加载会卡顿拖动地图时更是肉眼可见的掉帧。我实际做的时候用 QGIS 里的简化几何工具把容差设为 0.01 度坐标点数量压缩到原来的八分之一文件大小降到 200KB 左右肉眼几乎看不出边界变形。抽稀的容差不能一味往大调。容差太大边界上的弯弯绕绕会被抹平掩膜轮廓看着很“假”容差太小文件体积降不下来。我建议先按 0.005、0.01、0.02 三档分别导出几个版本在真实地图缩放级别下对比效果选择视觉可接受且体积最小的那档。如果产品要求按不同缩放级别展示不同精度的边界那就要借助矢量瓦片或者多级 GeoJSON 方案这个复杂度就上来了本文不展开。3. Leaflet 端的掩膜效果实现3.1 先把地图和行政区划图层加载出来掩膜是在地图上做叠加所以第一步先把底图和行政区划图层铺好。我这里用国内可访问性稳定的 OSM 瓦片服务做演示实际商用项目请替换成合规的底图服务。!-- index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title行政区划掩膜实战/title link relstylesheet hrefhttps://unpkg.com/leaflet1.9.4/dist/leaflet.css / script srchttps://unpkg.com/leaflet1.9.4/dist/leaflet.js/script style #map { width: 100%; height: 600px; } .district-name-label { color: #fff; font-size: 16px; font-weight: bold; text-shadow: 0 1px 3px rgba(0, 0, 0, 0.8); } /style /head body div idmap/div script const map L.map(map).setView([34.5, 113.0], 8); L.tileLayer(https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png, { maxZoom: 18, attribution: copy; OpenStreetMap contributors }).addTo(map); // 行政区划高亮图层 const districtLayer L.geoJSON(null, { style: { color: #2b7de9, weight: 2, fillColor: #2b7de9, fillOpacity: 0.2 } }).addTo(map); // 掩膜图层后面会动态更新 const maskLayer L.geoJSON(null, { interactive: false, style: { fillColor: #0a0a0a, fillOpacity: 0.55, fillRule: evenodd, stroke: false }, renderer: L.svg() }).addTo(map); // 加载行政区划边界 fetch(/api/district/410100/boundary) .then(res res.json()) .then(geojson { districtLayer.addData(geojson); map.fitBounds(districtLayer.getBounds()); updateMask(geojson); }); function updateMask(geojson) { // 掩膜构造逻辑见 3.2 和 3.3 } /script /body /html这里要注意fillRule参数。Leaflet 把 SVG 路径的fill-rule属性暴露成 Path 的 option你可以传evenodd或者nonzero。这是整个掩膜方案能成立的关键。默认情况下 Leaflet 的 Polygon 如果有内环SVG 填充走的是 nonzero 规则也就是看环的绕行方向一不小心内环就被填死了。显式设置为 evenodd 后填充规则与方向无关只与点的命中次数有关掩膜挖洞才能稳定生效。3.2 掩膜核心用 SVG evenodd 规则“挖洞”掩膜的几何构造思路我在开头讲过就是把“整个屏幕范围”和“目标行政区划边界”组合成一个带洞的多边形。GeoJSON 的 Polygon 类型第一个环是外环后面的环都是内环内环在视觉上就是被挖掉的洞。所以我们构造出来的掩膜 GeoJSON Feature 长这样function buildMaskFeature(bounds, districtGeoJson) { // bounds: Leaflet 的 LatLngBounds代表当前视口范围 // 外环覆盖整个视口的矩形 const outerRing [ [bounds.getWest(), bounds.getSouth()], [bounds.getEast(), bounds.getSouth()], [bounds.getEast(), bounds.getNorth()], [bounds.getWest(), bounds.getNorth()], [bounds.getWest(), bounds.getSouth()] ]; // 内环行政区划边界的外环可以有多个 const innerRings extractOuterRings(districtGeoJson); return { type: Feature, properties: { name: mask }, geometry: { type: Polygon, coordinates: [outerRing, ...innerRings] } }; } function extractOuterRings(geojson) { const rings []; const features geojson.type FeatureCollection ? geojson.features : [geojson]; features.forEach(feature { const geom feature.geometry; if (!geom) return; if (geom.type Polygon) { // Polygon 的第一个环是外环可以直接作为掩膜的洞 rings.push(geom.coordinates[0]); } else if (geom.type MultiPolygon) { // MultiPolygon 的每个子多边形都取第一个环作为洞 geom.coordinates.forEach(polygon { rings.push(polygon[0]); }); } }); return rings; }这段代码有几个边界情况要说明。bounds.getWest()和bounds.getSouth()得到的是经纬度坐标要在当前投影下和行政区划边界保持在同一个坐标系里使用否则会出现掩膜偏移。外环的坐标顺序我写了逆时针方向Leaflet 在渲染时对方向没有强校验但 GeoJSON 规范建议外环逆时针、内环顺时针保持规范可以避免后续换 Mapbox 等引擎时出问题。掩膜生成的 GeoJSON 是一个Polygon外环是屏幕矩形内环是一个或多个行政区划外环。这样构造完以后SVG 渲染时 evenodd 规则会自动判断屏幕上某个像素点在矩形内部、同时在行政区划内部时穿过路径的次数是偶数不填充在矩形内部但不在行政区划内部时穿过次数是奇数填充半透明黑色。于是行政区划就像被“挖空”了一样。function updateMask(geojson) { const bounds map.getBounds(); const maskFeature buildMaskFeature(bounds, geojson); maskLayer.clearLayers(); maskLayer.addData(maskFeature); }maskLayer.clearLayers()每次会把之前的掩膜清掉再重新添加。这里不是最优做法因为重复创建 SVG path 会有性能开销但胜在逻辑简单清晰。如果掩膜更新频率很高可以预先创建 feature 然后只更新坐标数组不过我在实战中先保证了正确性再做优化。3.3 动态掩膜随地图移动和缩放实时更新掩膜的外环必须覆盖当前屏幕如果只在地图加载完成后生成一次用户一拖动地图掩膜外环就露馅了。所以必须监听地图的移动和缩放事件在视口变化后重新生成掩膜。map.on(moveend zoomend, () { if (currentDistrict) { updateMask(currentDistrict); } });moveend和zoomend是 Leaflet 提供的事件前者在地图拖动停止后触发后者在缩放动画结束后触发。这里用moveend而不是move是为了避免拖动过程中每帧都去重建掩膜。如果拖动画面的每一帧都更新鼠标拖一下地图就可能触发几十次重建浏览器光是处理 SVG path 重绘就会卡顿。我在实际项目里还遇到过一个问题如果用户快速拖动地图掩膜更新跟不上会出现短暂的空窗期遮罩像被撕开一块。解决方式是额外监听movestart在拖动开始前先把遮罩临时扩展一点比如在原有视口矩形基础上外扩 10%这样快速拖动的过程中遮罩不会提前暴露边界。等稳定后再恢复精确矩形。不过这个技巧要看产品对细节的容忍度我做过一个数据大屏项目用户都是固定视角看根本没有拖动需求那我连moveend监听都可以省掉只保留缩放时更新。3.4 锦上添花高亮描边、标签和过渡动画掩膜把视觉焦点聚到目标区域之后高亮区域本身还可以再做几层美化。我在这个项目里加了三个小功能行政区划描边颜色加深。掩膜把周边压暗后区域边界如果还用细线容易被暗色盖住。我把districtLayer的描边权重从默认的 2 提高到 3颜色改成橙色系和蓝色填充形成暖冷对比。实测下来视觉层次比单一蓝色好很多。加一个行政区划名称标签。用 Leaflet 的L.tooltip或者L.marker都可以关键是别加到图层里面去不然掩膜的 zoom 动画会连标签一起闪。我选择在districtLayer的每个 feature bindTooltip并开启permanent模式配合 CSS 文字阴影标签在暗色遮罩上依然清晰。平滑过渡效果。直接切换掩膜的透明度会显得突兀。我给 SVG path 加了 CSS transition让fill-opacity在 300ms 内渐变。SVG 元素属于 DOMCSS 过渡对它是生效的。有朋友问 Canvas 渲染器能不能也做过渡Canvas 是无状态的没有现成 DOM 元素可以挂 CSS只能通过 requestAnimationFrame 逐帧改透明度复杂度高不少。这也是我为什么推荐小数据量场景优先用 SVG 方案。4. 调试实录与高频问题排查4.1 掩膜偏移、边界对不上先查坐标系这是我在做掩膜时踩的最大的坑。第一次完成掩膜编码后刷新页面发现遮罩的黑洞和高亮区域明显错位黑洞偏到了区域外面整个效果看起来像是“眼神不好没对准”。排查步骤我帮你整理一下。第一步先看底图服务用的坐标系。OSM 是 WGS-84高德是 GCJ-02百度是 BD-09同一个经纬度在不同坐标系下可以偏差几百米。第二步看边界 GeoJSON 文件里的坐标范围和底图是否契合。可以打印出边界数据的第一个坐标点再到地图上手动打一个 marker 对比位置。第三步如果确认数据是 GCJ-02 而底图是 WGS-84不要自己写转换算法直接引入成熟的坐标转换库。新手很容易在这里浪费时间。我的最终方案是统一采用 WGS-84 OSM 底图。这样后端和前端都不用碰坐标转换。如果你的业务强制用高德底图那就要在服务端或前端做 GCJ-02 偏移修正修复之后掩膜同步问题会自动消失。4.2 掩膜边缘出现白边或细缝SVG 渲染的掩膜和高亮区域中间有时会出现一条白色细缝尤其是放大到较高缩放级别时。原因是掩膜的挖洞边界和高亮区域的边界是两条独立的 SVG path两个图层的抗锯齿像素不完全一致中间就会露出底图的颜色。几个对策我都试过比较有效的是给掩膜的内环边界加上一条和遮罩同一颜色的描边。也就是说掩膜的stroke不要设置成false而是设成和fillColor相同的颜色weight设为 1。这样内环边缘即使有抗锯齿也会被描边颜色覆盖白边自然消失。另一种做法是把高亮区域描边向外扩一点点比如权重 3让高亮边界盖住掩膜边界也能消除细缝。两个方法结合使用效果最好。4.3 掩膜区域是死板矩形动态更新跟不上快速拖动前面提到的动态掩膜方案外环是用当前视口矩形构造的。如果用户进行惯性拖动moveend触发前会有短暂延迟遮罩矩形可能落后于视口屏幕边缘会露出没有被遮挡的区域。我后来给掩膜外环做了缓冲扩展。每次取map.getBounds()之后不直接拿原始范围生成矩形而是先调用bounds.pad(0.1)把视口外扩 10%。这样即使发生了短暂的拖动延迟外扩部分也能兜住屏幕边缘。等moveend触发后再重新精确计算。4.4 区域边界复杂时渲染卡顿行政区划边界如果抽稀不足比如一个省的边界包含几万个坐标点SVG 渲染器每次更新掩膜都要重建一个巨大的 path浏览器会卡到怀疑人生。这个我在第 2 部分提过数据侧一定要抽稀。如果抽稀之后还是卡可以把 Leaflet 的渲染器从默认的 SVG 换成 Canvas。L.geoJSON(null, { renderer: L.canvas(), style: { ... } });Canvas 渲染器处理大量坐标点时性能远好于 SVG因为最终绘制是直接画在画布上不用维护大量 DOM 节点。但 Canvas 的缺点是遮罩区域不可选中、样式调起来不如 SVG 直观做临时调试的时候还是 SVG 方便。我建议上线前再切 Canvas开发期保持 SVG。另外还有一个容易被忽略的点后端返回的 GeoJSON 如果没开 Gzip 压缩3MB 的文件在本地调试看不出来部署到公网服务器后加载耗时能到几秒。SpringBoot 默认没开启 Gzip需要在application.yml里配置响应的压缩或者在前端 Nginx 层开启。配置方式不复杂值得提前做。4.5 高频问题速查表我把调试过程中积累的问题整理成一个表格方便你以后遇到类似情况快速定位。现象可能原因排查与解决掩膜黑洞和行政区划错位坐标系不一致确认底图服务坐标系统一 WGS-84 或统一转换掩膜周围有白边SVG 抗锯齿导致掩膜内环加同色描边或高亮图层描边向外扩拖动地图时遮罩边缘露馅外环矩形未覆盖新视口监听 moveend使用 bounds.pad(0.1) 外扩掩膜更新频繁页面卡顿用了 move 事件更新改为 moveend zoomend减少重建次数边界数据加载慢数据精度太高/未压缩抽稀边界数据开启 Gzip 压缩掩膜层挡住了地图操作interactive 未关闭掩膜图层设置 interactive: false带洞/飞地区域挖洞异常只取了 Polygon 外环处理 MultiPolygon 和多个内环的情况Cursor 绘制掩膜时还有一个细节要提醒掩膜图层最好放在 overlayPane 的最底层也就是先 add 掩膜图层再 add 行政区划图层保证行政区划永远在掩膜上方。如果顺序反了行政区划会被半透明遮罩盖住高亮效果就废了。5. 一点个人体会掩膜这个效果代码量不大核心逻辑就是我上面写的“矩形 行政区划内环 evenodd 填充规则”。做行政区划可视化这些年我的体会是真正决定项目成败的往往不是前端炫技而是边界数据是否合规、坐标系是否统一、大数据量下的性能是否达标。SVG 方案适合单区域或少量区域的场景上手快、调试直观Canvas 方案适合大量区域和频繁交互的场景性能更稳。最后再分享一个小技巧调试掩膜时把fillOpacity临时调到 0.9遮罩颜色加深后边界是否对齐、是否有白边会看得非常清楚。调试完再恢复成 0.5 左右的正式值。我每次做地图遮罩都会先这样排查一轮省了不少定位问题的时间。