当前位置：文江博客知识库简体中文文档 Web API Element wheel_event

滚轮事件 - Web API 接口参考编辑

当滚动鼠标滚轮或操作其它类似输入设备时会触发滚轮事件。滚轮事件替换了已被弃用的非标准mousewheel事件。

注意事项： 请勿想当然依据滚轮方向（即该事件的各delta属性值）来推断文档内容的滚动方向，因标准未定义滚轮事件具体会引发什么样的行为，引发的行为实际上是各浏览器自行定义的。即便滚轮事件引发了文档内容的滚动行为，也不表示滚轮方向和文档内容的滚动方向一定相同。因而通过该滚轮事件获知文档内容滚动方向的方法并不可靠。要获取文档内容的滚动方向，可在文档内容滚动事件（scroll）中监视scrollLeft和scrollTop二值变化情况，即可推断出滚动方向了。

概要

接口: WheelEvent
同步性: 异步
事件冒泡: 是
可取消: 是
目标元素: defaultView, Document, Element
默认行为: 滚动, 历史记录切换, 或者放大／缩小.

属性

滚轮事件实现了以下事件的属性： WheelEvent, MouseEvent, UIEvent and Event.

Properties of WheelEvent

该接口继承了父接口MouseEvent、UIEvent、Event的属性。

WheelEvent.deltaX 只读

返回double值，该值表示滚轮的横向滚动量。

WheelEvent.deltaY 只读

返回double值，该值表示滚轮的纵向滚动量。

WheelEvent.deltaZ 只读

返回double值，该值表示滚轮的z轴方向上的滚动量。

WheelEvent.deltaMode 只读

返回unsigned long值，该值表示上述各delta*的值的单位。该值及所表示的单位如下：

常量	值	描述
`DOM_DELTA_PIXEL`	`0x00`	滚动量单位为像素。
`DOM_DELTA_LINE`	`0x01`	滚动量单位为行。
`DOM_DELTA_PAGE`	`0x02`	滚动量单位为页。

Properties of MouseEvent

这个接口也继承了UIEvent 和 Event原型上的方法,

MouseEvent.altKey 只读: 当鼠标事件触发的时，如果alt 键被按下，返回true;
MouseEvent.button 只读: 当鼠标事件触发的时，如果鼠标按钮被按下（如果有的话），将会返回一个数值。
MouseEvent.buttons 只读: 当鼠标事件触发的时，如果多个鼠标按钮被按下（如果有的话），将会返回一个或者多个代表鼠标按钮的数字。
MouseEvent.clientX 只读: 鼠标指针在点击元素（DOM）中的X坐标。
MouseEvent.clientY 只读: 鼠标指针在点击元素（DOM）中的Y坐标。
MouseEvent.ctrlKey 只读: 当鼠标事件触发时，如果 control 键被按下，则返回 true；
MouseEvent.metaKey 只读: 当鼠标事件触发时，如果 meta键被按下，则返回 true；
MouseEvent.movementX 只读: 鼠标指针相对于最后mousemove事件位置的X坐标。
MouseEvent.movementY 只读: 鼠标指针相对于最后mousemove事件位置的Y坐标。

MouseEvent.offsetX 只读: 鼠标指针相对于目标节点内边位置的X坐标
MouseEvent.offsetY 只读: 鼠标指针相对于目标节点内边位置的Y坐标
MouseEvent.pageX 只读: 鼠标指针相对于整个文档的X坐标；
MouseEvent.pageY 只读: 鼠标指针相对于整个文档的Y坐标；

MouseEvent.region 只读: 返回被点击事件影响的点击区域的id，如果没有区域被影响则返回null。
MouseEvent.relatedTarget 只读: 鼠标事件的次要目标（如果有的话）
MouseEvent.screenX 只读: 鼠标指针相对于全局（屏幕）的X坐标；
MouseEvent.screenY 只读: 鼠标指针相对于全局（屏幕）的Y坐标；
MouseEvent.shiftKey 只读: 当鼠标事件触发时，如果 shift 键被按下，则返回 true；
MouseEvent.which 只读: 当鼠标事件触发时，表示被按下的按钮。
MouseEvent.mozPressure 只读: 点击事件发生时施加在触摸屏或者平板设备的压力量。这个数值在0.0（最小压力）和1.0（最大压力）之间。
MouseEvent.mozInputSource 只读: 生成事件的类型（若干 MOZ_SOURCE_* 常量如下列出）。可通过该属性获知鼠标事件是否由真实鼠标设备触发，亦或通过触摸事件触发（这可能影响处理坐标事件时的精确程度）。
MouseEvent.webkitForce 只读: 点击时施加的压力量。
MouseEvent.x 只读: MouseEvent.clientX的别名。
MouseEvent.y 只读: MouseEvent.clientY的别名。

