Drag QML Type (Uncreatable)

用于指定已移动项的拖放事件。更多...

注意：此类型无法创建。无法在 QML 中实例化。

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

关联属性

• active : bool
• dragType : enumeration
• hotSpot : point
• imageSource : url
• imageSourceSize : size (since 6.8)
• keys : stringlist
• mimeData : var
• proposedAction : enumeration
• source : Object
• supportedActions : flags
• target : Object

附加信号

• dragFinished(DropAction dropAction)
• dragStarted()

附带的方法

• void cancel()
• enumeration drop()
• void start(flags supportedActions)
• void startDrag(flags supportedActions)

详细说明

通过使用“Drag”附加属性，可以将任何项设置为场景中的拖放事件源。

当某个项处于active 状态时，该项位置的任何变化都会触发拖动事件，并将该事件发送给与该项新位置相交的任何DropArea 。其他实现了拖放事件处理程序的项目也可以接收这些事件。

以下代码片段演示了如何使用 `MouseArea` 拖动一个项目。不过，拖动操作并不局限于鼠标拖动；任何能够移动项目的操作都会触发拖动事件，包括触摸事件、动画和绑定。

import QtQuick

Item {
    width: 200; height: 200

    DropArea {
        x: 75; y: 75
        width: 50; height: 50

        Rectangle {
            anchors.fill: parent
            color: "green"

            visible: parent.containsDrag
        }
    }

    Rectangle {
        x: 10; y: 10
        width: 20; height: 20
        color: "red"

        Drag.active: dragArea.drag.active
        Drag.hotSpot.x: 10
        Drag.hotSpot.y: 10

        MouseArea {
            id: dragArea
            anchors.fill: parent

            drag.target: parent
        }
    }
}

拖动操作可通过调用 Drag.cancel() 取消，或将 Drag.active 设置为 false 来终止；也可以通过调用 Drag.drop() 并触发放置事件来终止。如果放置事件被接受，Drag.drop() 将返回事件接收方选择的drop action ，否则将返回 Qt.IgnoreAction。

另请参阅 《Qt Quick 示例——拖放》。

附加属性文档

Drag.active : bool [read-only attached]

该属性表示拖动事件序列当前是否处于活动状态。

将此属性绑定到MouseArea::drag 的active属性上，将在用户开始拖动时触发startDrag 方法。

将此属性设置为 true 还将向场景发送一个包含项目当前位置的 QDragEnter 事件。将其设置为 false 则会发送一个 QDragLeave 事件。

在拖动活动期间，项目位置的任何变化都会向场景发送一个包含项目新位置的 QDragMove 事件。

Drag.dragType : enumeration [attached]

此属性用于指定是自动启动拖拽操作、不执行任何操作，还是使用向后兼容的内部拖拽操作。默认情况下使用向后兼容的内部拖拽操作。

也可以通过调用 `startDrag` 手动启动拖动操作。

在使用Drag.Automatic 时，还应定义mimeData ，并将active 属性绑定到MouseArea 的active属性上：MouseArea::drag.active

Drag.hotSpot : point [attached]

该属性存储相对于项目左上角的拖动位置。

默认值为 (0, 0)。

对 hotSpot 的修改会触发以更新后的位置为基准的新的拖动操作。

Drag.imageSource : url [attached]

该属性存储了在拖放操作期间用于表示数据的图片的 URL。在拖放操作开始后修改此属性将不会产生任何效果。

下面的示例使用项目的内容作为拖拽图像：

import QtQuick

Item {
    width: 200; height: 200

    Rectangle {
        anchors.centerIn: parent
        width: text.implicitWidth + 20; height: text.implicitHeight + 10
        color: "green"
        radius: 5

        Drag.dragType: Drag.Automatic
        Drag.supportedActions: Qt.CopyAction
        Drag.mimeData: {
            "text/plain": "Copied text"
        }

        Text {
            id: text
            anchors.centerIn: parent
            text: "Drag me"
        }

        DragHandler {
            id: dragHandler
            onActiveChanged:
                if (active) {
                    parent.grabToImage(function(result) {
                        parent.Drag.imageSource = result.url
                        parent.Drag.active = true
                    })
                } else {
                    parent.Drag.active = false
                }
        }
    }
}

另请参阅 Item::grabToImage()。

