SwipeDelegate QML Type

可轻扫项目委托。更多

Import Statement:	`import QtQuick.Controls`
Inherits:	ItemDelegate

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

属性

swipe
- swipe.behind : Component
- swipe.behindItem : Item
- swipe.complete : bool
- swipe.enabled : bool
- swipe.left : Component
- swipe.leftItem : Item
- swipe.position : real
- swipe.right : Component
- swipe.rightItem : Item
- swipe.transition : Transition

附属物业

pressed : bool (since QtQuick.Controls 2.1 (Qt 5.8))

信号

void swipe.closed() (since QtQuick.Controls 2.2 (Qt 5.9))
void swipe.completed() (since QtQuick.Controls 2.1 (Qt 5.8))
void swipe.opened() (since QtQuick.Controls 2.2 (Qt 5.9))

附加信号

clicked() (since QtQuick.Controls 2.1 (Qt 5.8))

方法

void swipe.close() (since QtQuick.Controls 2.1 (Qt 5.8))
void swipe.open(enumeration side) (since QtQuick.Controls 2.2 (Qt 5.9))

详细说明

SwipeDelegate 显示一个视图项目，该视图项目可左右滑动以显示更多选项或信息。它在ListView 等视图中用作委托。

在下面的示例中，SwipeDelegate 用于ListView ，允许通过向左轻扫从其中移除项目：

ListView {
    id: listView
    anchors.fill: parent
    model: ListModel {
        ListElement { sender: "Bob Bobbleton"; title: "How are you going?" }
        ListElement { sender: "Rug Emporium"; title: "SALE! All rugs MUST go!" }
        ListElement { sender: "Electric Co."; title: "Electricity bill 15/07/2016 overdue" }
        ListElement { sender: "Tips"; title: "Five ways this tip will save your life" }
    }
    delegate: SwipeDelegate {
        id: swipeDelegate
        text: sender + " - " + title
        width: listView.width

        required property string sender
        required property string title
        required property int index

        ListView.onRemove: removeAnimation.start()

        SequentialAnimation {
            id: removeAnimation

            PropertyAction {
                target: swipeDelegate
                property: "ListView.delayRemove"
                value: true
            }
            NumberAnimation {
                target: swipeDelegate
                property: "height"
                to: 0
                easing.type: Easing.InOutQuad
            }
            PropertyAction {
                target: swipeDelegate
                property: "ListView.delayRemove"
                value: false
            }
        }

        swipe.right: Label {
            id: deleteLabel
            text: qsTr("Delete")
            color: "white"
            verticalAlignment: Label.AlignVCenter
            padding: 12
            height: parent.height
            anchors.right: parent.right

            SwipeDelegate.onClicked: listView.model.remove(index)

            background: Rectangle {
                color: deleteLabel.SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
            }
        }
    }
}

SwipeDelegate 的 API 继承自ItemDelegate ，而又继承自AbstractButton 。例如，您可以设置text ，并使用AbstractButton API 对clicks 做出反应。

有关刷卡进度的信息以及刷卡时应显示的组件，都可以通过swipe 分组属性对象获得。例如，swipe.position 保存在-1.0 至1.0 范围内的轻扫位置。swipe.left 属性决定控件向右轻扫时将显示哪个项目，反之亦然，swipe.right 。这些组件的位置由应用程序决定。例如，如果不为swipe.left 或swipe.right 指定任何位置，就会出现以下情况：

如果swipe.left 和swipe.right 分别锚定在background 项目的左侧和右侧，它们的行为将是这样的：

当使用swipe.left 和swipe.right 时，控件不能掠过左右边缘。要实现这种 "包裹 "行为，请设置swipe.behind 。这样，无论控件向哪个方向滑动，都会显示相同的项目。例如，在下图中，我们设置了swipe.behind ，然后向两个方向反复轻扫控件：

另请参阅 自定义 SwipeDelegate、委托控件和图库示例。

属性文档