Properties of UIEvent

也继承了父代 Event 的一些属性。

UIEvent.cancelBubble: 返回一个 Boolean，表示该事件的冒泡是否被取消。

UIEvent.detail只读: Returns a long with details about the event, depending on the event type.
UIEvent.isChar 只读: 返回一个 Boolean，表示该事件是否产生了一个键盘字符（key character）。
UIEvent.layerX 只读: 返回事件相对于当前层的水平坐标。
UIEvent.layerY 只读: 返回事件相对于当前层的垂直坐标。
UIEvent.pageX 只读: 返回事件相对于整个文档的水平坐标。
UIEvent.pageY 只读: 返回事件相对于整个文档的垂直坐标。
UIEvent.sourceCapabilities 只读: 返回输入设备功能接口的一个实例，它提供有关负责生成 touch 事件的物理设备的信息。
UIEvent.view只读: 返回一个包含了产生该事件的视图的 WindowProxy 。
UIEvent.which 只读: 返回一个对应（键盘）按下的数字类型的 keyCode ，或者一个字母数字键按下时的字符码(charCode)。

Properties of `Event`

Event.bubbles 只读: 一个布尔值，用来表示该事件是否会在 DOM 中冒泡。
Event.cancelBubble: Event.stopPropagation() 的历史别名。在事件处理器函数返回之前，将此属性的值设置为 true，亦可阻止事件继续冒泡。
Event.cancelable 只读: 一个布尔值，表示事件是否可以取消。
Event.composed 只读: 一个布尔值，表示事件是否可以穿过 Shadow DOM 和常规 DOM 之间的隔阂进行冒泡。
Event.currentTarget 只读: 对事件当前注册的目标的引用。这是一个当前计划将事件发送到的对象。它是有可能在重定向的过程中被改变的。
Event.deepPath: 一个由事件流所经过的 DOM 节点组成的数组。
Event.defaultPrevented 只读: 一个布尔值，表示 event.preventDefault() 方法是否取消了事件的默认行为。
Event.eventPhase 只读: 表示事件流正被处理到了哪个阶段。
Event.explicitOriginalTarget 只读: 事件的明确（explicit）原始目标（Mozilla 专有属性）。
Event.originalTarget 只读: 重设目标前的事件原始目标（Mozilla 专有属性）。
Event.returnValue: 旧版 Internet Explorer 引入的一个非标准历史属性，为保证依赖此属性的网页正常运作，此属性最终被收入规范。可用 Event.preventDefault() 与 Event.defaultPrevented 代替，但由于已进入规范，也可以使用此属性。
Event.srcElement: 旧版 Internet Explorer 对 Event.target 的非标准别称。出于兼容原因，一些其他浏览器也支持此别称。
Event.target 只读: 对事件原始目标的引用，这里的原始目标指最初派发（dispatch）事件时指定的目标。
Event.timeStamp 只读: 事件创建时的时间戳（精度为毫秒）。按照规范，这个时间戳是 Unix 纪元起经过的毫秒数，但实际上，在不同的浏览器中，对此时间戳的定义也有所不同。另外，规范正在将其修改为 DOMHighResTimeStamp。
Event.type 只读: 事件的类型，不区分大小写。
Event.isTrusted 只读: 表示事件是由浏览器（例如用户点击）发起的，还是由脚本（使用事件创建方法，例如 Event.initEvent）发出的。

废弃属性
Event.scoped 只读: 已废弃，使用 Event.composed 代替此属性。
一个布尔值，表示给定的事件是否会穿过 Shadow DOM，进入到标准 DOM 中。

方法

滚轮事件实现了以下事件的方法： WheelEvent, MouseEvent, UIEvent and Event.

Methods of WheelEvent

该接口本身未定义方法，但继承了父接口MouseEvent、UIEvent、Event的方法。

