MouseArea QML Type

这些属性包含鼠标光标的坐标。

如果hoverEnabled 属性为 false，那么这些属性只有在按下按钮时才有效，而且只要按住按钮，即使鼠标移动到区域外，这些属性也将保持有效。

默认情况下，该属性为 false。

如果hoverEnabled 为 true，这些属性将在以下情况下有效：

• 未按下按钮，但鼠标位于MouseArea 内（containsMouse 为 true）。
• 按下并按住一个按钮，即使该按钮已移出该区域。

坐标相对于MouseArea 。

该属性包含鼠标区域会做出反应的鼠标按钮。

要指定MouseArea 对多个按钮做出反应，Qt::MouseButtons 标志值可使用"|"（或）运算符组合：

MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

要表示接受所有可能的鼠标按钮，可以使用特殊值 "Qt.AllButtons"：

MouseArea { acceptedButtons: Qt.AllButtons }

默认值是Qt.LeftButton 。

该属性表示鼠标当前是否位于鼠标区域内。

这是一个方便的属性，等同于pressed && containsMouse ，也就是说，它可以确定当前是否有任何acceptedButtons 被按下，且鼠标当前位于MouseArea 内。

当鼠标在项目范围内按下时，该属性对突出显示项目特别有用。

另请参阅 pressed 和containsMouse 。

该属性用于保存该鼠标区域的光标形状。请注意，在不显示鼠标光标的平台上，该属性可能不起作用。

可用的光标形状有

• Qt.ArrowCursor
• Qt.UpArrowCursor 上箭头光标
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

为了只为一个区域设置鼠标光标形状而不对鼠标事件做出反应，请将acceptedButtons 设置为 none：

MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }

默认值为Qt.ArrowCursor 。

另请参阅 Qt::CursorShape 。

drag 提供了一种使项目可拖动的便捷方法。

• drag.target 指定要拖动的项目的 id。
• drag.active 指定目标项目当前是否正在被拖动。
• drag.axis 指定是否可以水平（ ）、垂直（ ）或两者（ ）拖动。Drag.XAxisDrag.YAxisDrag.XAndYAxis
• drag.minimum 和 限制目标项可以沿相应轴拖动的距离。drag.maximum

下面的示例显示了一个可以沿 X 轴拖动的Rectangle 。向右拖动时，矩形的不透明度会降低。

Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}

如果drag.filterChildren 设置为 true，拖动就可以覆盖后代的 MouseAreas。这样，父MouseArea 就可以处理拖动，而子代处理点击：

import QtQuick

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}

drag.threshold 决定拖动操作何时开始的阈值（以像素为单位）。默认情况下，该值与平台相关。该属性在 2.2 中添加。Qt Quick

如果drag.smoothed 为true ，则只有在拖动操作开始后才会移动目标。如果设置为false ，目标将直接移动到当前鼠标位置。默认情况下，此属性为true 。该属性在Qt Quick 2.4 中添加。

如果要进行拖放操作，请参阅Drag 附加属性和DropArea 。

该属性表示项目是否接受鼠标事件。

默认情况下，此属性为 true。

该属性用于确定是否处理悬停事件。

默认情况下，只有在响应按钮事件或按下按钮时才会处理鼠标事件。悬停可处理所有鼠标事件，即使没有按下鼠标按钮。

该属性会影响containsMouse 属性以及 onEntered、onExited 和 onPositionChanged 信号。

该属性可重置pressAndHold 发出前的经过时间（以毫秒为单位）。

如果未明确设置或重置后，该值将跟随QStyleHints::mousePressAndHoldInterval 。

通常情况下，使用应用程序样式提示全局设置该属性即可。当某些鼠标区域需要不同的时间间隔时，应使用此属性。

另请参见 pressAndHold 。

该属性显示acceptedButtons 当前是否被按下。

该属性显示当前按下的鼠标按钮。

它包含以下按位组合

• Qt.LeftButton
• Qt.RightButton
• Qt.MiddleButton

当鼠标右键被按下时，下面的代码会显示 "right"：

Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}

另请参阅 acceptedButtons 。

该属性用于确定鼠标事件是否可以从MouseArea 中窃取。

如果MouseArea 位于可过滤子鼠标事件的项目（如 Flickable）中，则如果父项目识别到手势（如轻移手势），鼠标事件可能会从MouseArea 中窃取。如果将 preventStealing 设为 true，则任何项目都不会窃取鼠标事件。

请注意，一旦某个项目开始窃取事件，将 preventStealing 设置为 true 将不会有任何效果，直到下一次按下事件发生。

默认情况下，此属性为 false。

该属性表示组成的鼠标事件是否会自动传播到与该MouseArea 重叠但在视觉堆叠顺序中较低的其他 MouseAreas。默认情况下，该属性为 false。

MouseArea 鼠标区域包含多个组成事件： 和 。这些事件由基本鼠标事件组成，如 ，传播方式与基本事件不同。clicked doubleClicked pressAndHold pressed

如果 propagateComposedEvents 设置为 true，那么组成事件将自动传播到场景中相同位置的其他 MouseAreas。每个事件都会按照堆叠顺序传播到它下面的下一个enabled MouseArea ，一直向下传播，直到MouseArea 接受该事件为止。与pressed 事件不同，如果没有处理程序，组成的事件不会被自动接受。

