MouseArea 是 QML 中用于处理鼠标交互的核心组件，它为可视项目提供鼠标事件处理能力。作为不可见项目， MouseArea 通常需要与可见项目配合使用，将鼠标交互逻辑与视觉表现分离。

核心特性详解

1. 基本属性

import QtQuick 2.15

Rectangle {
    width: 200
    height: 100
    color: "lightblue"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        enabled: true  // 默认为true，设为false将禁用鼠标事件

        // 只读属性
        property bool isPressed: pressed
        property bool containsMouse: containsMouse
    }

    Text {
        text: mouseArea.pressed ? "按下" : "释放"
        anchors.centerIn: parent
    }
}

2. 鼠标事件信号处理

Rectangle {
    width: 300
    height: 150
    color: mouseArea.containsMouse ? "#e0e0e0" : "white"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        hoverEnabled: true  // 启用悬停检测

        onClicked: {
            console.log("单击 at", mouse.x, mouse.y)
        }

        onDoubleClicked: {
            console.log("双击 at", mouse.x, mouse.y)
        }

        onPressed: {
            console.log("按下 按钮:", mouse.button)
        }

        onReleased: {
            console.log("释放 at", mouse.x, mouse.y)
        }

        onPressAndHold: {
            console.log("长按 at", mouse.x, mouse.y)
        }

        onPositionChanged: {
            console.log("移动:", mouse.x, mouse.y)
        }

        onEntered: console.log("鼠标进入")
        onExited: console.log("鼠标离开")
    }
}

高级应用示例

1. 拖拽实现

import QtQuick 2.15

Item {
    width: 400
    height: 300

    Rectangle {
        id: draggable
        width: 100
        height: 60
        color: "tomato"
        radius: 5

        MouseArea {
            id: dragArea
            anchors.fill: parent
            drag.target: parent
            drag.axis: Drag.XAndYAxis
            drag.minimumX: 0
            drag.minimumY: 0
            drag.maximumX: parent.parent.width - parent.width
            drag.maximumY: parent.parent.height - parent.height

            onPressed: parent.z++
            onReleased: parent.z--
        }

        Text {
            text: "拖拽我"
            anchors.centerIn: parent
        }
    }
}

2. 组合鼠标事件

Rectangle {
    width: 200
    height: 200
    color: "lightgreen"

    property point clickPos: Qt.point(0, 0)

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

        onClicked: {
            clickPos = Qt.point(mouse.x, mouse.y)

            if (mouse.button === Qt.LeftButton) {
                console.log("左键点击 at", mouse.x, mouse.y)
            } else if (mouse.button === Qt.RightButton) {
                console.log("右键点击 at", mouse.x, mouse.y)
            }
        }

        onWheel: {
            console.log("滚轮 delta:", wheel.angleDelta)
            if (wheel.angleDelta.y > 0) {
                parent.rotation += 5
            } else {
                parent.rotation -= 5
            }
        }
    }

    Rectangle {
        width: 10; height: 10
        radius: 5
        color: "red"
        x: clickPos.x - width/2
        y: clickPos.y - height/2
    }
}

3. 高级悬停效果

import QtQuick 2.15
import QtGraphicalEffects 1.15

Item {
    width: 300
    height: 200

    Rectangle {
        id: button
        width: 120
        height: 40
        anchors.centerIn: parent
        color: "#3498db"
        radius: 5

        Text {
            text: "悬停按钮"
            color: "white"
            anchors.centerIn: parent
            font.pixelSize: 14
        }

        MouseArea {
            id: ma
            anchors.fill: parent
            hoverEnabled: true
            cursorShape: Qt.PointingHandCursor
        }
    }

    DropShadow {
        anchors.fill: button
        source: button
        horizontalOffset: 0
        verticalOffset: ma.containsMouse ? 3 : 0
        radius: ma.containsMouse ? 8 : 5
        samples: 16
        color: "#80000000"
        Behavior on verticalOffset { NumberAnimation { duration: 100 } }
        Behavior on radius { NumberAnimation { duration: 100 } }
    }

    states: [
        State {
            when: ma.containsMouse
            PropertyChanges { target: button; color: "#2980b9" }
        }
    ]

    transitions: [
        Transition {
            ColorAnimation { duration: 200 }
        }
    ]
}

实战技巧

1. 性能优化 ：

   MouseArea {
       propagateComposedEvents: true  // 允许事件传递给下层MouseArea
       preventStealing: true  // 防止事件被窃取
   }
   

2. 多按钮处理 ：

   MouseArea {
       acceptedButtons: Qt.LeftButton | Qt.MiddleButton | Qt.RightButton
       onClicked: {
           if (mouse.button === Qt.MiddleButton) {
               console.log("中键点击")
           }
       }
   }
   

3. 组合键检测 ：

   MouseArea {
       onClicked: {
           if (mouse.modifiers & Qt.ShiftModifier) {
               console.log("Shift+点击")
           }
       }
   }
   

4. 自定义光标 ：

   MouseArea {
       cursorShape: Qt.DragCopyCursor
       // 或者使用自定义光标图像
       // cursorShape: Qt.BlankCursor
       // Canvas { ... }  // 自定义绘制光标
   }
   

常见问题解决方案

1. MouseArea 不响应 ：

2. 精准点击区域控制 ：

   MouseArea {
       shape: Qt.size(width, height)  // 精确点击区域
       containsMouse: shape.contains(mouseX, mouseY)
   }
   

3. 多层 MouseArea 处理 ：

   Item {
       MouseArea {
           id: topLayer
           anchors.fill: parent
           onClicked: console.log("顶层处理")
       }
   
       MouseArea {
           anchors.centerIn: parent
           width: 100; height: 100
           onClicked: {
               console.log("内层处理")
               mouse.accepted = false  // 允许事件继续传递
           }
       }
   }
   

总结

MouseArea 是 QML 中处理鼠标交互的核心组件，通过掌握其特性和使用技巧，开发者可以实现：

理解 pressed 、 containsMouse 等状态属性和各种事件信号的区别，是构建流畅交互体验的关键。在实际项目中，合理组合这些特性可以创建出既美观又易用的用户界面。