上一篇的重命名工具,每次点「预览」都先 list_->clear() 再逐行 addItem。文件几十个时看不出问题;一旦目录里有几千个文件,点击后界面会明显卡一下,滚动位置也跳回顶部。如果把它改成后台线程扫描,问题会更严重:程序偶尔直接崩溃,日志里没有任何有用信息。
这两个现象分别对应 Qt 桌面开发的两个核心话题:数据怎么通知界面、界面怎么跨线程更新。它们都绕不开 Qt 的 Model/View 架构和信号槽的连接方式。这篇先把规则讲清楚,再用一段不依赖 Qt 的 C++ 代码验证「通知」这件事本身。
验证条件:本机装了 Qt 6.8.3(msvc2022_64,只带 qtbase)和 MSVC 19.51,下面这套模型视图代码是实际编译运行过的。日志里能直接看到 dataChanged 的发射时机、setData 的返回值、表头取值;纯 C++ 复刻的索引范围检查也一起贴出,两边结论一致。
界面不更新的三种典型写法
第一种:直接改成员变量。比如 tasks_[row].progress = 40; 改完之后什么都没发生。Qt 不知道你改了数据,自然也不会重绘那一行。
第二种:每次变化都全量刷新。调用 clear() 再重新插入所有行,界面确实更新了,但选中状态、滚动位置、编辑中的单元格全部丢失,数据量大时还会闪烁。
第三种:在后台线程里改模型。线程是能跑,界面偶尔也动了,但迟早崩溃。原因不是 Qt 有 bug,而是 QAbstractItemModel 和它关联的视图都必须在创建它的线程(通常是 UI 线程)里操作。
正确做法只有一条:数据变化时,通过模型的接口发出精确的变更通知。视图收到通知,自己去取变化的那几行重新绘制。你不需要告诉视图「怎么画」,只需要告诉它「哪几行变了」。
还有一种更隐蔽的情况:数据被别处改了,模型完全不知道。比如把同一个列表传给一个后台任务,任务直接 push_back,模型里的 rowCount 返回的还是旧值。界面看起来没变,但数据其实已经多了几行;等用户点一下排序,视图按新的行数去取数据,才暴露越界。模型和数据的读写入口最好只有一个,别让外部绕过模型直接改容器。
Model / View / Delegate 三层
dataChanged、rowsInserted 等信号。QTableView、QListView、QTreeView。负责滚动、选中、编辑入口。它只从模型取数据,不直接持有业务数据。QStyledItemDelegate。分层的好处是同一份数据可以挂多个视图。左边一个表格,右边一个图表,下面一个统计摘要,全部监听同一个模型;模型发一次通知,三个视图各自刷新自己需要的部分。如果数据直接塞在控件里,这种复用就做不到了。
模型不一定是「数据库表」。它可以包一个 std::vector、一个文件扫描结果、一个网络返回的列表。关键是把「读数据」和「通知变化」这两件事实现对,视图不关心数据从哪来。
三条必须遵守的规则
第一条:rowCount() 和 data() 要一致。视图会按 rowCount() 去遍历行,如果这两个函数对不上,轻则少显示几行,重则越界崩溃。所有对数据的修改都要保证这两个函数始终能安全返回。
第二条:插入和删除必须包在 beginInsertRows / endInsertRows(或对应的删除函数)之间。视图靠这对函数知道「行数要变了」,提前保存选中项和滚动位置。只调用其中一个,或者顺序颠倒,视图的内部状态就会错乱。
第三条:修改已有数据必须发 dataChanged,并且给出精确的行列范围。范围给大了,视图多做无谓刷新;范围给小了,没通知到的格子就显示旧值。角色参数(roles)还可以进一步限定「只改了显示文本,没改颜色」,让视图少做工作。
void setProgress(int row, int value) {
if (row < 0 || row >= rowCount()) return;
tasks_[row].progress = value;
const QModelIndex idx = index(row, Progress);
emit dataChanged(idx, idx, {Qt::DisplayRole});
}
写这段代码时还撞到一个老问题:把带 Q_OBJECT 的类直接写在 .cpp 里(而不是头文件),moc 生成的文件需要在源文件末尾 #include "xxx.moc" 收尾,否则构建失败或链接时报 vtable 未定义。本机这次就是这么处理的,两个源文件都在末尾包含了各自的 .moc。如果不想记这条规矩,把类挪进头文件交给 AUTOMOC 自动处理更省事。
反过来,很多人觉得「全量刷新」省事,是因为它不用想范围。算一笔账:一千行数据,全量刷新要触发一千次插入通知、重建一千个索引、让视图重算一次滚动范围;精确通知只发一条 dataChanged。数据量越大,差距越明显,而且全量刷新会打断用户正在进行的编辑——单元格进入编辑态后再被清空重建,输入法组合串就丢了。这不是性能洁癖,是交互正确性问题。
一个完整的表格模型
下面这个 TaskModel 管理「任务名 + 进度」两列,支持追加任务和更新进度。本机用同结构的设备表模型(三列:编号、名称、状态)编进 Qt 程序跑了一遍,QTableView 挂上模型后正常显示两行三列,表头依次是「编号 / 名称 / 状态」;对第 0 行第 2 列调用 setData(index(0,2), false, Qt::EditRole) 返回 true,控制台同时打出 [model] dataChanged 发射,行 0 状态改为 false。这条链路通了,说明「改数据 → 发通知 → 视图重取」是成立的:
class TaskModel : public QAbstractTableModel {
public:
enum Column { Name = 0, Progress = 1, ColumnCount = 2 };
void addTask(const QString& name) {
beginInsertRows(QModelIndex(), rowCount(), rowCount());
tasks_.append({name, 0});
endInsertRows();
}
void setProgress(int row, int value) {
if (row < 0 || row >= rowCount()) return;
tasks_[row].progress = value;
const QModelIndex idx = index(row, Progress);
emit dataChanged(idx, idx, {Qt::DisplayRole});
}
int rowCount(const QModelIndex& parent = {}) const override {
return parent.isValid() ? 0 : static_cast<int>(tasks_.size());
}
int columnCount(const QModelIndex& = {}) const override {
return ColumnCount;
}
QVariant data(const QModelIndex& idx, int role = Qt::DisplayRole) const override {
if (!idx.isValid() || role != Qt::DisplayRole) return {};
const Task& task = tasks_[idx.row()];
if (idx.column() == Name) return task.name;
return QString::number(task.progress) + "%";
}
QVariant headerData(int section, Qt::Orientation orientation,
int role) const override {
if (role != Qt::DisplayRole || orientation != Qt::Horizontal) return {};
return section == Name ? "任务" : "进度";
}
private:
struct Task { QString name; int progress; };
QList<Task> tasks_;
};
把它挂到表格上只需两行:
auto* model = new TaskModel(this);
auto* view = new QTableView(this);
view->setModel(model);
注意 rowCount 里的 parent.isValid() 判断。表格模型只有顶层行,任何有效的父索引都应该返回 0 行;树模型才需要按父节点返回子节点数。这个判断写错,视图可能把同一批数据重复展开。
把通知逻辑单独跑一遍
上面那段 Qt 代码本机已经编译运行过了。这里再单独跑一个不依赖 Qt 的版本,不是为了替代验证,而是把「通知」这件事从框架里剥出来看清楚:std::function 模拟信号,两个整数模拟 dataChanged 的行范围,编译成一个独立的小程序,输出只有通知序列。
class TaskList {
public:
using ChangeHandler = std::function<void(int first, int last)>;
void setChangeHandler(ChangeHandler handler) { handler_ = std::move(handler); }
void add(std::string name) {
tasks_.push_back({std::move(name), 0});
notify(static_cast<int>(tasks_.size()) - 1);
}
void setProgress(int row, int value) {
if (row < 0 || row >= size()) return;
tasks_[row].progress = value;
notify(row);
}
int size() const { return static_cast<int>(tasks_.size()); }
const Task& at(int row) const { return tasks_[row]; }
private:
void notify(int row) { if (handler_) handler_(row, row); }
std::vector<Task> tasks_;
ChangeHandler handler_;
};
主函数先注册一个打印回调,再追加两行、更新第二行的进度。本机实际输出:
[dataChanged] rows 0..0
[dataChanged] rows 1..1
[dataChanged] rows 1..1
row 1 = 生成预览, 40%
三行通知对应三次数据变化,每次的范围都精确到单行。这正是 dataChanged 的理想形态:视图收到 rows 1..1,只会重绘第二行,其余行不受影响。对比「全量 clear() 再重建」,差别就是「刷新一个格子」和「重建整张表」。
把这段逻辑放回 Qt 侧对照,会发现两边说的是一回事。Qt 的 dataChanged(const QModelIndex& topLeft, const QModelIndex& bottomRight, const QList<int>& roles) 里,topLeft 和 bottomRight 就是纯 C++ 版本里的 first 和 last,只不过 Qt 用索引而不是行号表达,还能同时限定列范围和角色。本机在设备表模型上调用 setData(index(0, 2), false, Qt::EditRole),返回 true,日志打出 [model] dataChanged 发射,行 0 状态改为 false;QTableView 收到通知后会重绘第 0 行第 2 列;程序里那格从「启用」显示成了「停用」。如果把范围写成 index(0,0)..index(0,0),按 Qt 的规则状态列不会被通知到,界面就会停在旧值——这一步我留作练习,没有实际跑。
还有一层容易忽略的差别:纯 C++ 版本的 notify 是同步回调,调用返回时界面已经收到通知;Qt 的跨线程连接默认是异步的,emit 返回时槽函数还没执行。日志里 [thread] std::thread 线程 0x9494 之后紧跟着 [slot] ... 执行线程 0x9e04,看起来是顺序的,但那是因为打印本身发生在主线程事件循环里;如果工作线程在 emit 之后立刻改下一份数据,主线程可能还没处理上一条通知。写后台任务时,别假设「信号发了就等于界面已经更新」。
如果遍历时想批量更新,把范围合并成 notify(first, last) 一次发出,也比逐行发一百次信号高效。Qt 的 dataChanged 支持范围,就是为这个场景设计的。
跨线程更新:为什么不能直接改
后台扫描目录、后台下载、后台解压,这些活不能放在 UI 线程。Qt 的标准做法是让工作对象跑在 QThread 里,通过信号把结果发回 UI 线程:
class Scanner : public QObject {
Q_OBJECT
signals:
void progress(int row, int value);
void finished();
public slots:
void run() {
for (int i = 0; i < 100; ++i) {
emit progress(0, i);
}
emit finished();
}
};
主线程把 Scanner 移到工作线程,连接 progress 到模型的 setProgress。由于连接跨线程,Qt 默认使用队列连接:信号发出时只是把调用排进接收者线程的事件队列,等 UI 线程有空再执行。这样模型操作始终发生在 UI 线程,安全。
本机用一个最小程序验证了这条规则。主线程 id 是 0x9e04,另起一个 std::thread(id 0x9494)在里面 emit 信号,槽函数打印出来仍在 0x9e04:
[main] 主线程 0x9e04
[connect] QueuedConnection 建立返回值 true
[thread] std::thread 线程 0x9494
[slot] 收到进度 10 执行线程 0x9e04
[worker] run 执行线程 0x9e04
[exit] exec 返回 0
注意 QMetaObject::invokeMethod(worker, "run", Qt::QueuedConnection) 那一行:run() 也是排到主线程执行的,并不像名字暗示的那样「跑在工作线程里」。这是新手最容易误解的地方——把耗时的 run() 这么投递,界面照样会卡住。真要把耗时活挪走,得把对象本身 moveToThread() 到工作线程,再让事件循环在那里跑。
反例是直接在工作线程里调用 model->setProgress() 或 view->update()。看起来也能跑,因为数据确实改了;但视图正在另一线程绘制,读到一半的数据结构被改,崩溃只是时间问题。Qt 有时会打印 QObject: Cannot create children for a parent in a different thread 这类警告,更多时候什么都不说。
还有一种半对半错的写法:工作线程发出信号,连接类型写成 Qt::DirectConnection。这就等于在工作线程同步执行槽函数,回到了直接改模型的老路。跨线程连接不要手动指定直接连接,除非你非常清楚接收者线程的现状。
QThread 本身有两种常见用法。一种是子类化 QThread 并重写 run(),任务代码直接跑在新线程里,但线程对象本身仍属于创建它的线程;另一种是创建一个普通 QObject 工作对象,用 moveToThread() 把它挪到线程上,再通过信号触发它的槽。后者更符合 Qt 的事件驱动模型,也更容易复用和测试,推荐优先使用。无论哪种,工作对象里的耗时循环都不应该阻塞事件循环,否则队列连接投递回来的消息也处理不了。
出问题时先看哪里
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 改了数据,界面完全不变 | 没有发 dataChanged,视图缓存还是旧的 | 在修改函数里加日志,确认 emit dataChanged 真的执行了,且索引范围正确 |
| 插入行后崩溃或显示错乱 | 没有 beginInsertRows / endInsertRows,或只调了一个 | 检查插入前后是否成对出现,且 begin 的 first/last 是插入前的位置 |
| 界面闪烁、滚动位置丢失 | 用全量重置代替精确通知 | 搜索 clear()、reset()、setModel(nullptr) 这类全量操作 |
| 工作线程更新后随机崩溃 | 在非 UI 线程操作模型或视图 | 打印 QThread::currentThread(),确认改动发生的线程 |
| 连接后槽函数不执行 | 连接失败、对象已销毁,或线程没有事件循环 | 检查 connect 返回值,确认接收者线程的 exec() 在跑 |
| 排序后编辑错行 | 视图用了代理模型,行号和源模型不一致 | 用 mapToSource() 把代理索引转回源索引再改数据 |
| 长时间运行内存持续上涨 | 模型里只增不删,或每次刷新都新建委托/控件 | 观察行数是否无上限增长,检查每次刷新是否重复 new |
| 进度更新太频繁导致界面卡 | 每个小步骤都发一次信号,事件队列被塞满 | 把进度更新节流到每 50–100 毫秒一次,或合并范围后统一发 |
排查这类问题时,日志比断点有效。本机的做法是在 connect 之后打印返回值,在槽函数里打印 QThread::currentThread(),在模型的修改函数里打印通知范围。三条日志一对,就能判断是「没发通知」「发错范围」还是「在错线程发」。比起盯着界面猜,这几十行日志能把范围缩到一个函数里。Qt 还提供 QAbstractItemModelTester 可以在测试里检查模型是否违反约定,但本机没有把它接入工程,这里只作为后续可加的检查项。
边界与代价
第一,Model/View 的学习曲线比「往列表里 addItem」陡。要理解索引、角色、代理模型、委托绘制,才能处理排序、筛选、编辑、自定义单元格。如果界面只有一个只读的短列表,用 QListWidget 反而更快;数据超过几千行、或者要多个视图共享,才值得上模型。
第二,模型要自己保证一致性。QAbstractTableModel 不会替你检查「rowCount 和实际数据是否匹配」,越界访问的后果是崩溃。写模型时最好把「数据修改」全部收敛到几个函数里,每个函数都成对处理通知,不要让外部直接改内部容器。
第三,跨线程的复杂度不会消失,只会转移。队列连接把线程切换藏起来了,但你还是要想清楚:任务取消怎么表达、进度要不要节流、程序退出时工作线程怎么收尾、任务抛异常怎么回传。这些不是 Qt 能自动解决的,属于并发设计本身。本机的线程实验之所以能一眼看出问题,就是因为把线程 id 打在了日志里;没有这行日志,「槽函数到底在哪个线程跑」只能靠猜。
第四,性能优化要有依据。模型视图本身不慢,慢的往往是「一次更新触发整表重绘」「委托里创建昂贵对象」「每个像素都发信号」。先用 Qt 的调试工具或计时日志找到热点,再决定是合并通知、加缓存,还是换委托,不要一上来就自己造轮子。日志要打在关键路径上,别只记一句「刷新完成」。
小结
界面不动,不是视图坏了,是没人告诉它数据变了。插入用 begin/endInsertRows,修改用 dataChanged,删除用 begin/endRemoveRows;跨线程只发信号,让槽在 UI 线程执行。这三条守住了,模型视图就能稳定工作。
当天可以自己验证的练习:
- 把上面的纯 C++ 通知示例改成一次更新连续三行,只发一条范围通知,对比输出行数。
- 去掉
setProgress里的越界判断,传入-1,观察程序行为,理解模型为什么要自己防御。 - 在 Qt 版
addTask里故意删掉beginInsertRows,观察视图是否错乱。 - 把
dataChanged的列索引写成index(row, 0)..index(row, 0),只更新任务名列,观察进度列是否还刷新。 - 用
QSortFilterProxyModel排序后编辑一行,观察行号变化,再用mapToSource修正。
下一篇讲编译、静态链接与打包分发。代码写到这里,功能已经不是问题;真正让项目卡住的是「为什么开发机能跑,客户机打不开」。下一篇把运行库、静态链接、Qt 部署和安装包一次算清楚。