QML类型——MouseArea

正文

MouseArea鼠标事件处理区域。

详细介绍

MouseArea是不可见的对象，通常与可见对象结合使用，以便为该项目提供鼠标事件处理。
enabled属性用于开启和禁用鼠标操作，禁用时，鼠标区域无法响应所有鼠标事件。
虽然MouseArea是不可见的对象，但是具有visible属性，设置为false时，鼠标区域无法响应所有鼠标事件。
pressed只读属性标识着当前鼠标是否有按下操作。此属性通常用于用户界面中属性之间的绑定。
containsMouse只读属性标识着鼠标光标是否在鼠标区域内；默认情况下，只有在按住鼠标时才会有效。
最常用的是涉及到鼠标点击的事件：onClicked,onDoubleClicked,onPressed,onReleased和onPressAndHold。还有onWheel获取鼠标滚轮事件。
当鼠标区域与其他鼠标区域重叠，可以通过将propertyComposedEvents设置为true，将鼠标的基本事件自动传递给相同位置的其他MouseArea对象。

示例：（在一个Rectangle中使用MouseArea，单击矩形使其变成红色）

import QtQuick 2.0

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: {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

属性介绍

• mouseX: real
• mouseY: real
  两个属性为鼠标光标的坐标。
  如果hoverEnabled属性为false，则这些属性仅在按下按钮时才有效，并且即使将鼠标移动到该区域外，只要按住该按钮，这些属性将一直有效。（默认情况下为false）
  如果hoverEnabled为true，则两个属性将在以下情况下有效：
  1.没有按钮按下，但是鼠标在MouseArea区域内（containsMouse为true）。
  2.即使按钮移出该区域，也一直按住按钮。
  注意：坐标是相对于MouseArea的
• acceptedButtons: Qt::MouseButtons
  指定MouseArea接受响应的鼠标按钮类型。
  如果要对多个按钮做出响应，使用“|”组合Qt::MouseButtons。

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

如果要对所有鼠标按钮做出响应，则使用特殊值“Qt.AllButtons”。

MouseArea { acceptedButtons: Qt.AllButtons }

默认值为Qt.LeftButton。

• containsMouse: bool
  此属性判断当前鼠标是否在MouseArea区域内。
  警告：如果hoverEnabled为false，则只有当鼠标光标在MouseArea内按下鼠标按钮时，containsMouse才有效。
• containsPress: bool
  此属性相当于组合属性（pressed && containsMouse），即判断当前按下鼠标按钮且鼠标光标位于MouseArea中。
  此属性对于鼠标在MouseArea范围内按下时突出显示一个项目特别有用。
• cursorShape: Qt::CursorShape
  此属性指定鼠标光标在MouseArea内的形状。
  可用的光标形状有：
  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
  样式图：
  [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-GV60wEwG-1594801841141)(leanote://file/getImage?fileId=5f0d1d4450f7571d32000005)]
  如果只为MouseArea设置鼠标光标形状，而不响应鼠标事件，则将acceptedButtons设置为none。

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

默认值为Qt.ArrowCursor。

• drag group
• drag.active: bool
• drag.axis: enumeration
• drag.filterChildren: bool
• drag.maximumX: real
• drag.maximumY: real
• drag.minimumX: real
• drag.minimumY: real
• drag.target: Item
• drag.threshold: real
  drag提供了一种使元素对象可拖动的方法。
  drag.target 指定了要拖动的对象ID
  drag.active 指定当前是否拖动目标。
  drag.axis 指定是否可以水平（Drag.XAxis），垂直（Drag.YAxis）或任意方向（Drag.XAndYAxis）进行拖动。
  drag.minimum和drag.maximum 限制可以沿着相应方向拖动目标的距离。
  下面示例显示一个可以沿着X轴拖动的矩形，当矩形向右拖动时，其不透明度会降低：

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.axis方向拖动。例如，如果在上例中将rect设置为anchors.left或anchors.right，则该对象无法沿着X轴拖动。通过在onPressed处理程序中将anchor值设置为undefined可以避免此情况。
如果drag.filterChildren设置为true，则拖动可以覆盖后面的MouseArea。如下示例，使父MouseArea可以拖动，而子MouseArea处理点击。
drag.threshold指定了确定开始拖动操作的阈值（以像素为单位）。默认情况下，这和平台相关。
如果drag.smoothed为true，则只有在拖动操作结束后，才会移动目标。如果设置为false，则目标将直接移动到当前鼠标的位置。默认值为true。
如果要处理放置操作，可以参考Drag和DropArea

import QtQuick 2.0

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")
                }
            }
        }
    }
}

• enabled: bool
  此属性指定当前对象是否接受鼠标事件。
  注意：由于历史原因，此属性不等同于Item.enabled。它仅影响鼠标事件，并且不会影响到子项。
  默认值为true。

• hoverEnabled: bool
  此属性指定对于是否处理鼠标悬停事件。
  默认情况下，仅响应于按钮事件或按下按钮时处理鼠标事件。悬停可以处理所有鼠标事件，即使没有按下鼠标按钮。
  此属性影响containsMouse属性以及onEntered,onExited和onPositionChanged信号。

• pressAndHoldInterval: int
  此属性会覆盖在发出pressAndHold之前经过的时间（以毫秒为单位）。
  如果没有明确的设置（或者后续重置），则该值会和QStyleHints::mousePressAndHoldInterval保持一致。
  通常，利用应用程序样式来全局设置此属性就够了。当某些MouseArea需要不同的时间间隔时，应设置此属性。

