JS 监听鼠标滚轮事件的标准写法与 wheel 对象详解

图 0：JavaScript 鼠标滚轮事件现代标准核心全览

一、标准监听写法与 passive 参数机制

监听滚轮事件的代码形式本身并不复杂，但在现代浏览器中，参数配置的选择直接决定了交互功能能否正常工作以及页面滚动是否流畅。

1.1 最简标准写法

给指定 DOM 元素注册滚轮事件的标准写法如下：

// 获取目标容器元素
const container = document.getElementById('scroll-container');

// 声明事件处理函数
function onWheelHandler(event) {
  // 阻止浏览器默认页面滚动行为（如自定义局部缩放或模拟滚动条时）
  event.preventDefault();

  // 从 WheelEvent 对象中解构滚动偏移量
  const { deltaX, deltaY, deltaMode } = event;
  console.log(`水平偏移: ${deltaX}, 垂直偏移: ${deltaY}, 模式: ${deltaMode}`);
}

// 注册监听器：需要调用 preventDefault 时，必须显式声明 passive: false
container.addEventListener('wheel', onWheelHandler, { passive: false });

1.2 现代浏览器为何默认 passive: true？

在 Chrome、Firefox 和 Safari 等现代浏览器中，为了保障用户的滚动体验，绑定在 window、document 以及 document.body 上的 wheel 和 touchstart 事件，其 passive 配置项默认已被设为 true。

这一改动的核心原因在于浏览器的线程架构设计。现代浏览器的页面滚动通常运行在独立的合成器线程（Compositor Thread）上，从而能够在主线程执行复杂 JavaScript 计算时仍然保持 60fps/120fps 的平滑滚动。如果事件监听器默认是非被动的（passive: false），合成器线程每次检测到用户滚动时，都必须暂停滚动操作，强制等待 JavaScript 主线程执行完事件回调函数，以确认回调内是否调用了 event.preventDefault()。一旦主线程出现微小的耗时计算，就会直接导致整页滚动出现肉眼可见的卡顿。

当声明了 passive: true 时，开发者就向浏览器承诺：“本监听器内绝对不会调用 preventDefault()”。因此合成器线程可以立即推进页面滚动，丝毫不受主线程阻塞。

图 1：鼠标滚轮事件监听注册与 Passive 选项决策流程

二、WheelEvent 对象核心属性详解

在 wheel 事件触发时，回调函数接收到的参数是规范定义的 WheelEvent 实例（继承自 MouseEvent 和 UIEvent）。它封装了滚动的轴向距离、度量单位以及指针坐标。

2.1 三维轴向偏移：deltaX、deltaY 与 deltaZ

• deltaY：垂直滚动位移。向下滚动为正值（> 0），向上滚动为负值（< 0）。这与屏幕坐标系（Y 轴向下为正）保持完全一致。
• deltaX：水平滚动位移。向右滚动为正值（> 0），向左滚动为负值（< 0）。当用户使用横向滚轮、按住 Shift 拨动滚轮或在触控板上双指横向滑动时触发。
• deltaZ：沿 Z 轴（深度方向）的位移。目前除了极少数特殊 3D 交互设备外，主流消费级鼠标和触控板该值恒为 0。

2.2 度量单位模式：deltaMode 的差异与换算

许多开发者常常误以为 deltaY 始终代表“屏幕像素值”，这是一个常见的陷阱。实际上，deltaY 的具体物理单位由 event.deltaMode 属性决定：

当需要在自定义画布缩放或自定义滚动条中实现一致的用户体验时，必须针对 deltaMode 进行像素归一化换算：

function normalizeWheelDelta(event) {
  let { deltaX, deltaY, deltaMode } = event;

  // 基准行高与页高预设值
  const LINE_HEIGHT = 20;   // 单行基准像素
  const PAGE_HEIGHT = 600;  // 单页基准像素

  if (deltaMode === 1) {
    // DOM_DELTA_LINE：将行数换算为像素
    deltaX *= LINE_HEIGHT;
    deltaY *= LINE_HEIGHT;
  } else if (deltaMode === 2) {
    // DOM_DELTA_PAGE：将页数换算为像素
    deltaX *= PAGE_HEIGHT;
    deltaY *= PAGE_HEIGHT;
  }

  return { x: deltaX, y: deltaY };
}

