首页 / MapLibre / API 文档
MapWheelEvent
先看结论
滚轮事件对象,用来观察或拦下滚轮缩放,比如只在按住 Ctrl 时才允许地图吃掉滚轮。
map.on('wheel', function (e) { if (!e.originalEvent.ctrlKey) e.preventDefault(); })
字段
| 字段 | 类型 | 说明 |
|---|---|---|
type | 'wheel' | 事件名固定 |
target | Map | 触发事件的地图实例 |
originalEvent | WheelEvent | 原始事件,可取 deltaY、ctrlKey、clientX |
preventDefault() | 方法 | 阻止地图执行本次滚轮缩放 |
defaultPrevented | boolean | 是否已调用过 preventDefault |
事件在 ScrollZoomHandler 之前派发,因此
preventDefault() 能真正拦下缩放,而不是事后再撤销。
页面滚动是否需要同时阻止,由布局决定,地图不会代劳。
相关开关
| 成员 | 说明 |
|---|---|
map.scrollZoom.enable() | 开启滚轮缩放,默认已开启 |
map.scrollZoom.disable() | 整体关闭,连事件都不再参与缩放 |
map.scrollZoom.isEnabled() | 查询当前状态 |
scrollZoom 构造参数 | speed 默认 1,可调缩放步长 |
示例
var zoomWithCtrl = false;
map.on('wheel', function (e) {
/* 不按 Ctrl 时把滚轮还给页面滚动 */
if (!zoomWithCtrl && !e.originalEvent.ctrlKey) {
e.preventDefault();
}
});
document.getElementById('mode').addEventListener('change', function () {
zoomWithCtrl = this.checked;
document.getElementById('hint').textContent = zoomWithCtrl
? '按住 Ctrl 滚动滚轮缩放地图'
: '滚轮直接缩放地图';
});
/* 需要完全托管时,直接关掉内置处理器 */
// map.scrollZoom.disable();
注意事项
preventDefault() 拦的是地图缩放,不是页面滚动。
页面本身在滚轮时仍会滚动,除非同时对
originalEvent 调用原生 preventDefault,
或给容器设置 overflow: hidden。
触控板的双指滚动同样派发 wheel,deltaY 很小且连续。
用 ctrlKey 做判断时,macOS 的捏合手势不会带上该键,
行为与 Windows 不一致,需要按平台分别处理。
别在监听里反复开关处理器。
scrollZoom.disable() 会移除 DOM 监听,频繁调用造成多余的
绑定与解绑。用事件里的条件判断更轻。
经纬志(2026)。《MapWheelEvent》。https://www.jingweizhi.com/maplibre/api/map-wheel-event.html(访问日期 2026-11-03)。