swipe group
swipe.behind : Component
swipe.behindItem : Item
swipe.complete : bool
swipe.enabled : bool
swipe.left : Component
swipe.leftItem : Item
swipe.position : real
swipe.right : Component
swipe.rightItem : Item
swipe.transition : Transition

名称	说明
位置	该只读属性用于保存相对于控件任一侧的轻扫位置。当此值到达`-1.0` （左侧）或`1.0` （右侧）并释放鼠标按钮时，`complete` 将变为`true` 。
完成	该只读属性用于保存向左或向右轻扫之后控件是否完全显示。当 complete 为`true` 时，在`left` 、`right` 或`behind` 中声明的任何交互项都将收到鼠标事件。
启用	该属性决定控件是否可以轻扫。该属性在QtQuick.Controls 2.2 中添加。
左	该属性用于保存左侧委托。左侧委托位于contentItem 和background 的后面。当SwipeDelegate 向右滑动时，该项将逐渐显示出来。交互式和非交互式项目均可在此使用。正常的事件处理规则适用；如果使用的是Button 这样的交互式控件，如果点击按钮，SwipeDelegate 的交互信号（如clicked() ）将不会发出。
后面	该属性用于保存在SwipeDelegate 向左和向右滑动时显示的委托。与`left` 和`right` 委托一样，它位于contentItem 和background 的后面。不过，已设置`behind` 的SwipeDelegate 可以从两侧连续轻扫，并始终显示相同的项目。这里可以使用交互式和非交互式项目。正常的事件处理规则适用；如果使用的是Button 这样的交互式控件，如果点击按钮，SwipeDelegate 的交互信号（如clicked() ）将不会发出。
右	该属性包含右委托。右委托位于contentItem 和background 的后面。当SwipeDelegate 向左滑动时，该项目将逐渐显示出来。交互式和非交互式项目均可在此使用。正常的事件处理规则适用；如果使用的是Button 这样的交互式控件，如果点击按钮，SwipeDelegate 的交互信号（如clicked() ）将不会发出。
左侧项目	此只读属性包含从`left` 组件实例化的项目。如果`left` 尚未设置，或自创建SwipeDelegate 后位置未变，则该属性将为`null` 。
背后项目	此只读属性保存从`behind` 组件实例化的项目。如果`behind` 尚未设置，或自创建SwipeDelegate 后位置未变，则此属性将为`null` 。
右项目	此只读属性保存从`right` 组件实例化的项目。如果`right` 尚未设置，或自创建SwipeDelegate 后位置未变，则此属性将是`null` 。
过渡	此属性用于保存释放轻扫、调用swipe.open() 或swipe.close() 时应用的过渡。 SwipeDelegate { swipe.transition: Transition { SmoothedAnimation { velocity: 3; easing.type: Easing.InOutCubic } } } 此属性在Qt Quick Controls 2.2 中添加。

另请参阅 contentItem,background,swipe.open() 和swipe.close()。

附加属性文档

SwipeDelegate.pressed : bool [read-only, since QtQuick.Controls 2.1 (Qt 5.8)]

该属性可附加到在swipe.left,swipe.right, 或swipe.behind 中声明的非交互式项目，以检测该项目是否被按下。只有当swipe.complete 是true 时，项目才能被按下。

例如

swipe.right: Label {
    anchors.right: parent.right
    height: parent.height
    text: "Action"
    color: "white"
    padding: 12
    background: Rectangle {
        color: SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
    }
}

可以有多个单独接收鼠标和触摸事件的项目。例如，要在swipe.right 项目中执行两个操作，请使用以下代码：

