qml ListView 详解

最新推荐文章于 2025-02-20 08:00:00 发布

码农客栈_V13427279549

最新推荐文章于 2025-02-20 08:00:00 发布

阅读量1k

点赞数 23

分类专栏： Qt qml 文章标签： qml

本文链接：https://blog.csdn.net/ckg3824278/article/details/145061783

版权

Qt 同时被 2 个专栏收录

408 篇文章

订阅专栏

qml

125 篇文章

订阅专栏

1. 概述

ListView 是 Qt Quick 中用于展示列表数据的组件，它提供了灵活且高效的方式来显示可滚动的项目列表。ListView 通过 model、delegate 和 orientation 等属性，可以根据不同的需求展示列表项。它支持纵向和横向的滚动方式，并允许使用不同的视图元素来展示每个列表项。

ListView 通常用于显示大量数据，例如从数据库获取的条目、图片列表、联系人等信息。其主要优势在于支持懒加载，只渲染当前视口可见的部分，提升性能。

2. 重要属性

model：定义数据源，用于提供列表项的数据。可以是数组、列表模型（如 ListModel）或自定义的模型。
delegate：用于定义如何显示每个列表项。通常是一个 Item，用于控制每个项目的外观和布局。
orientation：控制列表的滚动方向，支持 ListView.Vertical（垂直）和 ListView.Horizontal（水平）。
height：指定 ListView 的高度（当滚动方向为垂直时）。如果方向为水平，可以设置 width。
width：指定 ListView 的宽度（当滚动方向为水平时）。如果方向为垂直，则设置 height。
spacing：列表项之间的间距。默认为 0，设置为大于 0 的值可以增加项之间的空隙。
clip：布尔值，指定是否裁剪超出视图边界的内容。默认为 true，即内容超出视图时会被裁剪。
currentIndex：表示当前选中的项的索引。通过此属性可以控制选择的项。
interactive：布尔值，是否允许用户交互。默认为 true，表示允许用户滚动列表、选择项等。
highlight：用于设置当前高亮项的外观。可以使用 Item 元素来设置高亮效果。
visible：指定 ListView 是否可见。默认为 true。
flickable：控制是否启用触摸或鼠标滚动。通常设置为 true，表示支持滚动。
contentY / contentX：表示列表滚动的纵向或横向位置。可以通过修改这些值来控制滚动位置。

3. 重要方法

positionViewAtIndex(index, position)：将视图滚动到指定项的位置。index 是目标项的索引，position 指定了位置类型（例如，顶部、底部或居中）。
currentIndex：获取或设置当前选中的索引项。通过此方法可以更新选中的项。
scrollToIndex(index)：将 ListView 滚动到指定的索引项。
contentHeight：获取列表的内容总高度。适用于垂直方向的 ListView。
contentWidth：获取列表的内容总宽度。适用于水平方向的 ListView。

4. 重要信号

onCurrentIndexChanged(index)：当当前选中的项的索引发生变化时触发。可以监听该信号来更新 UI 或执行其他操作。
onItemPressed(index)：当用户按下某个列表项时触发。index 为当前点击的项的索引。
onItemReleased(index)：当用户释放某个列表项时触发。
onFlickStarted()：当用户开始滚动时触发，通常用于触发滚动动画或调整其他 UI 元素。
onFlickEnded()：当用户停止滚动时触发。
onMovementChanged()：当滚动方向发生变化时触发，适用于水平和垂直滚动的视图。

5. 常用枚举类型

ListView.Horizontal：表示水平滚动方向。
ListView.Vertical：表示垂直滚动方向。
ListView.EnsureVisible：确保目标项在视口内可见。
ListView.Beginning：表示滚动到列表的起始位置。
ListView.End：表示滚动到列表的末尾。

Window {
    visible: true
    width: 640
    height: 800
    title: "ListView 示例"

    // 数据模型
    ListModel {
        id: colorModel
        ListElement { color: "red"; name: "红色" }
        ListElement { color: "green"; name: "绿色" }
        ListElement { color: "blue"; name: "蓝色" }
        ListElement { color: "yellow"; name: "黄色" }
        ListElement { color: "purple"; name: "紫色" }
        ListElement { color: "orange"; name: "橙色" }
        ListElement { color: "cyan"; name: "青色" }
        ListElement { color: "magenta"; name: "品红色" }
        ListElement { color: "gray"; name: "灰色" }
        ListElement { color: "black"; name: "黑色" }
    }

    Column {
        id: columnLayout
        anchors.centerIn: parent
        spacing: 1
        //padding: 20
        width: 300
        height: 800
        visible: true
        enabled: true
        clip: true

        ListView {
            id: listView
            width: parent.width
            height: 300
            model: colorModel
            spacing: 10
            clip: true
            orientation: ListView.Vertical
            interactive: true
            flickableDirection: Flickable.AutoFlickDirection

            delegate: Rectangle {
                width: parent.width
                height: 50
                color: model.color
                border.color: "black"
                border.width: 1

                Text {
                    text: model.name
                    anchors.centerIn: parent
                    color: "white"
                }

                MouseArea {
                    anchors.fill: parent
                    onClicked: {
                        listView.currentIndex = index
                    }
                }
            }

            highlight: Rectangle {
                color: "lightblue"
                opacity: 0.5
            }

            highlightFollowsCurrentItem: true

            onCurrentIndexChanged: {
                console.log("当前选中的项索引: " + currentIndex)
            }

            onContentXChanged: {
                console.log("内容水平滚动位置: " + contentX)
            }

            onContentYChanged: {
                console.log("内容垂直滚动位置: " + contentY)
            }

            onMovementStarted: {
                console.log("滚动开始")
            }

            onMovementEnded: {
                console.log("滚动结束")
            }
        }

        Rectangle {
            id: controlRect1
            width: 150
            height: 50
            color: "green"

            Text {
                text: "点击添加颜色"
                anchors.centerIn: parent
                color: "white"
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    colorModel.append({ color: "pink", name: "粉色" })
                }
            }
        }

        Rectangle {
            id: controlRect2
            width: 150
            height: 50
            color: "red"

            Text {
                text: "点击移除颜色"
                anchors.centerIn: parent
                color: "white"
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    if (colorModel.count > 0) {
                        colorModel.remove(0)
                    }
                }
            }
        }

        Rectangle {
            id: controlRect3
            width: 150
            height: 50
            color: "orange"

            Text {
                text: "滚动到顶部"
                anchors.centerIn: parent
                color: "white"
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    listView.positionViewAtBeginning()
                }
            }
        }

        Rectangle {
            id: controlRect4
            width: 150
            height: 50
            color: "purple"

            Text {
                text: "滚动到底部"
                anchors.centerIn: parent
                color: "white"
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    listView.positionViewAtEnd()
                }
            }
        }

        Rectangle {
            id: controlRect5
            width: 150
            height: 50
            color: "brown"

            Text {
                text: "滚动到索引 2"
                anchors.centerIn: parent
                color: "white"
            }

            MouseArea {
                anchors.fill: parent
                onClicked: {
                    listView.positionViewAtIndex(2, ListView.Center)
                }
            }
        }
    }
}