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

概述

本文将介绍Leaflet库中最后一个组件，即图层控制组件 Control.Layers。

源码实现

export var Layers = Control.extend({options: {collapsed: true,position: "topright",autoZIndex: true,hideSingleBase: false,sortLayers: false,sortFunction: function (layerA, layerB, nameA, nameB) {return nameA < nameB ? -1 : nameB < nameA ? 1 : 0;},},initialize: function (baseLayers, overlays, options) {Util.setOptions(this, options);this._layerControlInputs = [];this._layers = [];this._lastZIndex = 0;this._handlingClick = false;this._preventClick = false;for (var i in baseLayers) {this._addLayer(baseLayers[i], i);}for (i in overlays) {this._addLayer(overlays[i], i, true);}},onAdd: function (map) {this._initLayout();this._update();this._map = map;map.on("zoomend", this._checkDisabledLayers, this);for (var i = 0; i < this._layers.length; i++) {this._layers[i].layer.on("add remove", this._onLayerChange, this);}return this._container;},addTo: function (map) {Control.prototype.addTo.call(this, map);return this._expandIfNotCollapsed();},onRemove: function () {this._map.off("zoomend", this._checkDisabledLayers, this);for (var i = 0; i < this._layers.length; i++) {this._layers[i].layer.off("add remove", this._onLayerChange, this);}},addBaseLayer: function (layer, name) {this._addLayer(layer, name);return this._map ? this._update() : this;},addOverlay: function (layer, name) {this._addLayer(layer, name, true);return this._map ? this._update() : this;},removeLayer: function (layer) {layer.off("add remove", this._onLayerChange, this);var obj = this._getLayer(Util.stamp(layer));if (obj) {this._layers.splice(this._layers.indexOf(obj), 1);}return this._map ? this._update() : this;},expand: function () {DomUtil.addClass(this._container, "leaflet-control-layers-expanded");this._section.style.height = null;var acceptableHeight =this._map.getSize().y - (this._container.offsetTop + 50);if (acceptableHeight < this._section.clientHeight) {DomUtil.addClass(this._section, "leaflet-control-layers-scrollbar");this._section.style.height = acceptableHeight + "px";} else {DomUtil.removeClass(this._section, "leaflet-control-layers-scrollbar");}this._checkDisabledLayers();return this;},collapse: function () {DomUtil.removeClass(this._container, "leaflet-control-layers-expanded");return this;},_initLayout: function () {var className = "leaflet-control-layers",container = (this._container = DomUtil.create("div", className)),collapsed = this.options.collapsed;container.setAttribute("aria-haspopup", true);DomEvent.disableClickPropagation(container);DomEvent.disableScrollPropagation(container);var section = (this._section = DomUtil.create("section",className + "-list"));if (collapsed) {this._map.on("click", this.collapse, this);DomEvent.on(container,{mouseenter: this._expandSafely,mouseleave: this.collapse,},this);}var link = (this._layersLink = DomUtil.create("a",className + "-toggle",container));link.href = "#";link.title = "Layers";link.setAttribute("role", "button");DomEvent.on(link,{keydown: function (e) {if (e.keyCode === 13) {this._expandSafely();}},click: function (e) {DomEvent.preventDefault(e);this._expandSafely();},},this);if (!collapsed) {this.expand();}this._baseLayersList = DomUtil.create("div", className + "-base", section);this._separator = DomUtil.create("div", className + "-separator", section);this._overlaysList = DomUtil.create("div",className + "-overlays",section);container.appendChild(section);},_getLayer: function (id) {for (var i = 0; i < this._layers.length; i++) {if (this._layers[i] && Util.stamp(this._layers[i].layer) === id) {return this._layers[i];}}},_addLayer: function (layer, name, overlay) {if (this._map) {layer.on("add remove", this._onLayerChange, this);}this._layers.push({layer: layer,name: name,overlay: overlay,});if (this.options.sortLayers) {this._layers.sort(Util.bind(function (a, b) {return this.options.sortFunction(a.layer, b.layer, a.name, b.name);}, this));}if (this.options.autoZIndex && layer.setZIndex) {this._lastZIndex++;layer.setZIndex(this._lastZIndex);}this._expandIfNotCollapsed();},_update: function () {if (!this._container) {return this;}DomUtil.empty(this._baseLayersList);DomUtil.empty(this._overlaysList);this._layerControlInputs = [];var baseLayersPresent,overlaysPresent,i,obj,baseLayersCount = 0;for (i = 0; i < this._layers.length; i++) {obj = this._layers[i];this._addItem(obj);overlaysPresent = overlaysPresent || obj.overlay;baseLayersPresent = baseLayersPresent || !obj.overlay;baseLayersCount += !obj.overlay ? 1 : 0;}if (this.options.hideSingleBase) {baseLayersPresent = baseLayersPresent && baseLayersCount > 1;this._baseLayersList.style.display = baseLayersPresent ? "" : "none";}this._separator.style.display =overlaysPresent && baseLayersPresent ? "" : "none";return this;},_onLayerChange: function (e) {if (!this._handlingClick) {this._update();}var obj = this._getLayer(Util.stamp(e.target));var type = obj.overlay? e.type === "add"? "overlayadd": "overlayremove": e.type === "add"? "baselayerchange": null;if (type) {this._map.fire(type, obj);}},_createRadioElement: function (name, checked) {var radioHtml ='<input type="radio" class="leaflet-control-layers-selector" name="' +name +'"' +(checked ? ' checked="checked"' : "") +"/>";var radioFragment = document.createElement("div");radioFragment.innerHTML = radioHtml;return radioFragment.firstChild;},_addItem: function (obj) {var label = document.createElement("label"),checked = this._map.hasLayer(obj.layer),input;if (obj.overlay) {input = document.createElement("input");input.type = "checkbox";input.className = "leaflet-control-layers-selector";input.defaultChecked = checked;} else {input = this._createRadioElement("leaflet-base-layers_" + Util.stamp(this),checked);}this._layerControlInputs.push(input);input.layerId = Util.stamp(obj.layer);DomEvent.on(input, "click", this._onInputClick, this);var name = document.createElement("span");name.innerHTML = " " + obj.name;var holder = document.createElement("span");label.appendChild(holder);holder.appendChild(input);holder.appendChild(name);var container = obj.overlay ? this._overlaysList : this._baseLayersList;container.appendChild(label);this._checkDisabledLayers();return label;},_onInputClick: function () {if (this._preventClick) {return;}var inputs = this._layerControlInputs,input,layer;var addedLayers = [],removedLayers = [];this._handlingClick = true;for (var i = inputs.length - 1; i >= 0; i--) {input = inputs[i];layer = this._getLayer(input.layerId).layer;if (input.checked) {addedLayers.push(layer);} else if (!input.checked) {removedLayers.push(layer);}}for (i = 0; i < removedLayers.length; i++) {if (this._map.hasLayer(removedLayers[i])) {this._map.removeLayer(removedLayers[i]);}}for (i = 0; i < addedLayers.length; i++) {if (!this._map.hasLayer(addedLayers[i])) {this._map.addLayer(addedLayers[i]);}}this._handlingClick = false;this._refocusOnMap();},_checkDisabledLayers: function () {var inputs = this._layerControlInputs,input,layer,zoom = this._map.getZoom();for (var i = inputs.length - 1; i >= 0; i--) {input = inputs[i];layer = this._getLayer(input.layerId).layer;input.disabled =(layer.options.minZoom !== undefined && zoom < layer.options.minZoom) ||(layer.options.maxZoom !== undefined && zoom > layer.options.maxZoom);}},_expandIfNotCollapsed: function () {if (this._map && !this.options.collapsed) {this.expand();}return this;},_expandSafely: function () {var section = this._section;this._preventClick = true;DomEvent.on(section, "click", DomEvent.preventDefault);this.expand();var that = this;setTimeout(function () {DomEvent.off(section, "click", DomEvent.preventDefault);that._preventClick = false;});},
});export var layers = function (baseLayers, overlays, options) {return new Layers(baseLayers, overlays, options);
};

