桌面应用 / 系统课时

用 ListModel 保存列表数据

用 ListModel 保存列表数据

本篇解决 QML 中动态列表数据如何保存和维护的问题。你将使用 ListModel 创建结构化数据源,并通过代码完成新增、修改、删除和清空操作,为后续模型视图展示打下基础。

学习目标

  • 理解 ListModel 与 ListElement 在 QML 数据管理中的职责。
  • 掌握动态修改列表数据的常用方法。
  • 能够编写简单的数据模型并验证变化结果。

使用 ListModel 表达结构化数据

QML 的模型视图体系要求数据源与界面分离。ListModel 用于保存一组具有相同角色结构的数据,每一条记录由 ListElement 描述。

一个列表项通常包含多个角色,例如名称、状态、数量等。角色名称会成为视图 delegate 中访问数据的字段。

qml
import QtQuick

ListModel {
    id: userModel

    ListElement {
        name: "Alice"
        online: true
    }

    ListElement {
        name: "Bob"
        online: false
    }
}

预期结果

text
创建一个包含两条数据的 ListModel。
每条数据拥有 name 和 online 两个角色。

动态追加和修改数据

ListModel 不只适合静态声明,也可以在运行期间通过 JavaScript API 修改。常用方法包括 append、set、remove 和 clear。

append 用于增加新数据,set 用于修改指定索引的数据,remove 用于删除数据,clear 用于清空整个模型。

qml
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    visible: true
    width: 400
    height: 300

    ListModel {
        id: taskModel
    }

    Component.onCompleted: {
        taskModel.append({ title: "学习 QML", done: false })
        taskModel.append({ title: "练习 ListModel", done: false })
        taskModel.set(0, { title: "学习 QML", done: true })
        taskModel.remove(1)
    }
}

预期结果

text
程序启动后模型包含一条数据:
title=学习 QML
done=true

实际项目中,数据通常来自接口请求、文件读取或用户操作。模型负责保存状态,界面组件只负责读取和展示。

选择 ListModel 的使用方式

ListModel 适合数量中等、结构明确且需要被视图组件直接消费的数据。例如任务列表、联系人列表、设置项列表等。

如果数据规模非常大,或者数据来源本身是数据库或 C++ 后端对象,应考虑使用更适合的数据模型实现,例如 C++ 中的 QAbstractListModel。

使用动态角色时需要保持角色名称稳定,否则 delegate 访问字段时容易出现 undefined 数据。

常见操作边界

修改 ListModel 时,索引必须处于有效范围。remove 删除不存在的索引不会产生有效结果,因此业务代码中通常需要先检查 count。

清空模型后,绑定到该模型的视图会自动更新,不需要手动刷新界面。这也是 QML 响应式数据流的重要特点。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ListModel 保存列表数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通