Model/View 架构
理解模型/视图分离设计,用标准模型与代理模型驱动列表表格树
#为什么要发明 Model/View
假设你用 QTableWidget 写了一个 10 万行的日志查看器。它在内存里为每一个单元格创建一个 QTableWidgetItem 对象,每个对象都带着字体、颜色、对齐、图标、复选状态……结果还没显示出来,几百 MB 内存就没了,滚动卡成幻灯片。
问题的根源是数据和显示耦合在一个对象里。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:
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。
#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:
#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 显示同一模型,在其中一个选中行,另一个也会高亮。
#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():
#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。
#小结
- Model/View 的核心是视图不持有数据,只按需向模型"问",因此能承载海量数据。
QModelIndex是带父节点信息的临时凭证,结构变更后可能失效,长期保存用QPersistentModelIndex。- 扁平数据继承
QAbstractTableModel/QAbstractListModel,树形数据才继承QAbstractItemModel。 - 任何数据变更都必须走模型接口(
setData、insertRows…),否则信号不发、视图不更新。 QSortFilterProxyModel提供排序过滤与索引映射,视图与代理之间的索引必须mapToSource()/mapFromSource()转换。
#练习
- 用
QStringListModel+QListView做一个待办清单,支持添加、删除、双击重命名,并用QSettings持久化。 - 在表格示例中增加一个"只显示某城市"的
QComboBox,用setFilterKeyColumn(2)+setFilterFixedString()实现联动过滤。 - 子类化
QSortFilterProxyModel重写filterAcceptsRow(),实现"年龄区间 + 关键字"双重过滤。 - 让两个
QTableView共享同一个模型与同一个QItemSelectionModel,观察选中状态同步效果,并说出这与"各自一个选择模型"的区别。