QML之ListView独立属性,信号,方法讲解

前言

记录QML的视图之ListView的使用
Qt版本:Qt6.8.0

初始

窗口大小:640*480
listview大小为:640*480
listview是不可视控件无法直接看到

父类Flickable属性,信号,方法查看父类

属性

继承的必须设置的属性

clip

width/height

…

非动画属性

cacheBuffer : int --用于指定在 可见区域之外 预先加载（缓存）的列表项的像素范围

• 如果 cacheBuffer 设置为 100，则 ListView 会在当前可见区域的上方和下方各额外缓存 100 像素高度的项。

• 这些缓存的项会被提前创建并保持活跃状态（不会被销毁），但不会显示在屏幕上

• 直接设置即可

count : int --视图里项目的个数,等价于model里有多少数据

注意

• 如果未指定delegate则获取的项目个数为0

currentIndex : int --当前选中项的索引

你点击那个项目该值就是那个项目的listview的索引(从0开始),也可以手动指定

currentItem : Item --当前选中的项

你点击那个项目该值就是那个项目

PixPin_2025-05-14_15-45-30

delegate : Component --用于显示模型里的数据

footer : Component --页脚组件,页脚位于内容末尾，与内容一起移动，就像普通项目一样。(默认情况,可用footerPostitioning属性调整),锚点属性无效
footerItem : Item–存储页脚项
footerPositioning : enumeration --设置页脚的位置

model:model–存储数据的模型,可以是qml模型或c++模型

header : Component --页眉组件,其他同footer
headerItem : Item --存储页眉项
headerPositioning : enumeration --设置页眉所在位置

spacing:real --项目之间的间距

displayMarginBeginning : int --控制 ListView 在列表开头（顶部或左侧，取决于滚动方向）的可视范围外预加载多少像素的内容。
displayMarginEnd : int --控制 ListView 在列表末尾（底部或右侧，取决于滚动方向）的可视范围外预加载多少像素的内容。

直接设置即可

effectiveLayoutDirection : enumeration --返回视图的实际布局方向

verticalLayoutDirection : enumeration --指定 ListView 的垂直布局方向，定义列表项是从上到下还是从下到上排列

layoutDirection : enumeration --指定 ListView 的布局方向，定义内容从左到右还是从右到左排列

orientation : enumeration --设置列表滚动方向

reuseItems : bool --启用项复用机制以提高性能

snapMode : enumeration --定义滚动对齐模式

preferredHighlightBegin --表示高亮区域起始位置（相对于 ListView 的高度或宽度，取值为 0.0~1.0 的比例）
preferredHighlightEnd --表示高亮区域结束位置（同理，取值为 0.0~1.0 的比例）

• 配合highlightRangeMode一起使用.根据highlightRangeMode的值来决定高亮项(当前项)是否在该范围内
• 必须设置 highlightRangeMode: ListView.StrictlyEnforceRange 或ListView.ApplyRange，这两个属性才会生效
• 高亮区域的比例是相对于 ListView 的可视高度，而非内容高度。
• 值超出 [0.0, 1.0] 范围会导致未定义行为。
• 当beginning的值小于end的值进行切换项那么listview将会滚动到你选择的项,如果大于那么只有高亮会移动到你选择的项listview不会滚动
  • 也就是说beg>end时高亮移动到你选择的项(listview不动),beg<end时listview会滚动让你选择的项移动到高亮处(高亮不动)
• beginning>end

PixPin_2025-05-14_16-22-30

• beg<end

PixPin_2025-05-14_16-23-32

注意:如果需要在选择项时滚动listview就让beg<end,否则无需设置这两个属性

highlight : Component --设置高亮的样式
highlightFollowsCurrentItem : bool --表示高亮显示是否由视图管理。 如果此属性为 true（默认值),若要自定义高亮显示需设置为false
highlightItem : Item --它保存从高亮组件创建的高亮项
highlightMoveDuration : int --定义高亮项（highlight）移动到新位置时的动画持续时间（以毫秒为单位）,值越小高亮移动的速度就越快
highlightMoveVelocity : real --以像素/秒为单位控制高亮项移动的速度,优先于 highlightMoveDuration
highlightRangeMode : enumeration --定义高亮项在视图中的定位规则,当值为StrictlyEnforceRange时会强制将当前索引项显示在preferredHighlightBegin,preferredHighlightEnd划定的高亮区域内
highlightResizeDuration : int --当高亮项尺寸改变时，定义动画的持续时间（以毫秒为单位）
highlightResizeVelocity : real --以像素/秒为单位定义高亮项尺寸变化的动画速度,优先于 highlightResizeDuration