Methods of MouseEvent

这个接口也继承了它的副方法UIEvent 和Event.

MouseEvent.getModifierState(): 返回指定修饰键的当前状态。请参照KeyboardEvent.getModifierState() 查看详情。
MouseEvent.initMouseEvent(): 初始化创建MouseEvent的值。如果这个事件已经被分派，这个方法将不会做任何事情。

Methods of UIEvent

也继承了父代 Event 的一些方法。

UIEvent.initUIEvent(): 初始化一个 UIEvent 对象。如果事件已经被分派，这个方法什么都不做。

Methods of Event

Event.createEvent(): 创建一个新事件，如果使用此方法创建事件，则必须调用其自身的 initEvent() 方法，对其进行初始化。
Event.composedPath(): 返回事件的路径（将在该对象上调用监听器）。如果阴影根节点 (shadow root) 创建时 ShadowRoot.mode 值为 closed，那么路径不会包括该根节点下阴影树 (shadow tree) 的节点。
event.initEvent: 为通过 Event.createEvent() 创建的事件初始化。该方法对已经被派发的事件无效。
event.preventDefault: 取消事件（如果该事件可取消）。
event.stopImmediatePropagation: 对这个特定的事件而言，没有其他监听器被调用。这个事件既不会添加到相同的元素上，也不会添加到以后将要遍历的元素上（例如在捕获阶段）。
event.stopPropagation: 停止冒泡，阻止事件在 DOM 中继续冒泡。

废弃方法

Event.getPreventDefault(): 非标准方法；使用 Event.defaultPrevented 属性代替此方法。
返回 Event.defaultPrevented 的值。
event.preventBubble 已废弃 Gecko 24: 已废弃；使用 event.stopPropagation 代替此方法。
阻止事件继续冒泡。
event.preventCapture 已废弃 Gecko 24: 已废弃；使用 event.stopPropagation 代替此方法。

规范

Specification	Status	Comment
Document Object Model (DOM) Level 3 Events Specification wheel	Obsolete	Initial definition.

浏览器兼容性

BCD tables only load in the browser

跨浏览器监听滚动事件

以下脚本创建了一个全局的 addWheelListener 方法，它可以兼容各浏览器监听滚动事件，并且阻止默认行为。

// creates a global "addWheelListener" method
// example: addWheelListener( elem, function( e ) { console.log( e.deltaY ); e.preventDefault(); } );
(function(window,document) {

    var prefix = "", _addEventListener, onwheel, support;

    // detect event model
    if ( window.addEventListener ) {
        _addEventListener = "addEventListener";
    } else {
        _addEventListener = "attachEvent";
        prefix = "on";
    }

    // detect available wheel event
    support = "onwheel" in document.createElement("div") ? "wheel" : // 各个厂商的高版本浏览器都支持"wheel"
              document.onmousewheel !== undefined ? "mousewheel" : // Webkit 和 IE一定支持"mousewheel"
              "DOMMouseScroll"; // 低版本firefox

    window.addWheelListener = function( elem, callback, useCapture ) {
        _addWheelListener( elem, support, callback, useCapture );

        // handle MozMousePixelScroll in older Firefox
        if( support == "DOMMouseScroll" ) {
            _addWheelListener( elem, "MozMousePixelScroll", callback, useCapture );
        }
    };

    function _addWheelListener( elem, eventName, callback, useCapture ) {
        elem[ _addEventListener ]( prefix + eventName, support == "wheel" ? callback : function( originalEvent ) {
            !originalEvent && ( originalEvent = window.event );

            // create a normalized event object
            var event = {
                // keep a ref to the original event object
                originalEvent: originalEvent,
                target: originalEvent.target || originalEvent.srcElement,
                type: "wheel",
                deltaMode: originalEvent.type == "MozMousePixelScroll" ? 0 : 1,
                deltaX: 0,
                deltaZ: 0,
                preventDefault: function() {
                    originalEvent.preventDefault ?
                        originalEvent.preventDefault() :
                        originalEvent.returnValue = false;
                }
            };

            // calculate deltaY (and deltaX) according to the event
            if ( support == "mousewheel" ) {
                event.deltaY = - 1/40 * originalEvent.wheelDelta;
                // Webkit also support wheelDeltaX
                originalEvent.wheelDeltaX && ( event.deltaX = - 1/40 * originalEvent.wheelDeltaX );
            } else {
                event.deltaY = originalEvent.detail;
            }

            // it's time to fire the callback
            return callback( event );

        }, useCapture || false );
    }

})(window,document);

