QC++ / Qt 学习之路

Model/View 架构

理解模型/视图分离设计,用标准模型与代理模型驱动列表表格树

进阶第 26 / 48 章第四篇 · Qt 进阶

#为什么要发明 Model/View

假设你用 QTableWidget 写了一个 10 万行的日志查看器。它在内存里为每一个单元格创建一个 QTableWidgetItem 对象,每个对象都带着字体、颜色、对齐、图标、复选状态……结果还没显示出来,几百 MB 内存就没了,滚动卡成幻灯片。

Model / View 架构:数据与显示分离Model 只管数据,View 只管呈现,Delegate 负责绘制与编辑Model 数据源QAbstractItemModel持有真实数据,不关心显示rowCount() / data()中间契约QModelIndexrow / column / parent 定位单元格data() / setData()dataChanged 信号通知刷新View 显示QTableView / QListView只负责呈现,不存数据setModel(model)Delegate 绘制与编辑QStyledItemDelegatepaint() / createEditor()setEditorData() / setModelData()QSortFilterProxyModel(可插拔)sort() / setFilterFixedString():排序与过滤,原始数据不变
Model/View 三者的职责与数据流向

问题的根源是数据和显示耦合在一个对象里。QTableWidget 这类"便利类"(QListWidget、QTreeWidget)把数据存进了控件内部,代价是:

  • 数据量大时内存爆炸;
  • 同一份数据想用表格和图表两种形式展示,得拷两份;
  • 换个过滤条件就得重建整个控件。

Model/View 的解法是把职责切成三块:

角色职责是否存数据
Model(模型)提供数据访问接口,通知变更是(或代理真实数据源)
View(视图)负责绘制与用户交互否,只按需"问"模型
Delegate(委托)负责单个单元格的绘制与编辑控件否

关键洞察:视图不持有数据。它只在需要绘制可见区域时调用 model->data(index, role) 拿值。屏幕上只显示 30 行,就只问 30 行——10 万行数据也只是 10 万条记录,不是 300 万个 QWidget 对象。这就是 Model/View 能扛大数据的原因。

另一个好处是一份数据多个视图:同一个 QAbstractItemModel 可以同时挂到 QTableView、QListView 和 QTreeView 上,改一处三处同步刷新,靠的是模型发出的 dataChanged() 信号。

#模型索引 QModelIndex

视图不会用 (row, column) 直接向模型要数据,而是用一个临时对象 QModelIndex。它内部封装了行、列、父节点指针和一个内部 ID:

C++
QModelIndex index = model->index(row, column, parent);
QVariant value    = index.data(Qt::DisplayRole);   // 或 model->data(index, Qt::DisplayRole)

为什么要绕这一层?因为树形结构需要父节点信息,一个 (row, column) 二元组无法唯一定位树中的节点。而 parent 参数让同一个接口能同时表达"扁平表格"(parent 为无效索引)和"任意深度的树"。

QModelIndex 是一条临时凭证,不是持久句柄:

  • 它由模型内部创建,你只能通过 model->index() 获取;
  • 模型结构变化(插入、删除、重置)后,之前保存的索引可能失效;
  • 用 index.isValid() 判断有效性,无效索引的 row/column 是 -1;
  • 跨模型比较索引没有意义,一定要用 index.model() 确认来源。

需要长期保存位置时,用 QPersistentModelIndex——模型会在结构变化时自动更新它。

#数据角色 Qt::ItemDataRole

同一个单元格可以有多种"值",用 role 区分:

Role含义
Qt::DisplayRole显示的文本(最常用)
Qt::EditRole编辑时的值(如去掉了格式化符号的数字)
Qt::DecorationRole图标 / 颜色块
Qt::ToolTipRole悬停提示
Qt::TextAlignmentRole对齐方式
Qt::BackgroundRole / ForegroundRole背景色 / 文字色
Qt::FontRole字体
Qt::CheckStateRole复选状态
Qt::UserRole自定义数据起点(存 ID、原始对象指针等)

Qt::UserRole 是实战中的利器:单元格显示"张三",但 UserRole 里存他的数据库主键。视图不显示它,处理时却能直接取到,避免了"按名字反查 ID"的脆弱逻辑。

#QAbstractItemModel 必须实现的虚函数

所有模型的基类是 QAbstractItemModel。要让它工作,你必须实现下面这组函数。分两种情形:

函数列表/表格模型树模型说明
rowCount()必须必须行数
columnCount()必须必须列数
data()必须必须取数据
index()基类已提供*必须创建索引
parent()基类已提供*必须取父索引
headerData()建议建议表头文本
flags()可选可选可选中/可编辑
setData()需编辑时需编辑时写数据

* 对于扁平结构,QAbstractListModel 和 QAbstractTableModel 已经帮你实现了 index() 和 parent(),所以这两个子类才是表格/列表的正确起点,不要直接用 QAbstractItemModel。

