企业官网建设流程全解析

Leaflet 图层分组与 LayersControl 图层切换控件实战指南

【免费下载链接】Leaflet🍃 JavaScript library for mobile-friendly interactive maps 🇺🇦项目地址: https://gitcode.com/gh_mirrors/le/Leaflet

本篇教程基于 Leaflet 官方示例「Layer Groups and Layers Control」（源文档位于 docs/examples/layers-control/index.md，配套可运行示例见 docs/examples/layers-control/example.md），系统讲解如何用LayerGroup把多个图层打包为一个整体，以及如何用LayersControl让用户在地图上自由切换互斥的底图、开关叠加图层。读完本文，你将能组合任意数量图层、搭建带单选/复选的图层管理面板，并在运行时动态增删图层条目。

两种图层类型：互斥的底图与可叠加的 Overlay

Leaflet 将图层划分为两大类，这也是 LayersControl 交互模型的基础：

1. 基础图层（base layer）：彼此互斥，同一时刻地图上只能显示一张。典型代表是瓦片底图（TileLayer），如 OpenStreetMap、卫星影像、地形图。LayersControl 中基础图层以**单选按钮（radio）**呈现。
2. 叠加图层（overlay）：叠加在底图之上的其余一切，如标记、折线、多边形，可以同时开启多个。LayersControl 中叠加图层以**复选框（checkbox）**呈现。

这一设计在源码中直接可见：在 src/control/LayersControl.js 的_addItem方法里，控件根据图层是否属于 overlay 创建不同类型的<input>元素：

input.type = obj.overlay ? 'checkbox' : 'radio';

用 LayerGroup 把多个图层打包成一组

假设你有一批城市标记，每个都绑定了弹窗：

const littleton = new Marker([39.61, -105.02]).bindPopup('This is Littleton, CO.'), denver = new Marker([39.74, -104.99]).bindPopup('This is Denver, CO.'), aurora = new Marker([39.73, -104.8]).bindPopup('This is Aurora, CO.'), golden = new Marker([39.77, -105.23]).bindPopup('This is Golden, CO.');

与其把四个标记逐个addTo(map)，不如用LayerGroup将它们收拢为一个整体：

const cities = new LayerGroup([littleton, denver, aurora, golden]);

现在cities就是一个可整体操作的图层：加入地图、移出地图都只需一步。从 src/layer/LayerGroup.js 的实现看，LayerGroup内部用_layers对象持有子图层，addLayer/removeLayer会同步反映到地图上（onAdd遍历调用map.addLayer，onRemove遍历调用map.removeLayer），因此往已在地图上的分组里动态添加/移除子图层，地图会立即跟随变化。分组还提供hasLayer、clearLayers、eachLayer、getLayers等管理方法，以及setZIndex批量设置层级。

创建底图与叠加图层

接下来准备两张可切换的底图（OpenStreetMap 标准版与 HOT 人道主义样式），并把osm作为默认底图、cities作为默认叠加层放进地图初始化参数：