Gecko notes

滚轮事件和其它的鼠标滚动事件

如果一个用户真实操作触发的滚轮事件没有被处理, 这会触发一个 DOMMouseScroll 事件和一个 MozMousePixelScroll 事件以向下兼容. 它们的属性值由滚轮事件delta值和最近的ancestor clipped元素计算出。(i.e., overflow 不可见). 如果滚轮事件或其它任意一个剩余事件被 event.preventDefault()阻止, 将什么都不会发生。

以下为事件顺序:

滚轮事件处于默认事件组 (web应用和浏览器插件都可以处理这个组的事件)
当连续滚轮事件 deltaY 的值累计大于1或小于－1时，竖直方向的 DOMMouseScroll 事件既属于默认事件组也属于系统事件组
当最近的滚轮事件的 deltaY 值非零时，两个事件组都包含竖直方向的 MozMousePixelScroll 事件
当连续滚轮事件 deltaX 的值累计大于1或小于－1时，两个事件组都包含水平方向的 DOMMouseScroll 事件
当最近的滚轮事件的 deltaX 值非零时，两个事件组都包含水平方向的 MozMousePixelScroll 事件
一个滚轮事件处于系统事件组 (只有浏览器插件可以处理这个组的事件)

`各个事件调用 preventDefault()` 会发生什么？
`wheel` (default event group)	`preventDefault()` called
`DOMMouseScroll` (Vertical)	Not fired	`preventDefault()` called
`MozMousePixelScroll` (Vertical)	Not fired	`defaultPrevented` is true	`preventDefault()` called
`DOMMouseScroll` (Horizontal)	Not fired	Not affected	Not affected	`preventDefault()` called
`MozMousePixelScroll` (Horizontal)	Not fired	Not affected	Not affected	`defaultPrevented` is true	`preventDefault()` called
`wheel` (system event group)	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true	`defaultPrevented` is true

如果一个浏览器插件需要知道剩余事件是否被web内容所处理，它可以使用第6个滚轮事件判断，详细内容请查阅系统事件组 nsIEventListenerService 的文档。

通过设置用户偏好可以修改delta值和默认行为 (details)，因此开发者不应该期望在处理这个事件后发生特殊的行为。

delta 值

delta 值并不代表默认情况下的实际滚动值，如果用户在滚动滚轮时按住其他键，可能会产生其他行为，比如在浏览记录中前进／回退，或者放大／缩小网页内容。此外，滚动过程中被滚动的元素不一定是目标元素，滚轮事件的目标元素是由事件触发时光标所在位置计算出的。 That event may not only not be the one actually being scrolled, 甚至都不可滚动。

deltaMode 值

在 Windows 下, 以下三个原生事件造成了 DOM 滚轮事件。

WM_MOUSEWHEEL (竖直方向的滚动事件): deltaMode 值可以是 DOM_DELTA_LINE 或 DOM_DELTA_PAGE。它取决于 Windows 的用户设置 (默认设置为 DOM_DELTA_LINE)。
WM_MOUSEHWHEEL (水平方向的滚动事件): deltaMode 值可以是 DOM_DELTA_LINE 或 DOM_DELTA_PAGE。然而 Windows 的滚轮速度设置界面和鼠标驱动工具都没有提供改为 page scroll 的选项。所以这个值通常为 DOM_DELTA_LINE.
WM_GESTURE (Only when caused by panning): deltaMode 值总是 DOM_DELTA_PIXEL。但请注意大多数笔记本的触摸板都在模拟鼠标滚轮事件而不是调用这个事件， WM_GESTURE 事件通常被平板电脑使用。

在 Mac 下 deltaMode 值由设备决定. 如果设备支持高分辨率像素级滚动, deltaMode 值就是典型的 DOM_DELTA_PIXEL. 然而用户可以通过加前缀"mousewheel.enable_pixel_scrolling"将其改变为 DOM_DELTA_LINE 。如果设备不支持高分辨率滚动，那么 deltaModel 值将一直为 DOM_DELTA_LINE.

在其它平台下， deltaMode 值总是 DOM_DELTA_LINE.