• pressed: bool
  此属性判断当前是否按下了任何按钮（acceptedButtons）。

• pressedButtons:MouseButtons
  此属性指定当前按下的鼠标按钮类型：
  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
    }
}

• preventStealing: bool
  此属性指定了是否可以从MouseArea截取鼠标事件。
  如果在MouseArea中加入过滤子级的鼠标事件（例如Flickable），则鼠标事件可能会被截取。
  如果父对象识别到任意动作（事件），将preventStealing设置为true，则不会截取鼠标事件。
  注意：当某对象开始截取事件时，将preventStealing设置为true，直到下一次按下事件才会生效。
  默认值为false。
• propagateComposedEvents: bool
  此属性指定在MouseArea对象出现重叠的情况下，鼠标事件是否可以传递到下层。默认为false。
  MouseArea包含多个组合事件：clicked,doubleClicked和pressAndHold，它们由基本的鼠标事件（如pressed）组成，并且与基本事件相比可以，传播方式有所不同。
  如果此属性设置为true，则组合事件将自动传递到场景中相同位置的其他MouseArea。每个事件将按照堆栈顺序传递到下一个有效MouseArea，并向下传递此可视层次结构，直到最后一个MouseArea接受该事件为止。与pressed事件不同，如果没有处理程序，组合事件将不会被自动接受。
  例如，下面是黄色的矩形包含一个蓝色的矩形。蓝色矩形是视觉堆栈层次中最顶层的对象，它将在黄色矩形上方直观的呈现。由于蓝色矩形将propagateComposedEvents设置为true，并且将所有接收到单击事件的对象MouseEvent::accepted设置为false，因此它将接收到的所有单击事件都传递到下方黄色矩形中。
  MouseEvent::accepted为true时表示鼠标事件不会往下传递。

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: {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

单击蓝色矩形将导致其子MouseArea对象的onClicked处理函数被调用；然后该事件传递到黄色矩形的MouseArea，触发onClicked处理程序。
此属性大大简化了处理重叠MouseArea的组合事件。例如，如果要一个MouseArea处理clicked信号，而另一个处理pressAndHold信号，或者是一个MouseArea正常情况下处理clicked信号，但是在特殊条件下将其传递出去。

• scrollGestureEnabled: bool
  此属性指定了当前MouseArea是否响应非鼠标设备的滚动事件，例如触控板上的2指轻弹手势。

信号

• canceled()
  取消鼠标事件后发送的信号，因为另一个对象截取了鼠标事件。
  该信号的用途：当有多个处理输入的MouseArea或Flickable内部有一个MouseArea时，该信号很有用。在后者情况下，如果您在onPressed信号处理程序中执行一些逻辑然后开始拖动，则Flickable将从MouseArea中截取鼠标事件。在此情况下，要在MouseArea对Flickable失去鼠标事件时重置逻辑，canceled需要另外处理released信号。
• clicked(mouse)
  鼠标点击时发送该信号。只有在同一个MouseArea内响应pressed和released才算一次点击（鼠标按下，移动到MouseArea外，然后移动进来，再释放也被认可为一次点击）。
  参数mouse提供了有关点击的信息，包含了点击释放的X和Y位置等。
  处理此信号时，更改mouse参数的accepted属性是无效的，除非propagateComposedEvents属性设置为true。
• doubleClicked(mouse)
  双击鼠标时发送该信号。
  处理此信号时，如果将mouse参数的accepted属性设置为false，则第二次单击时将发送pressed/released/clicked信号。
• entered()
  当鼠标进入MouseArea区域时，发送该信号。
  默认为false，仅在当前按下按钮时才会发送该信号。设置为true时，鼠标进入即可发送信号。
• exited()
  当鼠标离开MouseArea区域时，发送该信号。
  默认为false，仅在按下鼠标按钮且移出MouseArea区域或者在MouseArea区域内点击时会发送信号。设置为true时，即使没有点击，只要鼠标移出MouseArea区域也会发送信号。
  下面示例中显示两个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信号。相反，它们将被视为同事hovered。

• positionChanged(mouse)
  鼠标位置改变时发送该信号。
  默认情况下，仅在按下按钮时才会发送该信号；将hoverEnabled设置为true才会发送该信号，即使没有按钮鼠标按钮。
  处理该信号时，更改mouse参数的accepted属性无效。
• pressAndHold(mouse)
  长按（默认为800毫秒）时发送该信号。
  处理该信号，改变mouse参数的accepted属性是无效的，除非propagateComposedEvents属性为true。
• pressed(mouse)
  按下时发送该信号。
  处理该信号时，通过设置mouse参数的accepted属性来控制当前MouseArea是否处理pressed以及所有后续的鼠标事件，直到释放为止。
  accepted默认为true，无法处理该MouseArea的其他事件。如果设置accepted为false，则在下次按下按钮之前，不会响应该MouseArea对象的任何事件。
  处理函数：onPressed
• released(mouse)
  鼠标释放时发送信号。
  处理此信号时，更改mouse的accepted属性无效。
  处理函数：onReleased
• wheel(wheel)
  响应鼠标滚轮或触控板的滚动手势时发送信号。
  处理函数：onWheel