From 51c12c649f0e19eb3e03eb657bd8374b206e8439 Mon Sep 17 00:00:00 2001
From: Takahiro Ebato <takahiro.ebato@gmail.com>
Date: Sat, 11 Jul 2026 13:51:36 +0900
Subject: [PATCH] feat: provide raw deltaX/deltaY/deltaMode in the mousewheel
 event

---
 src/Element.ts        | 16 ++++++++++++
 src/Handler.ts        |  7 ++++-
 src/core/event.ts     |  3 ++-
 src/core/types.ts     |  3 ++-
 test/wheel-event.html | 59 +++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 85 insertions(+), 3 deletions(-)
 create mode 100644 test/wheel-event.html

diff --git a/src/Element.ts b/src/Element.ts
index 7237a7000..8e642ea88 100644
--- a/src/Element.ts
+++ b/src/Element.ts
@@ -219,6 +219,22 @@ export interface ElementEvent {
     pinchY: number,
     pinchScale: number,
     wheelDelta: number,
+    /**
+     * Raw `WheelEvent.deltaX`. Only available in the zrender "mousewheel"
+     * event, which is fired by the native "wheel" event.
+     */
+    deltaX?: number,
+    /**
+     * Raw `WheelEvent.deltaY`. Only available in the zrender "mousewheel"
+     * event, which is fired by the native "wheel" event.
+     */
+    deltaY?: number,
+    /**
+     * Raw `WheelEvent.deltaMode` (0: pixel, 1: line, 2: page).
+     * Only available in the zrender "mousewheel" event, which is
+     * fired by the native "wheel" event.
+     */
+    deltaMode?: number,
     zrByTouch: boolean,
     which: number,
     stop: (this: ElementEvent) => void
diff --git a/src/Handler.ts b/src/Handler.ts
index 45b09ceef..d3eb39807 100644
--- a/src/Handler.ts
+++ b/src/Handler.ts
@@ -7,7 +7,9 @@ import {GestureMgr} from './core/GestureMgr';
 import Displayable from './graphic/Displayable';
 import {PainterBase} from './PainterBase';
 import HandlerDomProxy, { HandlerProxyInterface } from './dom/HandlerProxy';
-import { ZRRawEvent, ZRPinchEvent, ElementEventName, ElementEventNameWithOn, ZRRawTouchEvent } from './core/types';
+import {
+    ZRRawEvent, ZRPinchEvent, ZRRawWheelEvent, ElementEventName, ElementEventNameWithOn, ZRRawTouchEvent
+} from './core/types';
 import Storage from './Storage';
 import Element, {ElementEvent} from './Element';
 import CanvasPainter from './canvas/Painter';
@@ -96,6 +98,9 @@ function makeEventPacket(eveType: ElementEventName, targetInfo: {
         pinchY: (event as ZRPinchEvent).pinchY,
         pinchScale: (event as ZRPinchEvent).pinchScale,
         wheelDelta: event.zrDelta,
+        deltaX: (event as ZRRawWheelEvent).deltaX,
+        deltaY: (event as ZRRawWheelEvent).deltaY,
+        deltaMode: (event as ZRRawWheelEvent).deltaMode,
         zrByTouch: event.zrByTouch,
         which: event.which,
         stop: stopEvent
diff --git a/src/core/event.ts b/src/core/event.ts
index e872db58c..9be0b85c9 100644
--- a/src/core/event.ts
+++ b/src/core/event.ts
@@ -196,7 +196,8 @@ export function normalizeEvent(
     return e;
 }
 
-// TODO: also provide prop "deltaX" "deltaY" in zrender "mousewheel" event.
+// Note: the normalization here ignores "deltaMode", so the scale of `zrDelta` differs
+// among browsers and devices. `ElementEvent` provides the raw "deltaX"/"deltaY"/"deltaMode".
 function getWheelDeltaMayPolyfill(e: ZRRawEvent): number {
     // Although event "wheel" do not has the prop "wheelDelta" in spec,
     // agent like Chrome and Safari still provide "wheelDelta" like
diff --git a/src/core/types.ts b/src/core/types.ts
index 3ca5988e0..00a45e60d 100644
--- a/src/core/types.ts
+++ b/src/core/types.ts
@@ -62,10 +62,11 @@ type ZREventProperties = {
 }
 
 export type ZRRawMouseEvent = MouseEvent & ZREventProperties
+export type ZRRawWheelEvent = WheelEvent & ZREventProperties
 export type ZRRawTouchEvent = TouchEvent & ZREventProperties
 export type ZRRawPointerEvent = TouchEvent & ZREventProperties
 
-export type ZRRawEvent = ZRRawMouseEvent | ZRRawTouchEvent | ZRRawPointerEvent
+export type ZRRawEvent = ZRRawMouseEvent | ZRRawWheelEvent | ZRRawTouchEvent | ZRRawPointerEvent
 
 export type ZRPinchEvent = ZRRawEvent & {
     pinchScale: number
diff --git a/test/wheel-event.html b/test/wheel-event.html
new file mode 100644
index 000000000..84204af87
--- /dev/null
+++ b/test/wheel-event.html
@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8" />
+    <title>Wheel Event: raw deltaX / deltaY / deltaMode</title>
+    <script src="../dist/zrender.js"></script>
+    <script src="lib/config.js"></script>
+    <style>
+        body { font-family: monospace; }
+        #log { white-space: pre; font-size: 12px; }
+        table { border-collapse: collapse; margin: 10px 0; }
+        td, th { border: 1px solid #999; padding: 4px 10px; text-align: right; }
+    </style>
+</head>
+<body>
+    <p>Scroll the mouse wheel / trackpad over the rectangle.
+       The zrender "mousewheel" event carries the raw <b>deltaX / deltaY / deltaMode</b>
+       of the native WheelEvent, along with the normalized <b>wheelDelta</b>.</p>
+    <div id="main" style="width:600px;height:300px;"></div>
+    <table>
+        <tr>
+            <th>deltaX</th><th>deltaY</th><th>deltaMode</th><th>wheelDelta</th>
+        </tr>
+        <tr id="valueRow">
+            <td>-</td><td>-</td><td>-</td><td>-</td>
+        </tr>
+    </table>
+    <div id="log"></div>
+    <script type="text/javascript">
+        var zr = zrender.init(document.getElementById('main'), {
+            renderer: window.__ZRENDER__DEFAULT__RENDERER__
+        });
+        zr.add(new zrender.Rect({
+            shape: { x: 0, y: 0, width: 600, height: 300 },
+            style: { fill: '#8fd3e8' }
+        }));
+
+        var logEl = document.getElementById('log');
+        var lines = [];
+
+        zr.on('mousewheel', function (e) {
+            var cells = document.getElementById('valueRow').getElementsByTagName('td');
+            var values = [e.deltaX, e.deltaY, e.deltaMode, e.wheelDelta];
+            for (var i = 0; i < values.length; i++) {
+                cells[i].textContent = values[i];
+            }
+
+            lines.unshift(
+                'deltaX=' + e.deltaX
+                + ' deltaY=' + e.deltaY
+                + ' deltaMode=' + e.deltaMode
+                + ' wheelDelta=' + e.wheelDelta
+            );
+            lines = lines.slice(0, 20);
+            logEl.textContent = lines.join('\n');
+        });
+    </script>
+</body>
+</html>