滚轮事件

翻译不完整。 请帮助我们翻译这篇文章!

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

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

概要

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

属性

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

Properties of WheelEvent

该接口继承了父接口MouseEventUIEventEvent的属性。

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

方法

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

Methods of WheelEvent

该接口本身未定义方法,但继承了父接口MouseEventUIEventEvent的方法。

Methods of MouseEvent

这个接口也继承了它的副方法UIEventEvent.

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

Methods of UIEvent

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

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

Methods of Event

规范

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

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
wheel eventChrome Full support 61Edge Full support 12Firefox Full support 17IE Full support 9
Notes
Full support 9
Notes
Notes Internet Explorer only exposes the wheel event via addEventListener; there is no onwheel attribute on DOM objects. See IE bug 782835.
Opera Full support 48Safari Full support 7WebView Android Full support 61Chrome Android Full support 61Firefox Android Full support 17Opera Android Full support 45Safari iOS Full support 7Samsung Internet Android Full support 8.0

Legend

Full support  
Full support
See implementation notes.
See implementation notes.

跨浏览器监听滚动事件

以下脚本创建了一个全局的 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()阻止, 将什么都不会发生。

以下为事件顺序:

  1. 滚轮事件处于默认事件组 (web应用和浏览器插件都可以处理这个组的事件)
  2. 当连续滚轮事件 deltaY 的值累计大于1或小于-1时,竖直方向的 DOMMouseScroll 事件既属于默认事件组也属于系统事件组
  3. 当最近的滚轮事件的 deltaY 值非零时,两个事件组都包含竖直方向的 MozMousePixelScroll 事件
  4. 当连续滚轮事件 deltaX 的值累计大于1或小于-1时,两个事件组都包含水平方向的 DOMMouseScroll 事件
  5. 当最近的滚轮事件的 deltaX 值非零时,两个事件组都包含水平方向的 MozMousePixelScroll 事件
  6. 一个滚轮事件处于系统事件组 (只有浏览器插件可以处理这个组的事件)
各个事件调用 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.

Untrusted events

非用户真实操作触发的滚轮事件不会引发默认行为。

参考