源码分析之Leaflet图层控制控件Control.Layers实现原理

概述

本文将先容Leaflet库中最后一个组件，即图层控制组件 Control.Layers。
源码实现

1. export var Layers = Control.extend({
2.   options: {
3.     collapsed: true,
4.     position: "topright",
5.     autoZIndex: true,
6.     hideSingleBase: false,
7.     sortLayers: false,
8.     sortFunction: function (layerA, layerB, nameA, nameB) {
9.       return nameA < nameB ? -1 : nameB < nameA ? 1 : 0;
10.     },
11.   },
12.   initialize: function (baseLayers, overlays, options) {
13.     Util.setOptions(this, options);
15.     this._layerControlInputs = [];
16.     this._layers = [];
17.     this._lastZIndex = 0;
18.     this._handlingClick = false;
19.     this._preventClick = false;
21.     for (var i in baseLayers) {
22.       this._addLayer(baseLayers[i], i);
23.     }
25.     for (i in overlays) {
26.       this._addLayer(overlays[i], i, true);
27.     }
28.   },
29.   onAdd: function (map) {
30.     this._initLayout();
31.     this._update();
33.     this._map = map;
34.     map.on("zoomend", this._checkDisabledLayers, this);
36.     for (var i = 0; i < this._layers.length; i++) {
37.       this._layers[i].layer.on("add remove", this._onLayerChange, this);
38.     }
40.     return this._container;
41.   },
42.   addTo: function (map) {
43.     Control.prototype.addTo.call(this, map);
44.     return this._expandIfNotCollapsed();
45.   },
46.   onRemove: function () {
47.     this._map.off("zoomend", this._checkDisabledLayers, this);
49.     for (var i = 0; i < this._layers.length; i++) {
50.       this._layers[i].layer.off("add remove", this._onLayerChange, this);
51.     }
52.   },
53.   addBaseLayer: function (layer, name) {
54.     this._addLayer(layer, name);
55.     return this._map ? this._update() : this;
56.   },
57.   addOverlay: function (layer, name) {
58.     this._addLayer(layer, name, true);
59.     return this._map ? this._update() : this;
60.   },
61.   removeLayer: function (layer) {
62.     layer.off("add remove", this._onLayerChange, this);
64.     var obj = this._getLayer(Util.stamp(layer));
65.     if (obj) {
66.       this._layers.splice(this._layers.indexOf(obj), 1);
67.     }
68.     return this._map ? this._update() : this;
69.   },
70.   expand: function () {
71.     DomUtil.addClass(this._container, "leaflet-control-layers-expanded");
72.     this._section.style.height = null;
73.     var acceptableHeight =
74.       this._map.getSize().y - (this._container.offsetTop + 50);
75.     if (acceptableHeight < this._section.clientHeight) {
76.       DomUtil.addClass(this._section, "leaflet-control-layers-scrollbar");
77.       this._section.style.height = acceptableHeight + "px";
78.     } else {
79.       DomUtil.removeClass(this._section, "leaflet-control-layers-scrollbar");
80.     }
81.     this._checkDisabledLayers();
82.     return this;
83.   },
84.   collapse: function () {
85.     DomUtil.removeClass(this._container, "leaflet-control-layers-expanded");
86.     return this;
87.   },
89.   _initLayout: function () {
90.     var className = "leaflet-control-layers",
91.       container = (this._container = DomUtil.create("div", className)),
92.       collapsed = this.options.collapsed;
94.     container.setAttribute("aria-haspopup", true);
96.     DomEvent.disableClickPropagation(container);
97.     DomEvent.disableScrollPropagation(container);
99.     var section = (this._section = DomUtil.create(
100.       "section",
101.       className + "-list"
102.     ));
104.     if (collapsed) {
105.       this._map.on("click", this.collapse, this);
107.       DomEvent.on(
108.         container,
109.         {
110.           mouseenter: this._expandSafely,
111.           mouseleave: this.collapse,
112.         },
113.         this
114.       );
115.     }
117.     var link = (this._layersLink = DomUtil.create(
118.       "a",
119.       className + "-toggle",
120.       container
121.     ));
122.     link.href = "#";
123.     link.title = "Layers";
124.     link.setAttribute("role", "button");
126.     DomEvent.on(
127.       link,
128.       {
129.         keydown: function (e) {
130.           if (e.keyCode === 13) {
131.             this._expandSafely();
132.           }
133.         },
134.         click: function (e) {
135.           DomEvent.preventDefault(e);
136.           this._expandSafely();
137.         },
138.       },
139.       this
140.     );
142.     if (!collapsed) {
143.       this.expand();
144.     }
146.     this._baseLayersList = DomUtil.create("div", className + "-base", section);
147.     this._separator = DomUtil.create("div", className + "-separator", section);
148.     this._overlaysList = DomUtil.create(
149.       "div",
150.       className + "-overlays",
151.       section
152.     );
154.     container.appendChild(section);
155.   },
156.   _getLayer: function (id) {
157.     for (var i = 0; i < this._layers.length; i++) {
158.       if (this._layers[i] && Util.stamp(this._layers[i].layer) === id) {
159.         return this._layers[i];
160.       }
161.     }
162.   },
163.   _addLayer: function (layer, name, overlay) {
164.     if (this._map) {
165.       layer.on("add remove", this._onLayerChange, this);
166.     }
168.     this._layers.push({
169.       layer: layer,
170.       name: name,
171.       overlay: overlay,
172.     });
174.     if (this.options.sortLayers) {
175.       this._layers.sort(
176.         Util.bind(function (a, b) {
177.           return this.options.sortFunction(a.layer, b.layer, a.name, b.name);
178.         }, this)
179.       );
180.     }
182.     if (this.options.autoZIndex && layer.setZIndex) {
183.       this._lastZIndex++;
184.       layer.setZIndex(this._lastZIndex);
185.     }
187.     this._expandIfNotCollapsed();
188.   },
190.   _update: function () {
191.     if (!this._container) {
192.       return this;
193.     }
195.     DomUtil.empty(this._baseLayersList);
196.     DomUtil.empty(this._overlaysList);
198.     this._layerControlInputs = [];
199.     var baseLayersPresent,
200.       overlaysPresent,
201.       i,
202.       obj,
203.       baseLayersCount = 0;
205.     for (i = 0; i < this._layers.length; i++) {
206.       obj = this._layers[i];
207.       this._addItem(obj);
208.       overlaysPresent = overlaysPresent || obj.overlay;
209.       baseLayersPresent = baseLayersPresent || !obj.overlay;
210.       baseLayersCount += !obj.overlay ? 1 : 0;
211.     }
213.     if (this.options.hideSingleBase) {
214.       baseLayersPresent = baseLayersPresent && baseLayersCount > 1;
215.       this._baseLayersList.style.display = baseLayersPresent ? "" : "none";
216.     }
218.     this._separator.style.display =
219.       overlaysPresent && baseLayersPresent ? "" : "none";
221.     return this;
222.   },
223.   _onLayerChange: function (e) {
224.     if (!this._handlingClick) {
225.       this._update();
226.     }
228.     var obj = this._getLayer(Util.stamp(e.target));
229.     var type = obj.overlay
230.       ? e.type === "add"
231.         ? "overlayadd"
232.         : "overlayremove"
233.       : e.type === "add"
234.       ? "baselayerchange"
235.       : null;
237.     if (type) {
238.       this._map.fire(type, obj);
239.     }
240.   },
241.   _createRadioElement: function (name, checked) {
242.     var radioHtml =
243.       '<input type="radio" class="leaflet-control-layers-selector" name="' +
244.       name +
245.       '"' +
246.       (checked ? ' checked="checked"' : "") +
247.       "/>";
249.     var radioFragment = document.createElement("div");
250.     radioFragment.innerHTML = radioHtml;
252.     return radioFragment.firstChild;
253.   },
254.   _addItem: function (obj) {
255.     var label = document.createElement("label"),
256.       checked = this._map.hasLayer(obj.layer),
257.       input;
259.     if (obj.overlay) {
260.       input = document.createElement("input");
261.       input.type = "checkbox";
262.       input.className = "leaflet-control-layers-selector";
263.       input.defaultChecked = checked;
264.     } else {
265.       input = this._createRadioElement(
266.         "leaflet-base-layers_" + Util.stamp(this),
267.         checked
268.       );
269.     }
271.     this._layerControlInputs.push(input);
272.     input.layerId = Util.stamp(obj.layer);
274.     DomEvent.on(input, "click", this._onInputClick, this);
276.     var name = document.createElement("span");
277.     name.innerHTML = " " + obj.name;
279.     var holder = document.createElement("span");
281.     label.appendChild(holder);
282.     holder.appendChild(input);
283.     holder.appendChild(name);
285.     var container = obj.overlay ? this._overlaysList : this._baseLayersList;
286.     container.appendChild(label);
288.     this._checkDisabledLayers();
289.     return label;
290.   },
291.   _onInputClick: function () {
292.     if (this._preventClick) {
293.       return;
294.     }
296.     var inputs = this._layerControlInputs,
297.       input,
298.       layer;
299.     var addedLayers = [],
300.       removedLayers = [];
302.     this._handlingClick = true;
304.     for (var i = inputs.length - 1; i >= 0; i--) {
305.       input = inputs[i];
306.       layer = this._getLayer(input.layerId).layer;
308.       if (input.checked) {
309.         addedLayers.push(layer);
310.       } else if (!input.checked) {
311.         removedLayers.push(layer);
312.       }
313.     }
314.     for (i = 0; i < removedLayers.length; i++) {
315.       if (this._map.hasLayer(removedLayers[i])) {
316.         this._map.removeLayer(removedLayers[i]);
317.       }
318.     }
319.     for (i = 0; i < addedLayers.length; i++) {
320.       if (!this._map.hasLayer(addedLayers[i])) {
321.         this._map.addLayer(addedLayers[i]);
322.       }
323.     }
325.     this._handlingClick = false;
327.     this._refocusOnMap();
328.   },
330.   _checkDisabledLayers: function () {
331.     var inputs = this._layerControlInputs,
332.       input,
333.       layer,
334.       zoom = this._map.getZoom();
336.     for (var i = inputs.length - 1; i >= 0; i--) {
337.       input = inputs[i];
338.       layer = this._getLayer(input.layerId).layer;
339.       input.disabled =
340.         (layer.options.minZoom !== undefined && zoom < layer.options.minZoom) ||
341.         (layer.options.maxZoom !== undefined && zoom > layer.options.maxZoom);
342.     }
343.   },
345.   _expandIfNotCollapsed: function () {
346.     if (this._map && !this.options.collapsed) {
347.       this.expand();
348.     }
349.     return this;
350.   },
352.   _expandSafely: function () {
353.     var section = this._section;
354.     this._preventClick = true;
355.     DomEvent.on(section, "click", DomEvent.preventDefault);
356.     this.expand();
357.     var that = this;
358.     setTimeout(function () {
359.       DomEvent.off(section, "click", DomEvent.preventDefault);
360.       that._preventClick = false;
361.     });
362.   },
363. });
365. export var layers = function (baseLayers, overlays, options) {
366.   return new Layers(baseLayers, overlays, options);
367. };

