Leaflet 底图切换与图层控制

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

在 Leaflet 里做底图切换和图层控制,核心就是用 Layers 控件:把互斥的底图放进 baseLayers、可开关的叠加层放进 overlays,再 addTo(map)。初始化时只把其中一个底图加到地图上,其余底图只登记在控件对象里,控件会自动用单选/复选框同步状态。截至 2026 年 11 月,生产环境仍建议用稳定版 1.9.4;2.0 刚进入 beta,类名和写法有调整,新项目可对照官方迁移说明再决定是否跟进。

图层控制面板示意:底图互斥、叠加层可多选

底图和叠加层分别管什么

先分清两类图层,后面写代码才不会乱。

  • Base layers(底图):同一时间只能显示一张,控件里用单选按钮。常见是各种 TileLayer(街道、影像、地形)。
  • Overlays(叠加层):彼此独立,可同时开多个,控件里用复选框。常见是 Marker、GeoJSON、把多个标记包在一起的 LayerGroup。

创建控件时,第一个参数是底图对象,第二个是叠加层对象;键是控件上显示的名称,值必须是已经创建好的 Layer 实例。只做叠加层、没有底图时,第一个参数传 null。多个底图时,地图初始化只应 addTo 其中一个;所有要出现在控件里的底图都必须放进 baseLayers 对象,否则单选状态会对不上。

把多个 Marker 合成一个可整体开关的图层,用 LayerGroup:1.x 写作 L.layerGroup([marker1, marker2]),2.0 写作 new LayerGroup([…])。整组作为一个 overlay 登记即可,不必在控件里逐个列标记。

一步步加上图层控制

下面按 1.9.4 稳定版写法给出可执行步骤(页面已有带高度的地图容器、已引入 Leaflet CSS/JS 的前提下)。官方示例思路可参考 Leaflet 图层控制示例源码。

  1. 分别创建各个底图的 TileLayer 实例(建议都写上 attribution、maxZoom),只把默认那一张 addTo(map)。
  2. 需要的话创建叠加层:单个 Marker、LayerGroup 或 GeoJSON,需要默认显示的再 addTo(map)。
  3. 组装两个普通对象,例如 baseMaps = { “街道”: streets, “影像”: satellite },overlays = { “标注”: markers }。键可含简单 HTML 做样式,但别堆复杂结构。
  4. 调用 L.control.layers(baseMaps, overlays).addTo(map)(若只有叠加层则 L.control.layers(null, overlays))。
  5. 在浏览器里点开右上角图层图标:底图应是单选且默认项已勾上,叠加层是复选;切换底图时旧底图消失、新底图出现,勾选叠加层时对应要素显隐正常,即算通过。

2.0 beta 里工厂函数已去掉,应写成 new LayersControl(baseLayers, overlays).addTo(map),并从 leaflet 按需 import。若要从 1.x 迁过去,以 官方 1.x 到 2.0 迁移指南 为准,不要混用两套 API。

GitHub 上 Leaflet 官方图层控制示例文档页
GitHub 上 Leaflet 官方图层控制示例文档页(截图来源:github.com)

控件选项、事件和动态增删

默认折叠成图标、放在右上角,一般够用。需要改交互时再动选项。

选项 / 能力 说明(1.9.4) 使用注意
collapsed 默认 true,折叠为图标 列表很长或演示时可以设 false
position 默认 topright 可选 topleft / bottomleft / bottomright
hideSingleBase 默认 false 只有一个底图时设 true 可隐藏底图区
autoZIndex 默认 true 自动抬升 zIndex,保持切换顺序
addBaseLayer / addOverlay 创建后追加图层 传入已有 Layer 实例和显示名
removeLayer 从控件移除登记 不等于从地图上 remove;两边要分开处理

2.0 还增加了 title(按钮与无障碍标签,默认 Layers)和 collapseDelay(折叠延迟,方便滚长列表)。版本与发布说明见 Leaflet 官方 Releases 页面。

需要在切换时做联动(改图例、请求数据、记日志)时,监听地图事件即可:

  • baselayerchange:底图切换完成
  • overlayadd / overlayremove:叠加层被勾选或取消

事件对象里通常带有 name 和 layer,便于判断是哪一层。动态场景下,也可以先 map.addLayer(layer),再 control.addOverlay(layer, name);若图层实例本来就在控件登记里,仅 addLayer/removeLayer 也会让勾选状态跟着变。

容易踩的坑和怎么验收

图层控制出问题,多半不是 API 记错,而是「实例不一致」或「初始化加多了底图」。

  • 默认底图在控件里没被选中:必须把同一个 Layer 实例既 addTo(map) 又放进 baseMaps。又 L.tileLayer(…) 一次等于新实例,控件对不上,单选会空着或错位。
  • 一上来加了多张底图:只 add 默认那张;其它只出现在 baseMaps 里。多张同时 add,控件状态和显示都会乱。
  • Provider / 封装库又包了一层:确认最终塞进控件的仍是那一个实例引用,不要在封装函数里每次返回新对象却指望状态同步。
  • 移动端误触:1.9.4 已修过 Layers 控制在移动端的误触切换;若你还在更旧版本,优先升到 1.9.4 再排查业务逻辑。

验收可以按这几条过一遍:默认底图单选已勾;切换底图时屏幕上只剩一张底图;叠加层勾选/取消与地图内容一致;刷新页面后默认状态可复现;在窄屏或触摸设备上展开/折叠控件不误切底图。

常见问题

只有叠加层、没有底图切换,控件怎么写?

第一个参数传 null,第二个传 overlays 对象,例如 L.control.layers(null, overlays).addTo(map)。这样控件里只有复选框,没有底图单选区。

能不能初始化时让多个叠加层默认打开?

可以。把需要默认显示的叠加层在创建地图时一并 addTo(map)(或之后立刻 add),同时把它们登记进 overlays;控件会检测已在地图上的图层并勾上对应复选框。

现在该用 1.9.4 还是 2.0?

做正式项目、要稳,继续用 1.9.4。2.0 在 2026 年 11 月初刚发 beta,教程和 API 已偏 2.0 风格,但尚未当稳定版用;跟进前先读迁移指南,并在目标浏览器(Baseline 2022,如 Safari 15.4+)上测图层控件与瓦片行为。

控件折叠后找不到、或样式错乱怎么办?

先确认 Leaflet CSS 已正确引入,且地图容器有明确高度。折叠按钮依赖控件自带的 layers 图标资源;若图标 404,检查 CSS 同目录下的 images,或构建工具是否漏拷静态资源。再检查是否有全局 CSS 把 .leaflet-control-layers 的定位或 z-index 盖掉了。

总结:用 Layers 控件区分底图(互斥)和叠加层(可多选),初始化只挂一张底图、全程复用同一 Layer 实例,再按需配置折叠、位置和动态增删。建议先在 1.9.4 上把切换与勾选验收跑通,需要跟 2.0 时再按官方迁移指南改成 LayersControl 类写法,避免混用两套 API。