经纬志
首页 / MapLibre / API 文档

MapWheelEvent

先看结论

滚轮事件对象,用来观察或拦下滚轮缩放,比如只在按住 Ctrl 时才允许地图吃掉滚轮。

最后验证 2026-11-03 · MapLibre GL JS 4.x · 更新 2026-10-28 · 引用本文
map.on('wheel', function (e) { if (!e.originalEvent.ctrlKey) e.preventDefault(); })

字段

字段类型说明
type'wheel'事件名固定
targetMap触发事件的地图实例
originalEventWheelEvent原始事件,可取 deltaY、ctrlKey、clientX
preventDefault()方法阻止地图执行本次滚轮缩放
defaultPreventedboolean是否已调用过 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)。