Drag.imageSourceSize : size [attached, since 6.8]

该属性存储在拖放操作期间用于表示数据的图像大小。在拖放操作开始后修改此属性将无效。

该属性用于设置加载图像所存储的最大像素数，以避免大图像占用超过必要的内存。更多详细信息请参阅Image.sourceSize 。

下面的示例展示了一张以某种尺寸渲染的 SVG 图像，并将其重新渲染为另一种尺寸以作为拖拽图像：

import QtQuick

Item {
    width: 200; height: 200

    Image {
        anchors.centerIn: parent
        source: "images/qt_logo.svg"
        sourceSize.width: 96

        Drag.dragType: Drag.Automatic
        Drag.supportedActions: Qt.CopyAction
        Drag.mimeData: {
            "text/plain": "Qt Quick rocks!"
        }
        Drag.imageSource: "images/qt_logo.svg"
        Drag.imageSourceSize: Qt.size(48, 35)
        Drag.active: dragHandler.active

        DragHandler {
            id: dragHandler
        }
    }
}

该属性于 Qt 6.8 中引入。

另请参阅 imageSource 和Item::grabToImage()。

Drag.keys : stringlist [attached]

该属性包含一个键列表，DropArea 可以使用该列表来过滤拖拽事件。

在拖动操作进行期间更改键值将重置拖动事件的序列：系统会先发送一个“拖动离开”事件，随后再发送一个包含新源位置的“拖动进入”事件。

Drag.mimeData : var [attached]

该属性保存了一个从 MIME 类型到数据的映射，该映射在startDrag 过程中会被使用。 MIME 数据必须与 MIME 类型相匹配（例如，如果 MIME 类型为“text/plain”，则应为字符串；如果 MIME 类型为“image/png”，则应为图像），或者是一个ArrayBuffer ，其中数据应根据 MIME 类型进行编码。

Drag.proposedAction : enumeration [attached]

该属性保存了拖动源作为 Drag.drop() 方法的返回值所推荐的操作。

对 proposedAction 的更改将触发一个包含更新后建议的移动事件。

Drag.source : Object [attached]

该属性保存一个对象，该对象在拖动事件的接收方处被识别为事件的源。默认情况下，该对象即为“Drag”属性所关联的项目。

在拖动操作进行期间更改源对象会重置拖动事件的序列：系统会先发送一个“拖动离开”事件，随后再发送一个以新源为目标的“拖动进入”事件。

Drag.supportedActions : flags [attached]

该属性存储拖动源支持的 Drag.drop() 的返回值。

在拖拽操作进行中更改 supportedActions 会重置拖拽事件序列：系统会先发送一个“拖拽离开”事件，随后再发送一个带有新源的“拖拽进入”事件。

Drag.target : Object [attached]

在拖拽操作进行期间，该属性保存最后一个接收来自被拖拽项的enter事件的目标对象；如果当前拖拽位置与任何接收目标均无交集，则该属性为null。

当拖拽操作未处于活动状态时，该属性保存的是接受了结束本次拖拽操作的释放事件的对象；如果没有任何对象接受释放事件，或者拖拽操作被取消，则该目标将为 null。

附带的信号文档

[attached] dragFinished(DropAction dropAction)

当拖动操作结束时，如果该拖动操作是通过startDrag()方法启动的，或者通过dragType 属性自动启动的，则会发出此信号。

dropAction 该信号包含目标项接受的操作。

另请参阅 drop()。

[attached] dragStarted()

当使用startDrag() 方法开始拖动操作，或者通过dragType 属性自动触发拖动操作时，会发出此信号。

相关方法文档

[attached] void cancel()

结束拖动操作。

[attached] enumeration drop()

通过向目标项发送一个拖放事件来结束拖动序列。

返回目标项接受的操作。如果目标项或其父项不接受该拖放事件，则返回 Qt.IgnoreAction。

返回的放置操作可能是以下之一：

[attached] void start(flags supportedActions)

开始发送拖动事件。用于启动旧式的内部拖动操作。startDrag 是启动拖动操作的新式且推荐的方法。

可选参数supportedActions 可用于覆盖已启动序列的supportedActions 属性。

[attached] void startDrag(flags supportedActions)

开始发送拖动事件。

可选参数supportedActions 可用于覆盖已启动序列的supportedActions 属性。