图 2：WheelEvent 核心属性结构与坐标/向量体系

三、历史变迁与常见误区辨析

许多长期维护老项目的工程师在查看旧代码时，经常会看到 mousewheel、DOMMouseScroll、wheelDelta 等属性。理清这些特性的历史由来，能够帮助我们更深刻地理解为什么现行标准要如此设计。

3.1 废弃事件的历史成因

在 W3C 制定 wheel 标准之前，各大浏览器厂商各自为政：

• IE 与早期 WebKit：推出了私有的 mousewheel 事件，其对象包含 event.wheelDelta。但它的数值方向是向上滚为正（+120），向下滚为负（-120），且完全没有提供横向滚动支持。
• 旧版 Gecko (Firefox)：推出了私有的 DOMMouseScroll 事件，其对象包含 event.detail。它的数值方向与 WebKit 正好相反：向下滚为正（+3），向上滚为负（-3），单位是文本行。

这种方向相反、名称各异、单位不一的混乱局面，促使 W3C 在 DOM Level 3 Events 规范中正式推出了统一的 wheel 事件与 WheelEvent 接口。当前所有主流浏览器早已完全支持该标准，旧项目的兼容分支已无需再保留。

3.2 误区辨析一：“可以用 wheel 事件完全替代 scroll 事件”

这种说法看似合理，因为在日常浏览网页时，绝大多数滚动都是由鼠标滚轮或触控板手势带动的。然而在实际机制上，这两者有着本质区别：

• 触发阶段不同：wheel 代表的是用户的物理输入意图，在任何滚动发生之前触发；而 scroll 代表的是DOM 布局已经产生了实际位移。
• 触发范围不同：当页面已经滚动到最顶部或最底部时，用户继续拨动滚轮，wheel 事件依然会源源不断地触发，而 scroll 事件则完全停止触发。
• 来源不同：用户通过键盘按键（空格键、PageDown、方向键）、鼠标拖拽右侧原生滚动条、或者 JavaScript 执行 window.scrollTo() 时，只会触发 scroll 事件，根本不会触发 wheel 事件。

结论：如果需要监听用户“到了哪一步”或者计算“阅读进度”，必须使用 scroll 事件；如果需要“拦截滚动行为”、“对滚轮输入做出定制响应（如画板缩放）”，才必须使用 wheel 事件。

3.3 误区辨析二：“deltaY 的绝对值固定是 100 或 120”

部分开发者在编写代码时喜欢写出类似 if (e.deltaY === 100) 或固定除以 100 的逻辑。在某些接驳特定物理鼠标的 Windows 电脑上，这看似能够工作，但在触控板或开启了平滑滚动的系统上会彻底失效。

在 macOS 触控板或高刷新率设备上，滚轮手势被解析为连续的微小浮点数（例如 1.24、0.85、-3.62 等），并且在手指离开触控板后，系统还会派发带有惯性衰减的微小滚轮事件。因此，任何基于固定步进数值的代码都会产生跳变或判断失效。获取方向的正确方式应始终采用 Math.sign(event.deltaY)。

图 3：滚轮事件演进历程与 wheel / scroll 本质差异

四、实战场景与完整实现

在实际项目中，滚轮事件最广泛的应用场景包括图形画布以光标为中心缩放，以及水平轮播图/横向表格的滚轮联动。以下提供符合生产标准的完整实现。

4.1 实战一：以鼠标光标为中心平滑缩放画布

在思维导图、流程图设计器或图片查看器中，缩放时必须保持鼠标指针下方的图像内容静止，而不是以视口中心为原点进行机械缩放。这需要结合 WheelEvent 的 clientX/clientY 与 deltaY：

