QML类型——ListView

正文

为列表模型(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中的元素布局方式有以下三种：

1. orientation
   控制元素是水平还是垂直布局，该值可以是Qt.Horizontal和Qt.Vertical。

2. layoutDirection
   控制水平方向布局方式，通过Qt.LeftToRight或Qt.RightToLeft控制水平从左到右还是从右到左布局。

3. 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