复制代码

核心结构

1. export var Layers = Control.extend({...});
2. export var layers = function (...) { return new Layers(...) };

复制代码

• 继续自 Leaflet 的 Control 基类，实现图层控制功能。
  
• 提供工厂函数 layers() 简化实例化操作。
  

---

配置项 (options)

1. options: {
2.   collapsed: true,          // 默认折叠
3.   position: "topright",     // 控件位置
4.   autoZIndex: true,         // 自动管理图层 z-index
5.   hideSingleBase: false,    // 是否隐藏单一基础图层
6.   sortLayers: false,        // 是否排序图层
7.   sortFunction: (a, b) => { ... } // 自定义排序函数
8. }

复制代码

关键配置说明

• autoZIndex
  自动为新图层分配递增的 z-index，确保叠加次序精确。
  
• sortLayers
  启用后按 sortFunction 排序图层（默认按名称字母排序）。
  
• hideSingleBase
  当仅有一个底子图层时隐藏其选项地区。
  

---

初始化 (initialize)

1. initialize: function (baseLayers, overlays, options) {
2.   Util.setOptions(this, options);
3.   this._layerControlInputs = [];  // 存储输入控件
4.   this._layers = [];             // 存储图层信息
5.   this._lastZIndex = 0;          // 自动 Z-Index 计数器
7.   // 添加初始图层
8.   for (var i in baseLayers) this._addLayer(baseLayers[i], i);
9.   for (i in overlays) this._addLayer(overlays[i], i, true);
10. }