C++
#include <QApplication>
#include <QTableView>
#include <QStandardItemModel>
#include <QHeaderView>
#include <QSortFilterProxyModel>
#include <QLineEdit>
#include <QVBoxLayout>
#include <QWidget>

struct Person {
    QString name;
    int     age;
    QString city;
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QList<Person> people{
        {"张三", 28, "北京"},
        {"李四", 35, "上海"},
        {"王五", 22, "广州"},
        {"赵六", 41, "北京"},
    };

    // 用标准模型快速搭建
    auto *model = new QStandardItemModel(0, 3);
    model->setHorizontalHeaderLabels({"姓名", "年龄", "城市"});

    for (const Person &p : people) {
        QList<QStandardItem *> row;
        row << new QStandardItem(p.name);
        auto *ageItem = new QStandardItem();
        ageItem->setData(p.age, Qt::DisplayRole);   // 存 int,排序才按数值而非字符串
        row << ageItem;
        row << new QStandardItem(p.city);
        model->appendRow(row);
    }

    // 代理模型:排序 + 过滤
    auto *proxy = new QSortFilterProxyModel();
    proxy->setSourceModel(model);
    proxy->setFilterKeyColumn(-1);                  // -1 = 搜索所有列
    proxy->setFilterCaseSensitivity(Qt::CaseInsensitive);
    proxy->setSortRole(Qt::DisplayRole);

    auto *view = new QTableView();
    view->setModel(proxy);                          // 注意:视图挂代理,不挂源模型
    view->setSortingEnabled(true);
    view->setSelectionBehavior(QAbstractItemView::SelectRows);
    view->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch);
    view->sortByColumn(1, Qt::AscendingOrder);

    auto *filter = new QLineEdit();
    filter->setPlaceholderText("输入关键字过滤(如:北京)");

    auto *w = new QWidget();
    auto *lay = new QVBoxLayout(w);
    lay->addWidget(filter);
    lay->addWidget(view);
    w->resize(480, 320);
    w->show();

    QObject::connect(filter, &QLineEdit::textChanged,
                     proxy, [proxy](const QString &t) {
        proxy->setFilterFixedString(t);
    });

    // 选中变化时读取"源模型"的数据
    QObject::connect(view->selectionModel(), &QItemSelectionModel::currentRowChanged,
                     view, [view, proxy, model](const QModelIndex &cur, const QModelIndex &) {
        if (!cur.isValid()) {
            return;
        }
        QModelIndex src = proxy->mapToSource(cur);  // 代理索引 → 源索引
        qDebug() << "选中:" << model->item(src.row(), 0)->text()
                 << "年龄" << model->item(src.row(), 1)->data(Qt::DisplayRole).toInt();
    });

    return app.exec();
}

上面这段代码里有两个容易踩的坑:

第一,排序错乱。QStandardItem 若用 new QStandardItem(QString::number(age)) 存数字,排序会变成字符串比较,"9" > "41"。正确做法是 setData(int, Qt::DisplayRole) 让模型持有数值类型。

第二,索引属于哪个模型。视图里拿到的索引属于 proxy,必须经 mapToSource() 转换后才能访问 model。反过来从源索引找代理索引用 mapFromSource()。忘记映射,轻则取错行,重则越界崩溃。

#三个视图类怎么选

视图适合的结构常用配置
QListView一维列表(图标、列表模式)setViewMode(IconMode)、setSpacing()
QTableView二维表格setSpan() 合并单元格、setColumnHidden()
QTreeView层次结构setRootIsDecorated()、expandAll()

QTreeView 也能显示扁平表格(模型 parent() 返回无效索引即可),只是列会挤在一起,通常没必要。

#QStringListModel:最简单的模型

只需要显示一列字符串时,不必碰 QStandardItemModel:

C++
#include <QStringListModel>
#include <QListView>
#include <QPushButton>
#include <QVBoxLayout>
#include <QInputDialog>

void listDemo(QWidget *parent)
{
    auto *model = new QStringListModel(parent);
    model->setStringList({"待办 A", "待办 B", "待办 C"});

    auto *view = new QListView();
    view->setModel(model);
    view->setEditTriggers(QAbstractItemView::DoubleClicked
                        | QAbstractItemView::EditKeyPressed);

    auto *addBtn = new QPushButton("添加");
    auto *delBtn = new QPushButton("删除选中");

    QObject::connect(addBtn, &QPushButton::clicked, view, [model, view] {
        int row = model->rowCount();
        model->insertRows(row, 1);
        QModelIndex idx = model->index(row, 0);
        model->setData(idx, "新项目");
        view->edit(idx);                       // 直接进入编辑状态
    });

    QObject::connect(delBtn, &QPushButton::clicked, view, [model, view] {
        QModelIndex cur = view->currentIndex();
        if (cur.isValid()) {
            model->removeRows(cur.row(), 1);
        }
    });
}

注意插入是两步的:先 insertRows() 再 setData()。insertRows() 会正确发出 rowsInserted() 信号,让视图和代理模型同步;如果你直接改内部 QStringList 而不走模型接口,视图完全不知道数据变了。这是 Model/View 的铁律:任何数据变更都必须通过模型接口,让信号得以发出。