swipe.right: Row {
    anchors.right: parent.right
    height: parent.height

    Label {
        id: moveLabel
        text: qsTr("Move")
        color: "white"
        verticalAlignment: Label.AlignVCenter
        padding: 12
        height: parent.height

        SwipeDelegate.onClicked: console.log("Moving...")

        background: Rectangle {
            color: moveLabel.SwipeDelegate.pressed ? Qt.darker("#ffbf47", 1.1) : "#ffbf47"
        }
    }
    Label {
        id: deleteLabel
        text: qsTr("Delete")
        color: "white"
        verticalAlignment: Label.AlignVCenter
        padding: 12
        height: parent.height

        SwipeDelegate.onClicked: console.log("Deleting...")

        background: Rectangle {
            color: deleteLabel.SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"
        }
    }
}

注意每个background 项目中的color 赋值是如何用标签的id 限定附加属性的。这一点很重要；在项目中使用附加属性会导致该项目接受事件。假设我们在上一个示例中忽略了id ：

color: SwipeDelegate.pressed ? Qt.darker("tomato", 1.1) : "tomato"

Rectangle 背景项是标签的子项，因此它自然会比标签先接收事件。实际上，这意味着背景颜色会发生变化，但标签中的onClicked 处理程序永远不会被调用。

对于在这些项目中声明的交互式控件（如Button ），请使用它们各自的pressed 属性。

对于按下SwipeDelegate 本身，请使用其pressed 属性。

该属性在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 clicked().

信号文档

[since QtQuick.Controls 2.2 (Qt 5.9)] void swipe.closed()

当委托被轻扫关闭且转换完成时，会发出该信号。

它可用于在取消轻扫后执行某些操作。例如，它可用于取消从列表中删除委托。

注：相应的处理程序是swipe.onClosed 。

该信号在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 swipe 和swipe.opened() 。

[since QtQuick.Controls 2.1 (Qt 5.8)] void swipe.completed()

当swipe.complete 变成true 时，就会发出该信号。

它可用于在完成刷卡后执行某些操作。例如，它可用于将委托从其所在的列表中移除。

注意： 相应的处理程序是swipe.onCompleted 。

该信号在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 swipe 。

[since QtQuick.Controls 2.2 (Qt 5.9)] void swipe.opened()

该信号在委托被刷开且转换完成时发出。

它适用于在刷开完成后执行某些操作。例如，它可用于将委托从其所在的列表中移除。

注：相应的处理程序是swipe.onOpened 。

该信号在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 swipe 和swipe.closed() 。

附加信号文档

[since QtQuick.Controls 2.1 (Qt 5.8)] clicked()

该信号可附加到swipe.left 、swipe.right 或swipe.behind 中声明的非交互式项目，以便对点击做出反应。只有当swipe.complete 是true 时，项目才能被点击。

对于在这些项目中声明的交互式控件（如Button ），请使用各自的clicked() 信号。

要响应SwipeDelegate 本身的点击，请使用其clicked() 信号。

注：有关如何正确使用事件相关属性的信息，请参阅pressed 文档。

注：相应的处理程序是onClicked 。

该信号在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 pressed 。

方法文档

[since QtQuick.Controls 2.1 (Qt 5.8)] void swipe.close()

此方法将轻扫的position 设置为0 。为x 位置的contentItem 和background 定义的任何动画都将被触发。

此方法在 QtQuick.Controls 2.1 (Qt 5.8) 中引入。

另请参阅 swipe 和swipe.open() 。

[since QtQuick.Controls 2.2 (Qt 5.9)] void swipe.open(enumeration side)

此方法设置刷卡的position ，使其从指定的side 打开。

可用值：

常量	说明
`SwipeDelegate.Left`	`position` 将被设置为`1` ，使轻扫从左侧打开。必须指定`swipe.left` 或`swipe.behind` ，否则调用将被忽略。
`SwipeDelegate.Right`	`position` 设置为`-1` ，这样就可以从右侧打开刷卡器。必须指定`swipe.right` 或`swipe.behind` ，否则该调用将被忽略。

为x 位置定义的contentItem 和background 动画将被触发。

此方法在 QtQuick.Controls 2.2 (Qt 5.9) 中引入。

另请参阅 swipe 和swipe.close()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.