复制代码

参数说明

• baseLayers: 底子图层对象（互斥，如地图类型切换）
  
• overlays: 覆盖层对象（可叠加，如标记层）
  

---

生命周期方法

onAdd(map)

1. onAdd: function (map) {
2.   this._initLayout();     // 初始化 DOM 结构
3.   this._update();         // 渲染图层选项
4.   this._map = map;
5.   map.on("zoomend", this._checkDisabledLayers, this); // 监听缩放事件
6.   // 绑定图层变化事件
7.   this._layers.forEach(layer => layer.layer.on("add remove", this._onLayerChange, this));
8. }

复制代码

onRemove()

1. onRemove: function () {
2.   this._map.off("zoomend", this._checkDisabledLayers, this);
3.   // 解绑图层事件
4.   this._layers.forEach(layer => layer.layer.off("add remove", this._onLayerChange, this));
5. }

复制代码

---

图层管理 API

添加/移除图层

1. addBaseLayer(layer, name); // 添加基础图层
2. addOverlay(layer, name); // 添加覆盖层
3. removeLayer(layer); // 移除指定图层

复制代码

核心逻辑方法

1. _addLayer(layer, name, overlay) {
2.   // 处理排序、自动 Z-Index
3.   if (this.options.sortLayers) this._layers.sort(...);
4.   if (this.options.autoZIndex) layer.setZIndex(++this._lastZIndex);
5. }