keyNavigationEnabled: bool 控制是否启用键盘导航功能
keyNavigationWraps: bool 控制键盘导航是否在到达列表边界后环绕
必须设置focus: true,否则无效

按下键盘的上方向键,高亮往上移动一个项,按下键盘的下方向键,高亮往下移动一个项

section 提供了对列表内容分组的支持，可以在列表中根据某些标准生成分段标签

section.criteria : enumeration 定义分组的标准

• ViewSection.FullString：按完整字符串匹配分组
• ViewSection.FirstCharacter：基于字符串的首字符分组

section.delegate : Component 提供分组标签的外观定义

section.labelPositioning : enumeration 定义分组标签的位置

• ViewSection.InlineLabels：分段标签与列表项内联。-常用
  ViewSection.CurrentLabelAtStart：将当前标签置于视图的开始。
  ViewSection.NextLabelAtEnd:下一个部分标签（在所有可见部分之外）在移动时粘在视图的末尾

section.property : string 指定分组依据的模型属性

currentSection:string:表示当前滚动位置所在的分段（section）的标签名称。这个属性通常与 section 相关属性（如 section.property、section.criteria）一起使用，用于实现分组列表

• 仅当 ListView 的内容按分段（section）分组时，currentSection 才有意义。

ListView.nextSection : string 获取列表中当前可见项的下一个节名称

ListView.previousSection : string 获取列表中当前可见项的前一个节名称

ListView.section : string 获取当前项所属的节名称

section 是什么？
定义：section 是 QML 在渲染分组标题时自动提供的上下文属性（context property）。

值来源：它的值由 section.property 决定。

作用域：section 仅在 section.delegate 内部可用，其他地方无法直接访问。
只读性：section 是只读的，不能手动修改它的值。
依赖关系：必须正确设置 section.property，否则 section 可能为空。

例如：

section {
    property: "name"  // section 的值就是模型中每个条目的 "name" 属性
    criteria: ViewSection.FullString
}
ListElement {
            name: "haha"
            age: 20
            address: "cn"
}
ListElement {
            name: "gk"
            age: 25
            address: "eu"
}
section {
    delegate: Rectangle {
        Text {
            text: section  // 显示如 "haha"、"gk"
            anchors.centerIn: parent
        }
    }
}

如果模型数据是 ListElement { name: “haha” }，那么 section 的值就是 “haha”。

动态性：section 的值会根据当前渲染的分组自动更新。

注意:listview的分组不会自动排序，也就是说，如果property: "name"相同的交替出现时，那么listview则可能会显示多个相同的section.

ListModel {
        id: modelData
        ListElement {
            name: "haha"
            age: 20
            address: "cn"
        }
        ListElement {
            name: "gk"
            age: 25
            address: "eu"
        }
        ListElement {
            name: "gdn"
            age: 28
            address: "am"
        }
        ListElement {
            name: "haha"
            age: 20
            address: "cn"
        }
        ListElement {
            name: "gk"
            age: 25
            address: "eu"
        }
        ListElement {
            name: "gdn"
            age: 28
            address: "am"
        }
    }
    ListView {
        id: view
        anchors.fill: parent
        model: modelData
        spacing: 10

        highlight: Rectangle {
            color: "red"
        }
        highlightMoveDuration: 100
        highlightFollowsCurrentItem: true
        section {
            property: "name" // 分组依据的模型属性
            criteria: ViewSection.FullString // 按完整字符串匹配分组
            delegate: Rectangle {
                // 分段标题的样式
                width: parent.width
                height: 30
                color: "lightgray"
                Text {
                    text: section // 显示分组名称（如 "Fruit"）
                    anchors.centerIn: parent
                }
            }
            //abelPositioning: ViewSection.InlineLabels
        }
        delegate: ItemDelegate {
            width: parent.width - 40
            height: 50

            Rectangle {
                id: bg
                width: 480
                height: 30
                anchors.centerIn: parent

                color: "black"
                radius: 4
                Label {
                    anchors.centerIn: parent
                    color: "white"
                    text: name + age + address
                }
                TapHandler {
                    onTapped: {
                        view.currentIndex = index
                        console.log(view.currentIndex)
                    }
                }
            }
        }
    }

解决办法:需要将name为haha的放在一起,其他name放一起