核心结构

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

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

---

配置项 (options)

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

关键配置说明

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

---

初始化 (initialize)

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

参数说明

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

---

生命周期方法

onAdd(map)

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

onRemove()

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

---

图层管理 API

添加/移除图层

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

核心逻辑方法

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

---

DOM 与交互

控件布局 (_initLayout)

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

更新逻辑 (_update)

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

---

事件处理

输入控件点击 (_onInputClick)

_onInputClick: function () {// 处理图层显隐切换const addedLayers = [], removedLayers = [];this._layerControlInputs.forEach(input => {const layer = this._getLayer(input.layerId).layer;input.checked ? addedLayers.push(layer) : removedLayers.push(layer);});// 更新地图图层removedLayers.forEach(layer => this._map.removeLayer(layer));addedLayers.forEach(layer => this._map.addLayer(layer));
}

图层状态变化 (_onLayerChange)

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

---

辅助功能

动态禁用图层 (_checkDisabledLayers)

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

安全展开逻辑 (_expandSafely)

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

---

设计亮点

1. 响应式设计

   • 自动根据地图缩放级别禁用不符合条件的图层选项
   • 展开时动态计算最大高度避免溢出视口

2. 可扩展性

   • 支持通过 sortFunction 自定义图层排序规则
   • 允许通过 autoZIndex 自动管理图层叠加顺序

3. 无障碍支持

   • 使用 aria-haspopup 标记控件
   • 支持键盘操作（通过回车键展开）