例如，下面是一个包含蓝色Rectangle 的黄色Rectangle 。蓝色矩形是可视堆叠顺序层次结构中最顶层的项目；它将在视觉上呈现在黄色矩形之上。由于蓝色矩形将 propagateComposedEvents 设置为 true，并将所有接收到的clicked 事件的MouseEvent::accepted 设置为 false，因此它接收到的任何clicked 事件都会传播到其下方黄色矩形的MouseArea 。

import QtQuick 2.0

Rectangle {
    color: "yellow"
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

单击蓝色矩形将调用其子MouseArea 的onClicked 处理程序；然后该事件将传播到黄色矩形的MouseArea ，从而调用其自身的onClicked 处理程序。

当你想让重叠的 MouseAreas 一起处理组成的事件时，这个属性大大简化了使用情况。例如：希望一个MouseArea 处理clicked 信号，另一个处理pressAndHold ，或者希望一个MouseArea 在大部分时间处理clicked ，但在满足特定条件时将其传递给另一个。

该属性控制MouseArea 是否响应非鼠标设备的滚动手势，例如触控板上的双指轻弹手势。如果设置为 false，则只有当滚轮事件来自带滚轮的实际鼠标时，才会发出wheel 信号，而滚动手势事件将传递给其他任何可以处理这些事件的 Item。例如，当光标位于一个包含MouseArea 的项目上方时，用户可能会执行一个轻移手势，目的是与下方的 Flickable 进行交互。将此属性设置为 false 将允许PinchArea 处理鼠标滚轮或捏合手势，而由 Flickable 处理轻移手势。

默认情况下，该属性为 true。

当鼠标事件被取消，因为另一个项目抢走了鼠标事件处理权时，就会发出该信号。

该信号用于高级用途：当有不止一个MouseArea 在处理输入时，或当Flickable 内有一个MouseArea 时，该信号就很有用。在后一种情况下，如果您在onPressed 信号处理程序中执行了某些逻辑，然后开始拖动，Flickable 就会从MouseArea 中窃取鼠标处理。在这些情况下，当MouseArea 失去了对Flickable 的鼠标处理时，要重置逻辑，除了处理released 外，还应该处理canceled 。

该信号在出现点击时发出。点击被定义为按下后释放，且都在MouseArea 内（按下后移动到MouseArea 外，然后移动回 内并释放也被视为点击）。

mouse 参数提供了有关单击的信息，包括单击释放时的 x 和 y 位置，以及单击是否被保持。

处理此信号时，除非propagateComposedEvents 属性为true ，否则更改mouse 参数的accepted 属性不会有任何影响。

当出现双击（按下后释放，再按下）时，就会发出该信号。mouse 参数提供有关点击的信息，包括释放点击时的 x 和 y 位置，以及点击是否被按住。

处理该信号时，如果mouse 参数的accepted 属性设置为 false，则第二次点击时将发出按下/释放/点击信号；否则将被抑制。accepted 属性默认为 true。

该信号在鼠标进入鼠标区域时发出。

默认情况下，只有当前按下按钮时才会发出该信号。将hoverEnabled 设置为 true，即使没有按下鼠标按钮也会发出该信号。

另请参阅 hoverEnabled 。

当鼠标退出鼠标区域时会发出该信号。

默认情况下，只有当前按键被按下时才会发出该信号。将hoverEnabled 设置为 true，即使没有按下鼠标按钮也会发出该信号。

下面的示例显示了两个 MouseAreas（鼠标区域）之间相当典型的关系，mouseArea2 位于mouseArea1 的顶部。将鼠标从mouseArea1 移入mouseArea2 会导致mouseArea1 发出exited 信号。

Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}

如果给这两个 MouseAreas 赋予父子关系，从mouseArea1 将鼠标移动到mouseArea2 将不会导致mouseArea1 发出exited 信号。相反，它们将被视为同时悬停。

另请参阅 hoverEnabled 。

该信号在鼠标位置发生变化时发出。

mouse 参数提供了有关鼠标的信息，包括 x 和 y 位置，以及当前按下的任何按钮。

默认情况下，只有当前有按钮被按下时才会发出该信号。将hoverEnabled 设置为 true，即使没有按下鼠标按钮也会发出该信号。

处理此信号时，更改mouse 参数的accepted 属性不会产生任何影响。

长按时（当前为 800ms）会发出该信号。mouse 参数提供了有关按压的信息，包括按压的 x 和 y 位置以及按压的按钮。

处理该信号时，除非propagateComposedEvents 属性为true ，否则更改mouse 参数的accepted 属性不会有任何影响。

按下按钮时会发出该信号。mouse 参数提供了按下按钮的信息，包括 x 和 y 位置以及按下的按钮。

处理此信号时，可使用mouse 参数的accepted 属性来控制MouseArea 是否处理按下事件和所有未来的鼠标事件，直到释放为止。默认情况下，接受该事件，不允许该鼠标区域下面的其他鼠标区域处理该事件。如果接受设置为 false，则不会再向该MouseArea 发送任何事件，直到下一次按下按钮。

释放按钮时会发出该信号。mouse 参数提供了有关点击的信息，包括点击释放的 x 和 y 位置，以及点击是否被保持。

处理此信号时，更改mouse 参数的accepted 属性不会产生任何影响。

另请参阅 canceled 。

该信号是对鼠标滚轮和触控板滚动手势的响应。

wheel 参数提供了事件的相关信息，包括 x 和 y 位置、当前按下的任何按钮以及滚轮移动的相关信息（包括 angleDelta 和 pixelDelta）。