const osm = new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 19, attribution: '&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>' }); const osmHOT = new TileLayer('https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png', { maxZoom: 19, attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, Tiles style by <a href="https://www.hotosm.org/" target="_blank">Humanitarian OpenStreetMap Team</a> hosted by <a href="https://openstreetmap.fr/" target="_blank">OpenStreetMap France</a>' }); const map = new LeafletMap('map', { center: [39.73, -104.99], zoom: 10, layers: [osm, cities] });

构造 LayersControl 并接入地图

LayersControl 通过两个普通对象（key/value）接收图层：key 是控件中显示的文本，value 是对应的图层引用。底图对象与叠加对象分别传入构造函数的第一个和第二个参数：

const baseMaps = { "OpenStreetMap": osm, "OpenStreetMap.HOT": osmHOT }; const overlayMaps = { "Cities": cities }; const layerControl = new LayersControl(baseMaps, overlayMaps).addTo(map);

两个参数都是可选的：可以只传底图对象（省略第二个参数），也可以只传叠加对象（第一个参数传null）。被省略的图层类型不会出现在控件中供用户选择——这一点在 src/control/LayersControl.js 的构造函数中通过Object.entries(baseLayers ?? {})与Object.entries(overlays ?? {})的空值兜底实现。

两个必须遵守的约定

• 实例化地图时我们只添加了osm和cities，并未添加osmHOT。LayersControl 足够“聪明”，会自动检测哪些图层已在图上，并据此初始化复选框与单选按钮的选中状态——对应源码 src/control/LayersControl.js 中checked = this._map.hasLayer(obj.layer)的判断逻辑。
• 使用多个底图时，实例化阶段只应向地图添加其中一个，但创建控件时所有底图都必须放进底图对象。否则多张底图会同时显示，破坏互斥语义。

图层名的样式定制

图层名中可以直接嵌入 HTML，实现富文本样式。例如让 “OpenStreetMap.HOT” 显示为红色：

const baseMaps = { "OpenStreetMap": osm, "<span style='color: red'>OpenStreetMap.HOT</span>": osmHOT };

源码注释中同样给出了更复杂的用法，例如在名称前插入图标图片与自定义样式类：

{"<img src='my-layer-icon' /> <span class='my-layer-item'>My Layer</span>": myLayer}

因为名称通过name.innerHTML = ' ' + obj.name（见 src/control/LayersControl.js）渲染，所以 HTML 会被原样解析。

动态增删图层条目

控件创建之后，仍可通过addBaseLayer/addOverlay/removeLayer在运行时增删条目。下面的代码新增了一张地形底图和一个公园标记分组：

const crownHill = new Marker([39.75, -105.09]).bindPopup('This is Crown Hill Park.'), rubyHill = new Marker([39.68, -105.00]).bindPopup('This is Ruby Hill Park.'); const parks = new LayerGroup([crownHill, rubyHill]); const openTopoMap = new TileLayer('https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png', { maxZoom: 19, attribution: 'Map data: &copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, <a href="http://viewfinderpanoramas.org">SRTM</a> | Map style: &copy; <a href="https://opentopomap.org">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>)' }); layerControl.addBaseLayer(openTopoMap, "OpenTopoMap"); layerControl.addOverlay(parks, "Parks");

这些方法与LayersControl源码中定义的方法一一对应（src/control/LayersControl.js）：addBaseLayer将图层以非 overlay 身份登记并触发_update()重绘，addOverlay则登记为 overlay，removeLayer从内部_layers数组中移除对应条目。完成后的完整效果可参考 docs/examples/layers-control/example.md 中对应的可运行脚本。

控件选项与展开/收起行为

LayersControl继承自Control，其默认选项定义在 src/control/LayersControl.js，常用选项如下：

展开行为（expand/collapse，见 src/control/LayersControl.js）有几点值得注意：面板超出地图高度时自动出现滚动条（leaflet-control-layers-scrollbar）；在触摸设备上点击复选框时不会因pointerout误触发折叠；collapsed: false时面板常驻显示。折叠图标的默认样式与图层面板的布局（白底圆角、分割线、触摸态放大到 44px 等）定义在 src/leaflet.css。

源码层面：控件如何响应切换操作

当用户点击单选按钮或复选框时，_onInputClick遍历控件登记的全部输入框，先移除所有未勾选且已在图上的图层，再添加所有勾选但不在图上的图层（先移除后添加的顺序修正了历史 issue 中旧底图残留的问题）。这一过程中会通过_handlingClick标志抑制重复的_update()刷新。

同时，控件监听每个登记图层的add/remove事件（_onLayerChange），并在地图上触发三个对外事件：

• baselayerchange：通过控件切换底图时触发；
• overlayadd：通过控件开启叠加图层时触发；
• overlayremove：通过控件关闭叠加图层时触发。

外部代码可以监听这些事件实现联动（例如切换底图后同步更新图例）。此外，_checkDisabledLayers（src/control/LayersControl.js）会根据图层自身的minZoom/maxZoom与当前缩放级别，自动禁用超出缩放范围的选项。

行为验证：来自测试套件的证据

仓库测试 spec/suites/control/LayersControlSpec.js 对上述行为做了系统验证，可作为你使用时的行为参考：

• baselayerchange事件：点击不同底图单选按钮分别触发事件，且事件对象携带name与layer字段；点击 overlay 复选框不会误触发底图切换事件；控件从地图移除再重新添加后事件监听依然有效。
• 状态同步：当登记过的图层被map.addLayer/map.removeLayer时，对应复选框自动勾选/取消；未登记的图层增删不会触发控件刷新。
• removeLayer语义：从控件移除 overlay 后，面板中对应条目消失；移除不存在的图层时静默返回、不抛错。
• 折叠行为：collapsed: true时支持鼠标悬停、点击、键盘Enter展开，点击地图空白处或移出鼠标后收起，collapseDelay生效；collapsed: false时面板常驻，图层过多时自动出现滚动条。
• 排序：默认保持添加顺序；sortLayers: true时按名称字母序；也可传入自定义sortFunction按任意属性（如options.customOption）排序。
• 图层复用：同一图层出现在多个条目中（如重复底图）时，切换逻辑保持正确。

小结

通过LayerGroup与LayersControl的组合，你可以用极少代码实现一个完整的图层管理体系：底图用单选互斥切换、叠加层用复选框自由开关、控件状态随地图自动同步、面板在折叠与滚动之间自适应。从 src/control/LayersControl.js 与 src/layer/LayerGroup.js 的实现可见，整个体系建立在 Leaflet 统一的事件机制（add/remove事件）之上，这也意味着任何自定义图层只要遵循该事件约定，就能无缝接入图层控件。更多 API 细节可查阅 参考文档（LayerGroup见 docs/reference.html#layergroup）。

【免费下载链接】Leaflet🍃 JavaScript library for mobile-friendly interactive maps 🇺🇦项目地址: https://gitcode.com/gh_mirrors/le/Leaflet