首页 / Leaflet / API 文档

Control.Layers

先看结论

在右上角展开一个面板，用单选按钮切换底图、用复选框开关叠加层。

最后验证 2026-11-03 · Leaflet 1.9.4 · 更新 2026-10-28 · 引用本文

L.control.layers(baseLayers?, overlays?, options?) → Control.Layers

参数

选项	默认值	说明
`baseLayers`	—	底图映射，`{ '显示名': layer }`，同时只显示一个
`overlays`	—	叠加层映射，可多选
`position`	'topright'	控件所在角
`collapsed`	true	是否折叠成图标，点击后展开
`autoZIndex`	true	切换底图时自动调整图层层级
`sortLayers`	false	是否按名称排序图层列表
`sortFunction`	按名称字母排序	自定义比较函数，需 `sortLayers: true`
`hideSingleBase`	false	只有一个底图时隐藏底图分组

成员

成员	返回值	说明
`addBaseLayer(layer, name)`	this	登记一个底图，不自动加到地图
`addOverlay(layer, name)`	this	登记一个叠加层
`removeLayer(layer)`	this	从列表中移除，地图上的图层保留
`expand()` / `collapse()`	this	程序化展开或收起面板
`addTo(map)` / `remove()`	this	挂载与移除
`getContainer()`	HTMLElement	控件容器，可用于改宽度

var osm = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  maxZoom: 19,
  attribution: '© OpenStreetMap contributors'
});
var labels = L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  opacity: 0.8,
  maxZoom: 19
});

var city = L.layerGroup([
  L.marker([39.907359, 116.391263]).bindPopup('天安门')
]);

var layers = L.control.layers(
  { 'OSM 标准': osm, 'OSM 淡色': labels },
  { '重点点位': city },
  { position: 'topright', collapsed: true }
).addTo(map);

map.addLayer(osm);

/* 运行时追加一个叠加层，复选框会自动出现 */
layers.addOverlay(
  L.circle([39.907359, 116.391263], { radius: 800 }).bindPopup('1 km 覆盖'),
  '覆盖范围'
);

/* 监听切换事件做联动 */
map.on('baselayerchange', function (e) { console.log('底图', e.name); });
map.on('overlayadd', function (e) { console.log('开启', e.name); });

登记到控件里的图层不会自动显示。控件只负责 UI，底图的初始状态需要自己 addTo(map)。addBaseLayer 之后若想立刻切换，还要额外调用 map.addLayer 并移除旧底图。

collapsed: true 在移动端能省出地图空间，但多了两次点击。图层不超过三个且以桌面端为主时，设 collapsed: false 直接铺开更省事。底图多于两个时控件会按对象键顺序生成单选项，把最常用的放第一位。

引用本文

经纬志（2026）。《Control.Layers》。https://www.jingweizhi.com/leaflet/api/control-layers.html（访问日期 2026-11-03）。