JS 中 wheel 事件与 mousewheel 事件有什么区别？

一、为什么会有两个名称相似的滚轮事件？

在前端开发的历史演进中，浏览器的滚轮事件曾经历过严重的碎片化时期。早期微型计算机交互主要依赖纯物理滚轮鼠标，微软在 Internet Explorer 6 时代首先实现了 mousewheel 私有事件，并通过事件对象的 wheelDelta 属性反馈滚轮转动幅度。随后，WebKit（Safari、Chrome 早期内核）和 Opera 借鉴并实现了该事件。

然而，Firefox（Gecko 内核）自始至终未将 mousewheel 作为官方标准，而是长时间独家支持私有的 DOMMouseScroll 事件与 detail 属性。这种各家自立门户的局面导致前端工程师在编写自定义滚动条、图片缩放查看器或地图缩放功能时，不得不编写冗长且脆弱的浏览器特性分支判断。

为了解决历史包袱并适配现代触摸板（Trackpad）的多向滑动、高精度手势以及无障碍设备，W3C 在 DOM Level 3 Events 规范中正式推出了标准化的 wheel 事件（对应事件对象 WheelEvent）。各大现代浏览器随后迅速全面支持了 wheel，并将旧有的 mousewheel 标记为 Deprecated（已废弃）。

二、核心区别详解：四大技术断层

1. 属性体系与多轴向空间支持

传统的 mousewheel 事件继承自常规 MouseEvent，其核心属性仅有 wheelDelta，主要用于表达单一维度的垂直滚动。尽管后来 WebKit 补充了 wheelDeltaX 和 wheelDeltaY，但这始终未被纳入标准规范，且无法表达空间三维操作。

标准 wheel 事件则专门派生了 WheelEvent 接口，原生提供了标准的三维位移属性：

• deltaX（双精度浮点数）：表示水平横向滚动位移量。用户向右滑动触控板或倾斜鼠标滚轮时，该值为正；向左滑动时为负。
• deltaY（双精度浮点数）：表示垂直纵向滚动位移量。
• deltaZ（双精度浮点数）：表示沿 Z 轴（深度方向）的滚动位移量，常用于特定的三维操作硬件或 3D 虚拟场景漫游。

2. 致命陷阱：纵向滚动数值的正负极性完全相反

如果你在重构老旧代码时直接将 mousewheel 替换为 wheel，往往会发现页面或缩放组件的行为发生了“逆向反转”。这是因为两个事件在设计滚动正负方向时采用了截然相反的坐标哲学：

• 标准 wheel 事件（符合页面坐标系）：以页面内容的位移与 scrollTop 递增为基准。当用户向后（向下）滚动滚轮时，视图向下移动，scrollTop 增大，因此 deltaY 为正数（> 0）；反之，向前（向上）滚动滚轮时，deltaY 为负数（< 0）。
• 已废弃 mousewheel 事件（符合物理矢量朝向）：以向上位移为正基准。当用户向后（向下）滚动滚轮时，其 wheelDelta 反而是负数（< 0，常规步进为 -120）；当用户向前（向上）滚动滚轮时，wheelDelta 则是正数（> 0，常规步进为 +120）。

3. 滚动度量单位：deltaMode 属性

传统的 mousewheel 事件没有提供任何单位信息，其 wheelDelta 普遍以 120 的倍数递增（120 代表鼠标机械滚轮的一个物理刻度 Tick），但在高精度触控板或平滑滚动鼠标上，该数值可能出现非线性的任意浮点数，开发者难以精确计算实际应滚动的像素距离。

而标准 wheel 引入了专门的只读属性 deltaMode，明确告知开发者 deltaX/Y/Z 所采用的物理度量单位：

• 0 (DOM_DELTA_PIXEL)：增量以像素（px）为单位。这是现代触控板和大部分平滑滚轮的默认返回模式。
• 1 (DOM_DELTA_LINE)：增量以文本行（lines）为单位。常见于 Windows 系统下设置了“一次滚动 N 行”的传统鼠标机械滚轮。
• 2 (DOM_DELTA_PAGE)：增量以整页（pages）为单位。常见于用户在操作系统中开启了按页滚屏模式或翻页器设备。

4. 触发介质与手势支持的广度

mousewheel 在语义上局限于“鼠标”（Mouse），对现代笔记本触控板、连续惯性滚动（Momentum Scrolling）以及在触控板上按住 Ctrl 键进行的双指捏合缩放（Pinch-to-zoom）支持极不稳定。

而 wheel 是设备中立（Device-Independent）的抽象事件。现代浏览器（如 Chrome、Edge、Safari）将触控板的双指捏合缩放手势映射为带有 ctrlKey: true 的 wheel 事件，使现代 Web 应用能够非常轻松地构建出媲美原生系统的平滑画布缩放体验。

