QML Drag 类型详解

Drag QML 类型用于为可移动的 Item 元素指定拖放事件和行为。它是 QML 中实现拖放功能的主要机制。

基本概念

Drag 是一个附加属性（Attached Property），通常与 MouseArea 或 DragHandler 配合使用，为 Item 元素提供拖放能力。它处理拖放操作的源对象（被拖动的对象）的行为。

主要属性

源对象属性

• Drag.active: 布尔值，表示拖动是否处于活动状态
• Drag.source: 声明被拖动的对象实例（通常是父 Item）
• Drag.target: 当前有效的放置目标对象（当拖动对象悬停在可接受的放置区域上时）
• Drag.hotSpot: 定义拖动的热点位置，通常是鼠标指针相对于拖动对象的位置
• Drag.keys: 字符串列表，定义拖动对象可以被哪些目标接受

视觉反馈属性

• Drag.imageSource: URL，指定拖动过程中显示的图像
• Drag.dragType: 枚举值，指定拖动类型（None、Automatic、Internal）
• Drag.mimeData: 对象，包含拖动对象的 MIME 数据
• Drag.proposedAction: 拖动操作建议的动作（复制、移动等）
• Drag.supportedActions: 拖动操作支持的动作集合

信号

• Drag.dragStarted(): 拖动开始时触发
• Drag.dragFinished(DropAction action): 拖动完成时触发，传递执行的放置动作
• Drag.targetChanged: 当拖动目标发生变化时触发

使用方法

1. 基本拖动实现

Rectangle {
    id: dragItem
    width: 100; height: 100
    color: "blue"

    MouseArea {
        id: dragArea
        anchors.fill: parent
        drag.target: parent  // 设置拖动目标为父元素
        
        // 拖动属性
        drag.axis: Drag.XAndYAxis  // 可在X和Y轴拖动
        drag.minimumX: 0
        drag.maximumX: parent.width
        drag.minimumY: 0
        drag.maximumY: parent.height
    }
}

2. 拖放实现（带目标区域）

Item {
    width: 400; height: 400

    Rectangle {
        id: dragItem
        width: 50; height: 50
        color: "red"
        
        // 定义拖动源
        Drag.active: dragArea.drag.active
        Drag.hotSpot.x: width / 2
        Drag.hotSpot.y: height / 2
        Drag.keys: ["red"]
        
        states: State {
            when: dragArea.drag.active
            ParentChange { target: dragItem; parent: root }
            AnchorChanges {
                target: dragItem
                anchors.horizontalCenter: undefined
                anchors.verticalCenter: undefined
            }
        }
        
        MouseArea {
            id: dragArea
            anchors.fill: parent
            drag.target: parent
        }
    }
    
    // 放置目标区域
    Rectangle {
        id: dropZone
        width: 100; height: 100
        color: "yellow"
        anchors.right: parent.right
        anchors.bottom: parent.bottom
        
        // 定义放置目标
        DropArea {
            anchors.fill: parent
            keys: ["red"]
            
            onEntered: {
                dropZone.color = "green";
            }
            onExited: {
                dropZone.color = "yellow";
            }
            onDropped: {
                dropZone.color = "blue";
                dragItem.parent = dropZone;
                dragItem.anchors.centerIn = dropZone;
            }
        }
    }
}

3. 自定义拖动图像

Rectangle {
    id: dragItem
    width: 100; height: 100
    color: "purple"
    
    Drag.active: dragArea.drag.active
    Drag.hotSpot.x: width / 2
    Drag.hotSpot.y: height / 2
    Drag.imageSource: "qrc:/images/drag_image.png"  // 自定义拖动图像
    
    MouseArea {
        id: dragArea
        anchors.fill: parent
        drag.target: parent
    }
}

技术要点

• 放置点（Drop Target）: 需要使用 DropArea 类型来定义可放置区域
• 拖动状态（Drag State）: 通常使用 State 和 ParentChange 来管理拖动过程中的外观和行为
• 返回动画（Return Animation）: 可以使用 Behavior 或 Transition 为拖放操作添加动画效果
• 约束拖动（Constrained Drag）: 可以通过 drag.minimum/maximum 属性限制拖动范围

通过合理配置 Drag 属性和相关组件，可以实现丰富的拖放交互效果，提升应用的用户体验。