#选择模型 QItemSelectionModel

选中状态不属于模型,也不属于视图,而是由独立的 QItemSelectionModel 管理。这样多个视图可以共享同一份选中状态——两个 QTableView 显示同一模型,在其中一个选中行,另一个也会高亮。

C++
#include <QItemSelectionModel>
#include <QModelIndexList>
#include <QSet>
#include <QDebug>

void selectionDemo(QAbstractItemView *view, QAbstractItemModel *model)
{
    QItemSelectionModel *sel = view->selectionModel();

    // 信号:当前项变化 / 选区变化
    QObject::connect(sel, &QItemSelectionModel::currentChanged,
                     view, [](const QModelIndex &cur, const QModelIndex &prev) {
        qDebug() << "当前项:" << cur.row() << ",之前:" << prev.row();
    });

    QObject::connect(sel, &QItemSelectionModel::selectionChanged,
                     view, [](const QItemSelection &sel, const QItemSelection &) {
        qDebug() << "选中区域数:" << sel.size();
    });

    // 读取所有选中行(按行去重)
    QSet<int> rows;
    for (const QModelIndex &idx : sel->selectedIndexes()) {
        rows.insert(idx.row());
    }
    qDebug() << "选中了" << rows.size() << "行";

    // 代码控制选中
    sel->select(model->index(0, 0),
                QItemSelectionModel::ClearAndSelect | QItemSelectionModel::Rows);
}

selectedIndexes() 返回的是每个单元格的索引,选中 3 行 5 列会得到 15 个索引。要得到"选了哪几行"必须按 row() 去重——这是新手最常见的错误之一。

#代理模型:不止排序过滤

QSortFilterProxyModel 插在源模型和视图之间,做一层"虚拟变换":

功能API
模糊过滤setFilterFixedString() / setFilterRegularExpression()
指定过滤列setFilterKeyColumn()
大小写setFilterCaseSensitivity()
动态排序sort() / setDynamicSortFilter(true)
自定义规则子类化重写 filterAcceptsRow()
索引映射mapToSource() / mapFromSource()

代理模型可以串联:源模型 → 过滤代理 → 排序代理 → 视图。如果你需要"先过滤再排序"和"先排序再过滤"两种不同行为,串联顺序就是控制手段。

自定义过滤规则时重写 filterAcceptsRow():

C++
#include <QSortFilterProxyModel>
#include <QDate>

class AgeRangeProxy : public QSortFilterProxyModel
{
    Q_OBJECT
public:
    void setRange(int min, int max)
    {
        m_min = min;
        m_max = max;
        invalidateFilter();            // 关键:通知重新过滤
    }

protected:
    bool filterAcceptsRow(int sourceRow, const QModelIndex &sourceParent) const override
    {
        QModelIndex idx = sourceModel()->index(sourceRow, 1, sourceParent);  // 年龄列
        if (!idx.isValid()) {
            return false;
        }
        int age = sourceModel()->data(idx, Qt::DisplayRole).toInt();
        return age >= m_min && age <= m_max;
    }

private:
    int m_min = 0;
    int m_max = 150;
};

setRange() 里那句 invalidateFilter() 不能省:改了过滤条件必须显式触发重算,否则界面纹丝不动。同理,若源模型的 data() 返回值依赖某个外部状态,状态变了要调 invalidate() 或发出 dataChanged()。

Qt 5 提示:Qt 5 用 setFilterRegExp(QRegExp),Qt 6 已改为 setFilterRegularExpression(QRegularExpression)。另外 Qt 6 中 QStandardItemModel::itemFromIndex() 等接口签名未变,但建议在 CMake 中链接 Qt6::Widgets 与 Qt6::Core。

#小结

  1. Model/View 的核心是视图不持有数据,只按需向模型"问",因此能承载海量数据。
  2. QModelIndex 是带父节点信息的临时凭证,结构变更后可能失效,长期保存用 QPersistentModelIndex。
  3. 扁平数据继承 QAbstractTableModel / QAbstractListModel,树形数据才继承 QAbstractItemModel。
  4. 任何数据变更都必须走模型接口(setData、insertRows…),否则信号不发、视图不更新。
  5. QSortFilterProxyModel 提供排序过滤与索引映射,视图与代理之间的索引必须 mapToSource() / mapFromSource() 转换。

#练习

  1. 用 QStringListModel + QListView 做一个待办清单,支持添加、删除、双击重命名,并用 QSettings 持久化。
  2. 在表格示例中增加一个"只显示某城市"的 QComboBox,用 setFilterKeyColumn(2) + setFilterFixedString() 实现联动过滤。
  3. 子类化 QSortFilterProxyModel 重写 filterAcceptsRow(),实现"年龄区间 + 关键字"双重过滤。
  4. 让两个 QTableView 共享同一个模型与同一个 QItemSelectionModel,观察选中状态同步效果,并说出这与"各自一个选择模型"的区别。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。