SwipeDelegate QML Type
可滑动项目委托。更多...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
属性
- 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
| 名称 | 描述 |
|---|---|
| position | 此只读属性保存了滑动位置相对于控件两侧的位置。当该值达到-1.0 （左侧）或1.0 （右侧），且鼠标按钮被释放时，complete 将true 。 |
| complete | 此只读属性用于标识控件在向左或向右滑动后是否已完全显示。 当 complete 为 |
| enabled | 此属性决定控件是否可以被滑动。 该属性是在QtQuick.Controls 2.2 中添加的。 |
| left | 此属性保存左侧委托。 左侧委托位于contentItem 和background 的后方。当SwipeDelegate 向右滑动时，该项目将逐渐显示出来。 此处可使用交互式和非交互式项目。适用常规事件处理规则；如果使用了Button 这样的交互式控件，则在点击该按钮时，SwipeDelegate 的交互信号（如clicked()）将不会被触发。 |
| behind | 此属性保存当SwipeDelegate 向左或向右滑动时显示的委托。 与 此处可使用交互式和非交互式项目。常规事件处理规则依然适用；如果使用了Button 之类的交互式控件，当点击该按钮时，SwipeDelegate 的交互信号（如clicked （））将不会被触发。 |
| right | 此属性保存右侧委托。 右侧委托位于contentItem 和background 之后。当SwipeDelegate 被向左滑动时，该控件将逐渐显示出来。 此处可使用交互式和非交互式控件。适用常规事件处理规则；如果使用了Button 这样的交互式控件，则当点击该按钮时，SwipeDelegate 的交互信号（如clicked()）将不会被触发。 |
| leftItem | 此只读属性保存从left 组件实例化的项目。如果未设置 |
| behindItem | 此只读属性保存由behind 组件实例化的项目。如果未设置 |
| rightItem | 此只读属性保存由right 组件实例化的项目。如果未设置 |
| transition | 该属性保存了在松开滑动时，或调用swipe.open()或swipe.close()时应用的过渡效果。该属性是在QtQuick.Controls 2.2 中新增的。 |
另请参阅 contentItem 、background 、swipe.open() 和swipe.close()。
附加属性文档
SwipeDelegate.pressed : bool [read-only attached, 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()。
附带的信号文档
[attached, 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 。此时，针对contentItem 和background 中x 位置定义的任何动画都将被触发。
该方法在 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()。
© 2026 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.
