链表分段（List Section）

QML中ListView（链表视图）的分段（Section） 功能——这是ListView将数据按指定规则分组展示的核心特性，也叫“分组列表”，本质是通过指定“分段键（section key）”将模型数据划分为多个逻辑分组，每个分组有独立的分段标题（Section Header），实现如“按字母分类的联系人列表”“按日期分类的订单列表”等效果。

简单来说：链表分段 = 数据分组（按指定字段） + 分段标题（Header） + 列表展示（分组隔离），是提升长列表可读性的关键手段。

一、链表分段的核心概念

1. 核心组成

ListView实现分段需配置3个核心属性，缺一不可：

补充：ViewSection是分段规则的枚举类，核心值：

• ViewSection.FullString：按属性完整值分组（如“水果”“蔬菜”）；
• ViewSection.FirstCharacter：按属性首字符分组（如联系人按首字母A/B/C）。

2. 核心特性

• 自动分组：ListView根据section.property自动将相同值的项归为一组；
• 标题固定：滚动列表时，当前分组的标题会“吸附”在列表顶部（可配置）；
• 分段导航：可通过sectionLabelPosition控制标题位置，支持“标题在组首”或“标题悬浮”；
• 兼容动态模型：模型数据新增/修改时，分段会自动更新。

二、ListView分段完整示例（按类别分组）

以下示例实现“按食品类别（水果/蔬菜）分组”的分段列表，包含分段标题、分组隔离、悬浮标题等核心特性：

import QtQuick 2.15
import QtQuick.Window 2.15
import QtQuick.Controls 2.15

Window {
    width: 300
    height: 400
    visible: true
    title: "ListView分段（Section）示例"

    // 1. 带分段键的模型数据（包含category字段用于分组）
    ListModel {
        id: foodModel
        ListElement { name: "苹果"; category: "水果"; price: 5.99 }
        ListElement { name: "香蕉"; category: "水果"; price: 3.50 }
        ListElement { name: "橙子"; category: "水果"; price: 4.20 }
        ListElement { name: "青菜"; category: "蔬菜"; price: 2.99 }
        ListElement { name: "番茄"; category: "蔬菜"; price: 4.50 }
        ListElement { name: "黄瓜"; category: "蔬菜"; price: 3.20 }
    }

    // 2. 核心：带分段的ListView
    ListView {
        anchors.fill: parent
        model: foodModel
        delegate: foodDelegate  // 项代理
        spacing: 5
        padding: 5

        // 分段核心配置
        section {
            property: "category"  // 按category字段分组
            criteria: ViewSection.FullString  // 按完整值分组
            delegate: sectionDelegate  // 分段标题代理
            labelPosition: ViewSection.Inline  // 标题位置：组内首行（悬浮用Floating）
            // 可选：标题吸附顶部（Floating模式下生效）
            // sectionLabelHorizontalAlignment: Qt.AlignLeft
            // sectionLabelVerticalOffset: 0
        }

        // 可选：开启分段悬浮标题（滚动时标题固定在顶部）
        // section.labelPosition: ViewSection.Floating
    }

    // 3. 分段标题代理（每个分组的标题样式）
    Component {
        id: sectionDelegate
        Rectangle {
            width: parent.width
            height: 30
            color: "#e0e0e0"
            Text {
                anchors.centerIn: parent
                text: section  // section变量自动指向当前分组值（水果/蔬菜）
                font.bold: true
                font.size: 16
                color: "#333"
            }
        }
    }

    // 4. 普通项代理（分组内的列表项）
    Component {
        id: foodDelegate
        Rectangle {
            width: parent.width
            height: 50
            radius: 6
            color: "#f5f5f5"
            Column {
                anchors.centerIn: parent
                Text { text: model.name; font.size: 16 }
                Text { text: "¥" + model.price.toFixed(2); font.size: 12; color: "#666" }
            }
        }
    }
}

三、关键配置详解

1. 分段标题位置（labelPosition）

悬浮标题示例：

section {
    property: "category"
    criteria: ViewSection.FullString
    delegate: sectionDelegate
    labelPosition: ViewSection.Floating  // 悬浮标题
    // 标题偏移（避免遮挡）
    sectionLabelVerticalOffset: 0
}

2. 按首字母分组（FirstCharacter）

适合联系人、商品名称等按首字母分类的场景：

// 模型：添加letter字段（或直接用name首字母）
ListModel {
    id: contactModel
    ListElement { name: "张三"; letter: "Z" }
    ListElement { name: "李四"; letter: "L" }
    ListElement { name: "王五"; letter: "W" }
}

// ListView分段配置
section {
    property: "letter"
    criteria: ViewSection.FirstCharacter  // 按首字母分组
    delegate: sectionDelegate
    labelPosition: ViewSection.Floating
}

3. 分段导航（快速定位分组）

结合positionViewToSection方法，可实现“点击字母快速跳转到对应分组”：

// 字母导航栏
Row {
    anchors.bottom: parent.bottom
    anchors.horizontalCenter: parent.horizontalCenter
    spacing: 5

    Button {
        text: "水果"
        onClicked: listView.positionViewToSection("水果", ListView.Beginning)
    }
    Button {
        text: "蔬菜"
        onClicked: listView.positionViewToSection("蔬菜", ListView.Beginning)
    }
}

四、分段列表的进阶用法

1. 动态修改分段规则

可通过代码动态修改分段属性，实现“切换分组维度”（如按价格/类别切换）：

Button {
    text: "按价格分组"
    onClicked: {
        listView.section.property = "priceRange"  // 新增priceRange字段
        listView.section.criteria = ViewSection.FullString
        listView.reload()  // 刷新列表
    }
}

2. 分段样式差异化

不同分组的标题/项可设置不同样式（如水果分组红色，蔬菜分组绿色）：

// 分段标题代理差异化
Component {
    id: sectionDelegate
    Rectangle {
        width: parent.width
        height: 30
        // 根据分组值动态设置颜色
        color: section === "水果" ? "#ff6b6b20" : "#2ecc7120"
        Text {
            anchors.centerIn: parent
            text: section
            font.bold: true
            color: section === "水果" ? "#ff6b6b" : "#2ecc71"
        }
    }
}

五、使用注意事项

1. 模型数据排序：

   • ListView分段不会自动排序，需确保模型数据按分段键排序（如水果项全部放在蔬菜项前）；
   • 可通过ListModel的sort方法排序：foodModel.sort("category", Qt.AscendingOrder)。

2. 性能优化：

   • 大量数据时，分段标题代理尽量简化（避免复杂渐变/阴影）；
   • 悬浮标题（Floating）会增加少量性能开销，低配置设备建议用Inline模式。

3. 兼容性：

   • ViewSection.FirstCharacter对中文首字母支持有限（需手动给模型添加拼音首字母字段）；
   • Qt 5.12+对分段功能的支持更完善，低版本可能存在悬浮标题偏移问题。

总结

1. 链表分段核心：ListView通过section配置实现数据分组，核心是section.property（分组字段）、section.criteria（分组规则）、section.delegate（标题样式）。
2. 关键特性：支持“Inline（内联）”和“Floating（悬浮）”两种标题模式，可通过positionViewToSection实现分组快速导航。
3. 使用要点：模型数据需提前按分段键排序，中文首字母分组需手动处理，低配置设备优先用Inline标题模式保证性能。

链表分段是实现结构化长列表的核心功能，掌握后可轻松实现联系人列表、订单列表、商品分类列表等常见业务场景，大幅提升列表的可读性和交互体验。