MouseArea QML Type

支持简单的鼠标操作。更多...

• 所有成员的列表，包括继承的成员

属性

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : enumeration
  • drag.filterChildren : bool
  • drag.maximumX : real
  • drag.maximumY : real
  • drag.minimumX : real
  • drag.minimumY : real
  • drag.smoothed : bool
  • drag.target : Item
  • drag.threshold : real
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• pressAndHoldInterval : int
• pressed : bool
• pressedButtons : MouseButtons
• preventStealing : bool
• propagateComposedEvents : bool
• scrollGestureEnabled : bool

信号

• canceled()
• clicked(MouseEvent mouse)
• doubleClicked(MouseEvent mouse)
• entered()
• exited()
• positionChanged(MouseEvent mouse)
• pressAndHold(MouseEvent mouse)
• pressed(MouseEvent mouse)
• released(MouseEvent mouse)
• wheel(WheelEvent wheel)

详细说明

MouseArea 是一个不可见的项目，通常与可见项目配合使用，以便为该可见项目提供鼠标处理功能。通过有效充当代理，鼠标处理的逻辑可以封装在 MouseArea 项目中。

enabled 属性用于启用或禁用被代理项的鼠标处理功能。当禁用时，鼠标区域对鼠标事件变得透明。

MouseArea 是一个不可见的项，但它具有一个“visible”属性。当该属性设置为 false 时，鼠标区域对鼠标事件变为透明。

pressed 只读属性指示用户是否在鼠标区域上方按住鼠标按钮。该属性常用于用户界面中属性之间的绑定。containsMouse 只读属性指示鼠标光标是否位于鼠标区域上方，但默认情况下仅在按住鼠标按钮时生效；详情请参阅containsMouse 文档。

有关鼠标位置和按钮点击的信息是通过信号提供的，这些信号已定义了相应的事件处理程序属性。最常用的涉及处理鼠标按下和点击：onClicked、onDoubleClicked、onPressed、onReleased 和 onPressAndHold。还可以通过 onWheel 信号处理鼠标滚轮事件。

如果一个 MouseArea 与其他 MouseArea 项的区域重叠，您可以通过将propagateComposedEvents 设置为 true 并将应被传播的事件拒收，从而选择将clicked 、doubleClicked 和pressAndHold 事件传播到这些其他项。详情请参阅propagateComposedEvents 文档。

默认情况下，MouseArea 控件仅报告鼠标点击事件，而不报告鼠标光标位置的变化。设置hoverEnabled 属性可确保即使未按下任何鼠标按钮，系统也会使用为 onPositionChanged、onEntered 和 onExited 定义的处理程序，并更新containsMouse 属性。

用法示例

以下示例在Rectangle 中使用了一个MouseArea，当点击时会将Rectangle 的颜色更改为红色：

import QtQuick

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

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}

许多 MouseArea 信号会传递一个mouse 参数，其中包含有关鼠标事件的附加信息，例如位置、按钮以及任何键修饰符。

以下是前一个示例的扩展，当在该区域上右键单击时，会生成不同的颜色：

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

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

另请参阅 MouseEvent 、MouseArea 示例以及《Qt Quick - 用户输入》中的“重要概念”。

属性文档

acceptedButtons : Qt::MouseButtons

该属性用于指定鼠标区域响应的鼠标按钮。

若要指定MouseArea 对多个按钮作出响应，可使用“|”（或）运算符组合Qt::MouseButtons 标志值：

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

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

MouseArea { acceptedButtons: Qt.AllButtons }

默认值为Qt.LeftButton 。

containsMouse : bool [read-only]

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

containsPress : bool [read-only]

这是一个便利属性，等同于pressed && containsMouse ，即当acceptedButtons 中的任意一个按键当前被按下，且鼠标当前位于MouseArea 内时，该属性为真。

当鼠标在其边界内被按下时，此属性特别适用于突出显示某项。

另请参阅 pressed 和containsMouse 。

cursorShape : Qt::CursorShape

该属性存储此鼠标区域的光标形状。请注意，在不会显示鼠标光标的平台上，此属性可能无效。

可用的光标形状包括：

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitV光标
• Qt.SplitHCursor
• Qt.指手光标
• Qt.禁止光标
• Qt.什么是这个光标
• Qt.BusyCursor
• Qt.张开手形光标
• Qt.紧握手形光标
• Qt.拖拽复制光标
• Qt.拖动移动光标
• Qt.拖拽链接光标

若仅需为某个区域设置鼠标光标形状而不响应鼠标事件，请将acceptedButtons 设置为none：

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

默认值为Qt.ArrowCursor 。

另请参阅 Qt::CursorShape 。

drag group

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

• drag.target 指定要拖动的项的 ID。
• drag.active 指定目标项目当前是否正在被拖动。
• drag.axis 指定是否允许水平拖动（Drag.XAxis ）、垂直拖动（Drag.YAxis ）或两者兼有（Drag.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 确定拖动操作应开始时的阈值（以像素为单位）。默认情况下，该值与平台相关的数值绑定。此属性在Qt Quick 2.2 版本中新增。

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

若要实现拖放功能，请参阅Drag 关联属性以及DropArea 。

enabled : bool

该属性用于指定该项是否接受鼠标事件。

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

hoverEnabled : bool

该属性控制是否处理悬停事件。

默认情况下，仅在发生按钮事件或按下按钮时处理鼠标事件。启用“悬停”后，即使未按下任何鼠标按钮，也会处理所有鼠标事件。

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

这些属性存储鼠标光标的坐标。

如果hoverEnabled 属性为false，则这些属性仅在按下按钮时有效，并且只要按钮被按住，即使鼠标移出该区域，这些属性仍保持有效。

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

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