class ZoomableCanvas {
  constructor(container, targetImage) {
    this.container = container;
    this.target = targetImage;
    this.scale = 1;
    this.translateX = 0;
    this.translateY = 0;
    this.ticking = false;

    // 绑定事件处理函数，显式配置 passive: false
    this.onWheel = this.handleWheel.bind(this);
    this.container.addEventListener('wheel', this.onWheel, { passive: false });
  }

  handleWheel(e) {
    // 阻止整页默认滚动
    e.preventDefault();

    // 确定缩放系数：向上滚放大(deltaY < 0)，向下滚缩小(deltaY > 0)
    const zoomFactor = e.deltaY < 0 ? 1.1 : 0.9;
    const newScale = Math.min(Math.max(this.scale * zoomFactor, 0.2), 5.0);

    // 获取容器尺寸及鼠标在容器内的相对坐标
    const rect = this.container.getBoundingClientRect();
    const mouseX = e.clientX - rect.left;
    const mouseY = e.clientY - rect.top;

    // 计算以鼠标为中心的平移偏移量补偿
    const ratio = 1 - newScale / this.scale;
    this.translateX += (mouseX - this.translateX) * ratio;
    this.translateY += (mouseY - this.translateY) * ratio;
    this.scale = newScale;

    // 利用 requestAnimationFrame 批量调度重绘，避免掉帧
    if (!this.ticking) {
      this.ticking = true;
      requestAnimationFrame(() => {
        this.target.style.transform = 
          `translate(${this.translateX}px, ${this.translateY}px) scale(${this.scale})`;
        this.ticking = false;
      });
    }
  }

  destroy() {
    this.container.removeEventListener('wheel', this.onWheel);
  }
}

4.2 实战二：将垂直滚轮转为容器水平滚动

当页面中存在横向滑动的卡片流或图表时，用户往往习惯直接使用垂直滚轮。我们可以通过监听垂直 deltaY 并将其赋值给容器的 scrollLeft 来实现无缝横滚：

const horizontalList = document.querySelector('.horizontal-card-list');

horizontalList.addEventListener('wheel', (e) => {
  // 只有垂直滚动且没有按住 Shift 时进行劫持转换
  if (Math.abs(e.deltaY) > Math.abs(e.deltaX) && !e.shiftKey) {
    // 检查容器是否已经滚到最左或最右边缘
    const maxScrollLeft = horizontalList.scrollWidth - horizontalList.clientWidth;
    const canScroll = (e.deltaY > 0 && horizontalList.scrollLeft < maxScrollLeft) ||
                      (e.deltaY < 0 && horizontalList.scrollLeft > 0);

    if (canScroll) {
      // 还有横向滚动空间时阻止外部主页面下滚
      e.preventDefault();
      horizontalList.scrollLeft += e.deltaY;
    }
  }
}, { passive: false });

图 4：JavaScript 鼠标滚轮开发核心规范与避坑速查

五、常见问题排查与速查清单

1. 为什么在移动端手机上滚动完全不触发 wheel 事件？
   移动端触屏滑动手势派发的是 touchstart、touchmove、touchend 以及后续合成的 scroll 事件，根本不存在 wheel 事件。只有当外接实体蓝牙鼠标操作移动设备时才会有 wheel 事件。如果需要兼容双端手势，应分别对 Touch 与 Wheel 进行抽象适配。
2. 触控板双指缩放为何会误触发 wheel 事件？
   在 Chrome 和 Edge 等 Chromium 内核浏览器中，用户在触控板上做双指捏合（Pinch to zoom）手势时，浏览器会将其映射为带有 ctrlKey: true 的特殊 wheel 事件。如果你的应用需要区分“普通双指滚动”与“双指捏合手势”，只需判断 event.ctrlKey === true 即可进行精准分支处理。
3. 弹窗滚动穿透的最优解是什么？
   虽然可以通过在弹窗上监听 wheel 并 preventDefault() 来阻断滚轮穿透，但现代浏览器更推荐纯 CSS 属性：在弹窗滚动容器上设置 overscroll-behavior: contain;。这一行 CSS 能够直接在合成器线程切断滚动链（Scroll Chaining），无需编写任何 JS 监听即可彻底解决穿透问题。