正文
为列表模型(ListModel)的所有元素提供列表视图。
详细说明
ListView显示内置QML类型(例如ListModel和XmlListModel)创建的模型数据,或者使用C++定义的自定义模型类(继承QAbstractItemModel或QAbstractListModel)创建的数据。
ListView有一个Model(定义要显示的数据)和一个Delegate(定义如何显示数据)。ListView中的元素可以水平或垂直放置。列表视图本质上是可以拖动的,因为ListView继承Flickable。
用法示例
以下示例显示了在名为ContactModel.qml的文件中定义的简单列表模型:
import QtQuick 2.0
ListModel {
ListElement {
name: "Bill Smith"
number: "555 3264"
}
ListElement {
name: "John Brown"
number: "555 8426"
}
ListElement {
name: "Sam Wise"
number: "555 0473"
}
}
另一个组件可以在ListView中显示此模型数据,如下所示:
import QtQuick 2.0
ListView {
width: 180; height: 200
model: ContactModel {}
delegate: Text {
text: name + ": " + number
}
}
示例中,ListView为model创建了ContactModel组件,并为其委托创建一个Text显示项。
改进的列表视图如下所示。对委托进行了显示效果改进,并将其移至单独的contactDelegate组件中。
Rectangle {
width: 180; height: 200
Component {
id: contactDelegate
Item {
width: 180; height: 40
Column {
Text { text: '<b>Name:</b> ' + name }
Text { text: '<b>Number:</b> ' + number }
}
}
}
ListView {
anchors.fill: parent
model: ContactModel {}
delegate: contactDelegate
highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
focus: true
}
}
示例中,当前选中的元素使用highlight属性,以蓝色矩形突出显示,并将焦点(focus)设置为true以启用ListView的键盘导航。ListView本身就是焦点范围(有关详细信息,请参考Qt Quick中的Keyboard Focus)。
代理(delegate)将根据需要实例化,并且可以随时销毁。它们是ListView的contentItem的父级,而不是ListView本身的父级。永远不要将状态存储在代理中。
ListView将许多属性附加到代理的根元素(root item),例如ListView.isCurrentItem。在以下示例中,代理的根元素可以直接访问附加属性ListView.isCurrentItem。而子contactInfo对象必须通过父级访问(wrapper.ListView.isCurrentItem)
ListView {
width: 180; height: 200
Component {
id: contactsDelegate
Rectangle {
id: wrapper
width: 180
height: contactInfo.height
color: ListView.isCurrentItem ? "black" : "red"
Text {
id: contactInfo
text: name + ": " + number
color: wrapper.ListView.isCurrentItem ? "red" : "black"
}
}
}
model: ContactModel {}
delegate: contactsDelegate
focus: true
}
注意:视图不会自动启用裁剪(clip)。如果视图没有被其他对象或屏幕裁剪,则必须设置clip:true才能将超出视图部分裁剪掉。
ListView布局
ListView中的元素布局方式有以下三种:
-
orientation
控制元素是水平还是垂直布局,该值可以是Qt.Horizontal和Qt.Vertical。 -
layoutDirection
控制水平方向布局方式,通过Qt.LeftToRight或Qt.RightToLeft控制水平从左到右还是从右到左布局。 -
verticalLayoutDirevtion
控制垂直方向布局方式,通过ListView.TopToBottom或ListView.BottomToTop来控制垂直从上到下还是从下到上布局。
默认情况下,ListView是垂直布局,并且是从上到下放置。下图显示了ListView可以具有的不同布局方式,具体取决于上面列出的属性值:
Flickable设置
默认情况下,垂直ListView将flickableDirection设置为Flickable.Vertical,水平ListView将其设置为Flickable.Horizontal。此外,垂直ListView只计算contentHeight,而水平ListView只计算contentWidth。
从Qt 5.9(Qt Quick 2.9)开始,可以制作一个可以向两个方向滑动的ListView。将flickableDirection设置为Flickable.AutoFlickDirection或Flickable.AutoFlicklfNeeded,并且必须提供所需的contentWidth和contentHeight。
ListView {
width: 180; height: 200
contentWidth: 320
flickableDirection: Flickable.AutoFlickDirection
model: ContactModel {}
delegate: Row {
Text { text: '<b>Name:</b> ' + name; width: 160 }
Text { text: '<b>Number:</b> ' + number; width: 160 }
}
}
ListView中的顺序
元素的Z值确定了它们的与渲染顺序。ListView使用几个不同的默认Z值,具体取决于要创建的项目类型:
属性 | 默认Z值 |
---|---|
delegate | 1 |
footer | 1 |
header | 1 |
highl |