首页 / Leaflet / API 文档
Control
先看结论
控件基类。缩放按钮、版权信息、图层切换都继承自它，自定义控件也走同一套接口。
L.Control.extend({ options, onAdd, onRemove }) → Control 子类
位置参数
| 取值 | 位置 |
|---|---|
'topleft' | 左上，默认缩放按钮所在角 |
'topright' | 右上，图层切换常用 |
'bottomleft' | 左下，比例尺常用 |
'bottomright' | 右下，版权信息所在角 |
方法
| 方法 | 说明 |
|---|---|
addTo(map) | 添加到地图，触发 onAdd |
remove() | 移除，触发 onRemove |
getContainer() | 返回控件容器 DOM |
getPosition() | 读取当前位置 |
setPosition(position) | 移动位置，内部会先移除再添加 |
子类必须实现的成员
| 成员 | 要求 |
|---|---|
options.position | 四个角之一 |
onAdd(map) | 返回一个 DOM 节点，不能返回 null |
onRemove(map) | 可选，清理定时器与事件监听 |
var HomeControl = L.Control.extend({
options: { position: 'topleft' },
onAdd: function (map) {
var box = L.DomUtil.create('div', 'home-control');
box.innerHTML = '<button type="button">回到初始视图</button>';
L.DomEvent.disableClickPropagation(box);
L.DomEvent.disableScrollPropagation(box);
box.querySelector('button').addEventListener('click', function () {
map.flyTo([39.907359, 116.391263], 12);
});
return box;
}
});
var home = new HomeControl({ position: 'topleft' }).addTo(map);
home.setPosition('topright');任何包含按钮或滚动的控件都要阻断事件传播。
不调用 disableClickPropagation，点击控件会同时触发地图拖拽；
不调用 disableScrollPropagation，在控件上滚轮会缩放地图。
内置控件
| 构造函数 | 作用 | 默认位置 |
|---|---|---|
L.control.zoom(options) | 缩放按钮，可自定义文案与层级 | topleft |
L.control.attribution(options) | 版权信息汇总 | bottomright |
L.control.scale(options) | 比例尺，可选公制/英制 | bottomleft |
L.control.layers(baseLayers, overlays, options) | 底图与叠加层切换面板 | topright |
地图初始化时通过 zoomControl: false、attributionControl: false
关闭默认控件，再用 L.control.zoom({ position: 'bottomright' }).addTo(map)
放到别的位置。不要在关闭后忘记补回缩放按钮，触屏设备会失去唯一的缩放入口。
DOM 工具
| 方法 | 说明 |
|---|---|
L.DomUtil.create(tag, className, container?) | 创建节点并挂类名 |
L.DomUtil.addClass / removeClass | 类名操作 |
L.DomUtil.setPosition(el, point) | 用 transform 定位，比 left/top 高效 |
L.DomEvent.disableClickPropagation(el) | 阻止点击冒泡到地图 |
L.DomEvent.disableScrollPropagation(el) | 阻止滚轮缩放地图 |
L.DomEvent.stop(e) | 阻止默认行为并停止冒泡 |
状态同步
控件通常需要反映地图状态。在 onAdd 里监听 zoomend、
moveend，在 onRemove 里解绑；否则控件被移除后仍在接收事件，
内部引用的 DOM 节点已被回收，容易报空指针。需要在控件里显示比例尺时，
直接用内置的 L.control.scale，它已经处理了缩放级别换算。
经纬志（2026）。《Control》。https://www.jingweizhi.com/leaflet/api/control.html（访问日期 2026-11-03）。