• 未按下任何按钮，但鼠标位于MouseArea 区域内（即containsMouse 为true）。
• 按下了某个按钮并持续按住，即使鼠标随后已移出该区域。

坐标是相对于MouseArea 的。

pressAndHoldInterval : int

此属性会覆盖在触发pressAndHold 之前已过去的毫秒数。

如果未显式设置——或在重置之后——该值将遵循 `QStyleHints::mousePressAndHoldInterval`。

通常，通过应用程序样式提示全局设置此属性即可满足需求。当某些 MouseAreas 需要不同的间隔时，应使用此属性。

另请参阅 pressAndHold 。

pressed : bool [read-only]

该属性用于指示当前是否按下了任何acceptedButtons 按键。

pressedButtons : MouseButtons [read-only]

该属性保存当前按下的鼠标按钮。

它包含以下属性按位组合：

• 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 。

preventStealing : bool

该属性用于控制是否可以从该MouseArea 中“截取”鼠标事件。

如果将MouseArea 放置在会过滤子元素鼠标事件的元素（如Flickable）之中，当父元素识别到手势（例如轻扫手势）时，鼠标事件可能会被从MouseArea 中“窃取”。如果将preventStealing设置为true，则没有任何元素会窃取鼠标事件。

请注意，一旦项目开始截取事件，将 `preventStealing` 设置为 `true` 不会立即生效，而需等到下一个按压事件发生时才生效。

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

propagateComposedEvents : bool

该属性决定组合鼠标事件是否会自动传播到与该MouseArea 重叠、但在视觉堆叠顺序中位于其下方的其他MouseAreas。默认情况下，该属性值为false。

MouseArea 包含若干组合事件：clicked 、doubleClicked 和pressAndHold 。这些事件由基本鼠标事件（如pressed ）组合而成，其传播方式可能与基本事件不同。

MouseArea 如果将 `propagateComposedEvents` 设置为 `true`，则复合事件将自动传播到场景中同一位置的其他 `MouseAreas`。 每个事件都会传播到堆叠顺序中位于其下方的下一个enabled （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 信号，但在满足特定条件时将其转发。

scrollGestureEnabled : bool

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

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

Signal 文档

canceled()

当鼠标事件被取消时，会触发此信号，因为另一个项目抢占了鼠标事件的处理权。

此信号适用于高级场景：当有多个MouseArea 正在处理输入时，或者当Flickable 内部包含一个MouseArea 时，该信号非常有用。 在后一种情况下，如果您在onPressed 信号处理程序中执行某些逻辑，然后开始拖动，Flickable 将从MouseArea 处截取鼠标处理权。在这些情况下，当MouseArea 因Flickable 而失去鼠标处理权时，为了重置该逻辑，除了处理released 外，还应处理canceled 。

clicked(MouseEvent mouse)

当发生点击时，会发出此信号。点击被定义为先按下再松开，且整个过程均发生在MouseArea 内（按下后移出MouseArea ，随后再次移回并松开也视为一次点击）。

mouse 参数提供有关点击的信息，包括点击释放时的 x 和 y 坐标，以及点击是否被按住。

在处理此信号时，除非propagateComposedEvents 属性为true ，否则更改mouse 参数的accepted 属性将不起作用。

doubleClicked(MouseEvent mouse)

当发生双击（先按下、松开，然后再次按下）时，会发出此信号。mouse 参数提供了有关该点击的信息，包括点击松开时的x和y坐标，以及点击是否被按住。

在处理此信号时，如果mouse 参数的accepted 属性设置为false，则第二次点击时会发出pressed/released/clicked信号；否则这些信号将被抑制。accepted 属性的默认值为true。

entered()

当鼠标进入鼠标区域时，会触发此信号。

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

另请参阅 hoverEnabled 。

exited()

当鼠标移出鼠标区域时，会触发此信号。

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

下面的示例展示了一个相当典型的两个 MouseArea 之间的关系，其中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
    }
}

如果将这两个 MouseArea 设置为父子关系，则从mouseArea1 将鼠标移入mouseArea2 时，mouseArea1 不会触发exited 信号。相反，它们将被视为同时被悬停。

另请参阅 hoverEnabled 。

positionChanged(MouseEvent mouse)

当鼠标位置发生变化时，会发出此信号。

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

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

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

pressAndHold(MouseEvent mouse)

当发生长按（当前为800毫秒）时，会发出此信号。mouse 参数提供了有关按压的信息，包括按压的x和y坐标，以及被按下的按钮。

在处理此信号时，除非 `propagateComposedEvents ` 属性设置为 `true`，否则修改 `mouse ` 参数的 `accepted ` 属性将不会产生任何效果。

pressed(MouseEvent mouse)

当发生按键操作时，会发出此信号。mouse 参数提供了有关按键操作的信息，包括x和y坐标以及被按下的按钮。

处理此信号时，请使用mouse 参数的accepted 属性来控制该MouseArea 是否处理此次按键以及此后直至按键释放的所有鼠标事件。默认情况下，该区域会接受该事件，并禁止其下方的其他MouseAreas处理该事件。如果accepted设置为false，则直到下次按下该按钮之前，将不会向该MouseArea 发送任何进一步的事件。

released(MouseEvent mouse)

当发生释放操作时，会发出此信号。mouse 参数提供了有关点击的信息，包括点击释放时的x和y坐标，以及点击是否被按住。

在处理此信号时，修改mouse 参数的accepted 属性不会产生任何效果。

另请参阅 canceled 。

wheel(WheelEvent wheel)

该信号是在鼠标滚轮和触控板滚动手势触发时发出的。

wheel 参数提供了有关该事件的信息，包括x和y坐标、当前按下的按钮，以及关于滚轮移动的信息，包括angleDelta和pixelDelta。