ListModel {
        id: modelData
        ListElement {
            name: "haha"
            age: 20
            address: "cn"
        }
        ListElement {
            name: "haha"
            age: 20
            address: "cn"
        }
        ListElement {
            name: "gk"
            age: 25
            address: "eu"
        }
        ListElement {
            name: "gk"
            age: 25
            address: "eu"
        }
        ListElement {
            name: "gdn"
            age: 28
            address: "am"
        }
        ListElement {
            name: "gdn"
            age: 28
            address: "am"
        }
    }
    ListView {
        id: view
        anchors.fill: parent
        model: modelData
        spacing: 10

        highlight: Rectangle {
            color: "red"
        }
        highlightMoveDuration: 100
        highlightFollowsCurrentItem: true
        section {
            property: "name" // 分组依据的模型属性
            criteria: ViewSection.FullString // 按完整字符串匹配分组
            delegate: Rectangle {
                // 分段标题的样式
                width: parent.width
                height: 30
                color: "lightgray"
                Text {
                    text: section // 显示分组名称（如 "Fruit"）
                    anchors.centerIn: parent
                }
            }
            labelPositioning: ViewSection.InlineLabels
        }
        delegate: ItemDelegate {
            width: parent.width - 40
            height: 50

            Rectangle {
                id: bg
                width: 480
                height: 30
                anchors.centerIn: parent

                color: "black"
                radius: 4
                Label {
                    anchors.centerIn: parent
                    color: "white"
                    text: name + age + address
                }
                TapHandler {
                    onTapped: {
                        view.currentIndex = index
                        console.log(view.currentIndex)
                    }
                }
            }
        }
    }

动画属性

add : Transition

作用：当新项 首次被添加到列表 时触发动画（例如初始化或动态添加项）。

触发时机：新项首次出现在视图中。

add

addDisplaced : Transition

作用：当新项添加导致 已有项被挤开 时，被挤开的项会触发此动画。

触发时机：已有项因新项插入而移动。

adddisplaced

displaced : Transition

作用： 所有因模型变化导致项移动 的通用动画（涵盖 addDisplaced、removeDisplaced、moveDisplaced）。

触发时机：任何操作（添加、删除、移动）导致项被动移动时。

move : Transition

作用： 当项 主动移动位置（例如通过模型排序）时触发动画。

触发时机：项的位置在模型中主动改变时。

move

moveDisplaced : Transition

作用： 当项移动导致 其他项被挤开 时，被挤开的项触发此动画。

触发时机： 其他项因某项移动而被挤开时。

move

populate : Transition

作用：populate: 当列表 首次加载数据 时，所有项的初始化动画。

触发时机：列表第一次加载模型数据时。

remove : Transition

作用：当项 被删除 时触发动画。

触发时机：项从列表中移除时。

remove

removeDisplaced : Transition

作用：当项删除导致 其他项移动填补空缺 时，移动的项触发此动画。

触发时机： 其他项因某项移除而移动时。

removedisplaced

注意:

• add和addDisplaced ,removeDisplaced和remove ,move 和moveDisplaced 要成对出现
• displaced 是通用被动移动动画（优先级低于具体类型）,它适用于add remove move,当为这三个属性指定同样的动画时使用该属性,其他时候使用具体类型

附加信号

ListView.add()

该附加信号会在视图中添加一个项目后立即发出。如果指定了添加转换，则会在处理此信号后立即应用。

ListView.pooled()

此信号在项目被添加到重用池后发出。 您可以用它来暂停项目中正在进行的计时器或动画，或释放无法重复使用的资源。

只有当 reuseItems 属性为 true 时，才会发出该信号。

ListView.remove()

此附加信号会在一个项目从视图中移除前立即发出。 如果指定了移除转换，则会在处理此信号后应用，前提是 delayRemove 为 false。

ListView.reused()

该信号在项目被重复使用后发出。 此时，该项目已从池中取出并放置在内容视图中，索引和行等模型属性也已更新。 其他非模型提供的属性在项目被重用时不会改变。 应避免在委托中存储任何状态，如果存储了，应在收到此信号时手动重置状态。 此信号在项目被重复使用时发出，而不是在首次创建项目时发出。 只有当 reuseItems 属性为 true 时，才会发出此信号。

方法

decrementCurrentIndex() 将listview的当前项的索引减少 1
incrementCurrentIndex() 将listview的当前项的索引增加 1

decr

forceLayout() 强制listview执行布局更新

当在模型里添加数据.视图未更新可以调用此方法强制刷新

int indexAt(real x, real y) 返回给定坐标 (x, y) 对应的listview的索引。

Item itemAt(real x, real y) 返回给定坐标 (x, y) 对应的listview的项。

同上,只不过返回的不是索引而是视图索引处的项

Item itemAtIndex(int index) 返回给定索引的视图项（Item）对象

positionViewAtBeginning() 将视图定位到列表的开始位置
positionViewAtEnd() 将视图定位到列表的结束位置

beg

positionViewAtIndex(int index, PositionMode mode) 将视图定位到指定索引的位置，并根据给定的 PositionMode 设置显示方式