三、现代工程实践与平滑迁移四步法

在实际工程开发中，推荐完全采用标准 wheel。如果你维护的系统仍需要兼容个别历史陈旧运行环境（如特定工控屏内嵌的旧版 WebView），应当遵循规范的渐进增强与归一化流程。

步骤 1：精确的特性检测（优先选择标准 wheel）

无需使用不可靠的 User-Agent 嗅探，直接通过 JavaScript 原生操作符检测当前运行环境是否支持 onwheel：

// 准确检测当前环境支持的滚轮事件名
const wheelEventName = 'onwheel' in window 
  ? 'wheel' 
  : ('onmousewheel' in window ? 'mousewheel' : 'DOMMouseScroll');

步骤 2：警惕 passive 属性与 preventDefault 拦截失效

现代主流浏览器（Chrome 56+、Safari、Firefox）为了保障页面滚动的丝滑帧率（60fps/120fps），在 window、document 和 document.body 上注册滚轮事件监听器时，默认会将 passive 设置为 true。

如果你的业务场景需要拦截默认滚动行为（例如弹窗打开时禁止底层页面穿透滚动，或在富交互 Canvas 画布中阻止浏览器默认翻页）：

// 必须显式声明 passive: false，否则 e.preventDefault() 将静默失效并抛出控制台警告
const container = document.getElementById('canvas-viewport');

container.addEventListener(wheelEventName, handleWheelAction, { passive: false });

function handleWheelAction(e) {
  // 阻止默认页面滚动
  e.preventDefault();

  // 执行自定义交互逻辑
  processCustomScroll(e);
}

步骤 3：编写健壮的滚轮增量归一化函数（Normalization）

为了在业务逻辑中获得稳定、正负方向统一且单位一致的滚动像素值，建议封装如下轻量级统一解析器：

/**
 * 将任意滚轮事件对象标准化为像素增量
 * 返回统一格式：{ x: number, y: number }
 * 约定：向下/向右滚动为正值，向上/向左滚动为负值
 */
function normalizeWheel(event) {
  let x = 0;
  let y = 0;

  // 1. 标准 wheel 事件优先处理
  if ('deltaY' in event) {
    x = event.deltaX;
    y = event.deltaY;

    // 根据 deltaMode 进行物理单位换算
    if (event.deltaMode === 1) {
      // 文本行模式，常规以每行 16px 或 20px 计算
      const LINE_HEIGHT = 16;
      x *= LINE_HEIGHT;
      y *= LINE_HEIGHT;
    } else if (event.deltaMode === 2) {
      // 页面模式，按视口高度换算
      const PAGE_HEIGHT = window.innerHeight || 800;
      x *= PAGE_HEIGHT;
      y *= PAGE_HEIGHT;
    }
  } 
  // 2. 兼容历史旧版 WebKit / IE 的 mousewheel
  else if ('wheelDelta' in event) {
    // 关键修正：wheelDelta 向下为负，取相反数使向下为正，与 deltaY 保持一致
    y = -event.wheelDelta / 120 * 16;
    if ('wheelDeltaX' in event) {
      x = -event.wheelDeltaX / 120 * 16;
    }
  } 
  // 3. 兼容远古 Firefox 的 DOMMouseScroll
  else if ('detail' in event) {
    // Firefox detail 向下滚动为正，基数通常为 3
    y = event.detail * 16;
  }

  return { x, y };
}

步骤 4：在自定义交互组件中应用

// 在缩放控制器中的完整使用示例
const zoomStage = document.getElementById('zoom-stage');
let currentScale = 1.0;

zoomStage.addEventListener('wheel', (e) => {
  e.preventDefault();
  
  const { y } = normalizeWheel(e);
  
  // y > 0 表示向下滚动（缩小视口），y < 0 表示向上滚动（放大视口）
  if (y > 0) {
    currentScale = Math.max(0.2, currentScale - 0.05);
  } else if (y < 0) {
    currentScale = Math.min(5.0, currentScale + 0.05);
  }
  
  zoomStage.style.transform = `scale(${currentScale})`;
}, { passive: false });

四、对比矩阵与选型总结

为了便于在架构设计与技术选型中快速查阅，下表汇总了 wheel 与 mousewheel 的各项技术指标与差异对比：

在当下的 Web 平台开发中，浏览器对 W3C DOM Level 3 规范的支持度早已达到 100%。我们无需再为了历史陈旧浏览器而编写庞大臃肿的兼容层。在所有新的前端页面、Vue/React 组件或 Canvas 应用中，坚决采用 wheel 事件，并配合明确的 { passive } 配置与 deltaY 判断，即可编写出简洁、高性能且符合 Web 标准的滚轮交互逻辑。