拖动 QML 类型

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

导入语句	import QtQuick

包括继承成员在内的所有成员列表

附加属性

active : bool
dragType : 枚举
hotSpot : QPointF
imageSource : QUrl
keys : 字符串列表
mimeData : var
proposedAction : 枚举
source : 对象
supportedActions : 标志
target : 对象

附加信号

dragFinished(DropAction dropAction)
dragStarted()

附加方法

void cancel()
枚举 drop()
void start(flags supportedActions)
void startDrag(flags supportedActions)

详细描述

使用拖动附加属性，可以将任何项作为场景中的拖放事件源。

当某个项上存在活动状态的拖动时，该项位置的变化将生成一个拖动事件，该事件将被发送到与该项新位置相交的任何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 [只读]

此属性包含拖动事件序列当前是否处于活动状态。

将此属性绑定到鼠标区域的活跃属性，当用户开始拖动时将调用。

将此属性设置为true将在场景中发送包含项目当前位置的QDragEnter事件。设置为false将发送QDragLeave事件。

在拖动处于活跃状态时，项目位置的任何改变都将向场景发送包含项目新位置的QDragMove事件。

Drag.dragType : 枚举

此属性指示是否自动开始拖动、不进行任何操作还是使用向后兼容的内部拖动。默认情况下使用向后兼容的内部拖动。

也可以使用手动启动拖动。

常量	描述
`Drag.None`	不自动开始拖动
`Drag.Automatic`	自动开始拖动
`Drag.Internal`	（默认）自动开始向后兼容的拖动

当使用Drag.Automatic时，还应定义并绑定MouseArea的活跃属性：:MouseArea::drag.active

Drag.hotSpot : QPointF

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

默认情况下为(0, 0)。

hotSpot的变化将触发一个新的具有更新位置的拖动移动事件。

Drag.imageSource : QUrl

此属性保存用于在拖放操作中表示数据的图像的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.keys : stringlist

此属性保存一个键列表，该列表可用于 DropArea 以过滤拖动事件。

在拖动活跃时更改键将重置拖动事件的序列，通过发送拖动离开事件，然后发送具有新源的拖动进入事件。

Drag.mimeData : var

此属性保存用于开始拖动的从mime类型到数据的映射。需要的数据类型必须与mime类型匹配（例如，如果mime类型是"text/plain"，则为字符串；如果mime类型是"image/png"，则为图像），或是一个使用mse类型进行编码的ArrayBuffer数据。

Drag.proposedAction : 枚举

此属性保存拖动源作为Drag.drop()的返回值推荐的动作。

更改proposedAction将触发一个具有更新建议的动作移动事件。

Drag.source : Object

此属性保存一个对象，该对象由拖动事件的接收者识别为事件的源。默认情况下，这是附加Drag属性的项目。

在拖动活跃时更改源将通过发送拖动离开事件，然后发送具有新源的新拖动事件来重置拖动事件的序列。

Drag.supportedActions : flags

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

在拖动活动状态中更改supportedActions将通过对新源发送drag leave事件和drag enter事件来重置拖动事件的序列。

Drag.target : 对象

当拖动活动正在进行时，此属性保存最后一个表示项，该表示项接收了拖动项的enter事件，如果当前拖动位置不与任何接受目标的交集，则此值为null。

当拖动不是活动状态时，此属性保存接收了结束拖动事件的项的对象，如果没有对象接收drop事件，或者拖动被取消，则目标将是null。

附加信号文档

dragFinished(DropAction dropAction)

当使用startDrag()方法或使用dragType属性自动启动拖动时，此信号被发出。

dropAction保存了目标项接受的操作。

注意： 相应的处理程序是onDragFinished。

另请参阅 drop()。

dragStarted()

当使用startDrag()方法启动拖动，或当它使用dragType属性自动启动时，此信号被发出。

注意： 相应的处理程序是onDragStarted。

附加方法文档

void cancel()

结束拖动序列。

枚举 drop()

通过向目标项发送drop事件，结束拖动序列。

返回目标项接受的操作。如果目标项或父元素不接受drop事件，则返回Qt.IgnoreAction。

返回的drop操作可以是以下之一

常量	描述
`Qt.CopyAction`	将数据复制到目标
`Qt.MoveAction`	将数据从源移动到目标
`Qt.LinkAction`	从源到目标创建链接。
`Qt.IgnoreAction`	忽略操作（不处理数据）。

void start(flags supportedActions)

开始发送拖动事件。用于启动旧式内部拖动。 startDrag是启动拖动的新式、首选方法。

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

void startDrag(flags supportedActions)

开始发送拖动事件。

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