复制代码

---

DOM 与交互

控件布局 (_initLayout)

1. _initLayout: function () {
2.   // 创建 DOM 结构
3.   this._container = DomUtil.create("div", "leaflet-control-layers");
4.   this._section = DomUtil.create("section", "leaflet-control-layers-list");
6.   // 折叠/展开交互逻辑
7.   if (this.options.collapsed) {
8.     this._map.on("click", this.collapse);
9.     DomEvent.on(container, { mouseenter: this._expandSafely, mouseleave: this.collapse });
10.   }
11. }

复制代码

更新逻辑 (_update)

1. _update: function () {
2.   // 清空并重新渲染所有选项
3.   DomUtil.empty(this._baseLayersList);
4.   DomUtil.empty(this._overlaysList);
5.   this._layers.forEach(layer => this._addItem(layer));
6. }

复制代码

---

变乱处理

输入控件点击 (_onInputClick)

1. _onInputClick: function () {
2.   // 处理图层显隐切换
3.   const addedLayers = [], removedLayers = [];
4.   this._layerControlInputs.forEach(input => {
5.     const layer = this._getLayer(input.layerId).layer;
6.     input.checked ? addedLayers.push(layer) : removedLayers.push(layer);
7.   });
8.   // 更新地图图层
9.   removedLayers.forEach(layer => this._map.removeLayer(layer));
10.   addedLayers.forEach(layer => this._map.addLayer(layer));
11. }

复制代码

图层状态变革 (_onLayerChange)

1. _onLayerChange: function (e) {
2.   // 触发 Leaflet 事件：baselayerchange / overlayadd / overlayremove
3.   const obj = this._getLayer(Util.stamp(e.target));
4.   const eventType = obj.overlay ?
5.     (e.type === "add" ? "overlayadd" : "overlayremove") :
6.     (e.type === "add" ? "baselayerchange" : null);
7.   if (eventType) this._map.fire(eventType, obj);
8. }

复制代码

---

辅助功能

动态禁用图层 (_checkDisabledLayers)

1. _checkDisabledLayers: function () {
2.   // 根据当前缩放级别禁用不符合条件的图层
3.   const zoom = this._map.getZoom();
4.   this._layerControlInputs.forEach(input => {
5.     const layer = this._getLayer(input.layerId).layer;
6.     input.disabled =
7.       (layer.options.minZoom !== undefined && zoom < layer.options.minZoom) ||
8.       (layer.options.maxZoom !== undefined && zoom > layer.options.maxZoom);
9.   });
10. }

复制代码

安全睁开逻辑 (_expandSafely)

1. _expandSafely: function () {
2.   // 临时阻止点击事件防止误操作
3.   this._preventClick = true;
4.   DomEvent.on(this._section, "click", DomEvent.preventDefault);
5.   setTimeout(() => {
6.     DomEvent.off(this._section, "click", DomEvent.preventDefault);
7.     this._preventClick = false;
8.   }, 0);
9. }

复制代码

---

计划亮点

• 相应式计划
  
  
  
  • 自动根据地图缩放级别禁用不符合条件的图层选项
    
  • 睁开时动态盘算最大高度避免溢出视口
    
  
  
• 可扩展性
  
  
  
  • 支持通过 sortFunction 自定义图层排序规则
    
  • 允许通过 autoZIndex 自动管理图层叠加次序
    
  
  
• 无障碍支持
  
  
  
  • 使用 aria-haspopup 标记控件
    
  • 支持键盘操作（通过回车键睁开）
    
  
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。