上一篇的重命名工具,每次点「预览」都先 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 三层

Model(模型)持有数据,回答「有多少行、多少列、每个格子显示什么」。数据变化时发出 dataChanged、rowsInserted 等信号。
View(视图)QTableView、QListView、QTreeView。负责滚动、选中、编辑入口。它只从模型取数据,不直接持有业务数据。
Delegate(委托)负责单个格子的绘制和编辑器。默认委托够用,需要自定义进度条、标签、按钮时才写 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 的调试工具或计时日志找到热点,再决定是合并通知、加缓存,还是换委托,不要一上来就自己造轮子。日志要打在关键路径上,别只记一句「刷新完成」。

判断该不该用 Model/View,看两个信号:数据量是否大到全量刷新会卡,是否需要在多个视图之间共享同一份数据。满足任意一条,模型的收益就超过学习成本。

小结

界面不动,不是视图坏了,是没人告诉它数据变了。插入用 begin/endInsertRows,修改用 dataChanged,删除用 begin/endRemoveRows;跨线程只发信号,让槽在 UI 线程执行。这三条守住了,模型视图就能稳定工作。

当天可以自己验证的练习:

  1. 把上面的纯 C++ 通知示例改成一次更新连续三行,只发一条范围通知,对比输出行数。
  2. 去掉 setProgress 里的越界判断,传入 -1,观察程序行为,理解模型为什么要自己防御。
  3. 在 Qt 版 addTask 里故意删掉 beginInsertRows,观察视图是否错乱。
  4. 把 dataChanged 的列索引写成 index(row, 0)..index(row, 0),只更新任务名列,观察进度列是否还刷新。
  5. 用 QSortFilterProxyModel 排序后编辑一行,观察行号变化,再用 mapToSource 修正。

下一篇讲编译、静态链接与打包分发。代码写到这里,功能已经不是问题;真正让项目卡住的是「为什么开发机能跑,客户机打不开」。下一篇把运行库、静态链接、Qt 部署和安装包一次算清楚。