在 Qt 5.14.2 自带的 Examples 目录下，QtConcurrent Progress Dialog 属于那种看起来不起眼、实际营养很足的例子。第一次用 Qt 做耗时任务的人，十有八九会问“后台在跑，界面进度条怎么跟着走”，而官方这个示例正是标准答案。它不复杂，却把线程、信号槽、模态对话框、取消协作这些点串在了同一段流程里。适合谁？刚上手 Qt 并发编程的开发者、要在自己项目里塞进度反馈但又不想从零造轮子的人。读完你还会发现，自带的例子不是用来抄的，而是用来理解 API 设计意图的。

1. 示例整体设计：一个对话框串起三条主线

1.1 官方示例在解决哪些具体痛点

先说 UI 阻塞。这是最直观的问题。耗时计算如果直接放在主线程里，窗口会陷入“拖不动、点不了、白屏”的状态，用户第一反应是程序崩了。示例把任务交给线程池，主线程的事件循环继续转，窗口才能保持响应。

然后是进度不可见。任务在后台跑，如果界面上没有任何反馈，用户只能干等，时间一长就会失去耐心。进度条的意义不只是“显示百分比”，更是给用户一个确定性的预期：它告诉用户“已经在处理了、一共要处理多少、现在到哪个位置了”。这个过程需要一条可靠的通道，把后台线程里发生的事实时传回 UI 线程。

最后是取消控制。长任务应当能被用户中途叫停，但停止必须协作，不能强杀线程。直接用QThread::terminate()那种做法会留下锁未释放、资源未清理、状态不一致等一堆后遗症。官方示例展示的是一种安全的取消姿势：界面上发取消请求，后台任务在合适的检查点自己退出。

这三件事读起来都像常识，但放一起就难了。初学者常犯两种错：一种是把任务塞进QThread之后忘了如何正确把进度送回主线程；另一种是不做取消，界面一弹出来就只能等它自己跑完。官方示例故意放在 QtConcurrent 模块里，就是想告诉你，这种场景不需要自己管理底层线程。

1.2 为什么选 QtConcurrent，而不是直接开 QThread

QtConcurrent 属于高级并发接口。QThread更像是一个“线程对象”，你需要自己 start、自己管理生命周期、自己写信号把结果传回事件循环。QtConcurrent::run、QtConcurrent::map则把一个函数或一组操作交给内部线程池调度，返回一个带状态和结果句柄的QFuture。你只需要关心“要算什么”，不用关心“线程什么时候生、什么时候死、生几个”。

打个不严谨的比方：QThread 像是你亲自开一家外卖店，店里只有一个骑手，你得管他的排班、路线和休息时间；QtConcurrent 则是叫跑腿平台，你只管下单，平台自己调度骑手。对这个示例里的短暂批量任务，让平台来处理明显更省心，代码量也更少。

当然，这不代表 QThread 没用。需要常驻线程、持续监听 IO、有着严格线程亲和性的任务，QtConcurrent 并不擅长。但就“一个耗时任务 + 进度反馈”这种需求来说，QtConcurrent 是更贴近问题的抽象层次。

1.3 一次完整流程是怎么流转的

把流程拆开看，这个示例可以分成五步：

1. 用户点击“开始”。
2. 主线程创建一个进度对话框，并把QFutureWatcher的信号和对话框控件连接好。
3. 调用QtConcurrent启动后台任务，拿到QFuture之后通过setFuture交给 watcher。
4. 后台任务一边执行，一边更新 QFuture 内部的进度状态；watcher 收到变化后在事件循环里发信号。
5. UI 槽函数更新进度条；任务结束或用户取消时关闭对话框。

这套流程的关键在于QFutureWatcher是连接“异步世界”和“事件循环世界”的桥梁。后台线程不需要认识任何 QWidget，它只更新 QFuture 内部状态；界面上也不需要轮询，只用信号槽等通知。这也是官方示例最值得抄的部分。

2. 核心组件与关键细节解析

2.1 QFutureWatcher：不要在界面里直接轮询 QFuture

许多人第一次看到QFuture::isRunning()或progressValue()，第一反应是“那我开个 QTimer 每 100ms 去读它”。这个思路在小程序里能跑，但不够优雅，而且在高频更新时会把 UI 拖累。官方样本用的是 watcher。

QFutureWatcher本质是一个在任务和界面之间做转播的对象。它持有一份 QFuture，并把 QFuture 里变化翻译成 Qt 信号：progressRangeChanged、progressValueChanged、resultReadyAt、finished等。连接方式在主线程中建立，跨线程时 Qt 会自动选择队列连接，不需要你手动加锁。也就是说，后台线程只管写，界面线程只管收，数据同步交给 Qt 的元对象系统去处理。

这里有第一个非常容易踩的坑：watcher 的生命周期一定要超过任务本身。示例里要么把 watcher 放在顶层对象成员里，要么在任务开始时 new 一个，并在 finished 信号里 deleteLater；如果只在函数里定义了局部 watcher，函数一结束 watcher 就析构，后续进度信号就全部丢失，对话框会永远停在 0%。

2.2 QProgressDialog：模态、最小值时长、取消按钮

QProgressDialog 有两个容易被忽略的属性。一个是setMinimumDuration，默认是 4000ms，意思是任务跑得比这短就不显示对话框，避免一闪而过。如果你希望“开始点击后立刻出现进度条”，需要显式设为 0。另一个是setWindowModality，示例里一般用Qt::WindowModal，它会阻止与该窗口交互，但不至于像Qt::ApplicationModal那样锁死整框架。

取消按钮是自带功能，setCancelButtonText可以改文案。但注意，这个按钮被点击时，QProgressDialog 会发canceled信号并默认隐藏自己，任务本身不会被杀死。真正停止任务需要通过QFuture::cancel()协作取消，这一点放到后面常见问题章节展开。

还有一个细节：很多人在示例里看到QProgressDialog搭配exec()，以为进度对话框就该用exec()弹出来。实际上，对于后台任务 + 实时进度的场景，show()更稳。exec()会进入一个嵌套事件循环，如果用户在这期间又触发其他窗口操作，容易出现难以追踪的重入问题。官方示例的演示重点不在exec()，而在信号连接。

2.3 进度到底是从哪儿来的

这里需要区分两条路。

如果使用的是QtConcurrent::map、mapped或filter，当你把一个容器丢进去处理，模块会按照容器大小自动给出进度范围，每完成一个元素自动推进进度值。UI 端接住progressRangeChanged和progressValueChanged就够了，伪代码层是这样：

connect(watcher, &QFutureWatcher<void>::progressRangeChanged, dialog, &QProgressDialog::setRange); connect(watcher, &QFutureWatcher<void>::progressValueChanged, dialog, &QProgressDialog::setValue);

如果使用的是QtConcurrent::run，情况就不同。它只负责“跑一个函数”，不会帮你推算进度。你需要自己在任务里调用进度相关接口，比如设置范围、推进当前值。那些接口是线程安全的，能在工作线程里被不断调用，前提是你有办法把句柄传进任务内部。很多新人在这一步头大，官方也正是想借示例逼你用惯 watcher 那套 UI 逻辑，进度产生方式反而可以替换。

2.4 示例代码里最常见的连接模板

无论任务细节如何，UI 侧连接模板几乎固定。示例代码通常长这样：

QProgressDialog *progress = new QProgressDialog( tr("处理中..."), tr("取消"), 0, 0, this); progress->setWindowModality(Qt::WindowModal); progress->setMinimumDuration(0); QFutureWatcher<void> *watcher = new QFutureWatcher<void>(this); connect(watcher, &QFutureWatcher<void>::progressRangeChanged, progress, &QProgressDialog::setRange); connect(watcher, &QFutureWatcher<void>::progressValueChanged, progress, &QProgressDialog::setValue); connect(watcher, &QFutureWatcher<void>::finished, progress, &QProgressDialog::reset); connect(watcher, &QFutureWatcher<void>::finished, watcher, &QFutureWatcher<void>::deleteLater); watcher->setFuture(QtConcurrent::run(...)); // 或 map(...)

注意两个细节：finished连到reset或close时，如果还关心结果，要在重置对话框之前把结果取走；watcher->deleteLater()不能漏，否则每个任务都会泄漏内存。

3. 实操：把一个自带的示例改成自己的独立工程

3.1 打开示例后的第一件事：跑一遍再改

在 Qt Creator 里打开 Qt 5.14.2 的 Examples 列表，搜索 Progress Dialog，你会看到 Concurrent 分类下有一个同名示例。先直接运行，观察三个现象：后台任务开始后进度条匀速推进；拖拽窗口时界面依然能响应；点击取消后任务会在下一个检查点退出。这三个现象分别对应“不阻塞 UI”“事件循环正常”“协作式取消”。

跑通之后，下一步不是马上复制代码，而是把工程文件里跟编译相关的设置抄到自己工程。具体就是QT += concurrent widgets。少了concurrent会直接编译失败，少了widgets则会出现找不到 QProgressDialog 的报错。这是最基础但最常见的“我照着例子写却编不过”的原因。

3.2 核心代码落地：一个可运行的批量处理骨架

我把例子“拉平”到最小可移植版本。假设我这里有一个数据文件列表，要对每个文件做一次耗时计算，结束时统计成功数量：

// mainwindow.h #ifndef MAINWINDOW_H #define MAINWINDOW_H #include <QWidget> #include <QStringList> #include <QFutureWatcher> class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); private slots: void startWork(); void workFinished(); private: QFutureWatcher<int> m_watcher; QStringList m_files; }; #endif

// mainwindow.cpp #include "mainwindow.h" #include <QPushButton> #include <QVBoxLayout> #include <QProgressDialog> #include <QThread> #include <QtConcurrent> namespace { int handleFile(const QString &path) { // 模拟耗时处理 QThread::msleep(20); return path.size() % 3 == 0 ? 1 : 0; } } MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { auto *button = new QPushButton(tr("开始处理"), this); auto *layout = new QVBoxLayout(this); layout->addWidget(button); for (int i = 0; i < 300; ++i) m_files << QString("/tmp/data_%1.txt").arg(i); connect(button, &QPushButton::clicked, this, &MainWindow::startWork); } void MainWindow::startWork() { if (m_watcher.isRunning()) return; auto *dialog = new QProgressDialog(tr("处理文件中..."), tr("取消"), 0, m_files.size(), this); dialog->setWindowModality(Qt::WindowModal); dialog->setMinimumDuration(0); connect(&m_watcher, &QFutureWatcher<int>::progressRangeChanged, dialog, &QProgressDialog::setRange); connect(&m_watcher, &QFutureWatcher<int>::progressValueChanged, dialog, &QProgressDialog::setValue); connect(&m_watcher, &QFutureWatcher<int>::finished, dialog, &QProgressDialog::close); connect(&m_watcher, &QFutureWatcher<int>::finished, this, &MainWindow::workFinished); m_watcher.setFuture(QtConcurrent::mapped(m_files, handleFile)); } void MainWindow::workFinished() { int ok = 0; const auto results = m_watcher.results(); for (int value : results) if (value) ++ok; m_watcher.clearResults(); // 这里刷新主窗口的统计标签等 }

这段代码里我把结果类型设成QFutureWatcher<int>，对应mapped返回的每个元素处理结果。这样做的目的在于演示：官方示例把重点放在进度 UI 上，但真正的工程里结果回收同样重要。如果只是跑进度条，QFutureWatcher<void>配合QtConcurrent::run会更简洁；一旦需要批量计算并收集结果，mapped这套方案更自然。

3.3 几个工程化改动：从示例过渡到真实项目

把示例往自己工程里搬的时候，我会做这几个改动：

• 把QProgressDialog的创建放到startWork内，而不是一直保留一个成员指针。因为每次任务都可能有不同的数据量，范围不同，模态状态也不同。
• 给startWork加isRunning判断，避免用户连续点击启动两个并发批次。
• finished → close的连接只负责关对话框，真正处理结果放在workFinished里。不要在workFinished里再访问局部对话框指针。
• 结果比较大时用mapped会先收到一份完整结果集，在处理完结果后调用clearResults()释放内存。长期运行的项目尤其需要养成这个习惯，否则任务数量一大，内存会悄悄往上涨。

还要注意QtConcurrent::mapped是“映射”，它适合那种每个输入元素各有一个独立输出结果的场景。如果你的任务是对整个容器做一次整体计算，那应该用QtConcurrent::run；如果你的任务只是修改容器里的元素而不需要返回值，用QtConcurrent::map。这几种 API 名字很像，选错之后虽然也能跑，但结果是处理逻辑和代码意图对不上。

4. 常见问题与排查思路实录

4.1 进度条永远停在 0%

90% 的情况是QFutureWatcher生命周期早于任务结束。检查 watcher 是不是局部变量，是否在函数结束就析构。剩下 10% 是忘了setFuture。在 Qt 中，watcher 只有在setFuture之后才开始转发信号，如果先连接信号后启动任务，顺序没问题；但如果任务已经结束你才调用setFuture，某些版本只会发出finished，中途的进度信号不会补发。

另一个隐蔽原因：后台任务真的没进度上报。如果你用QFutureWatcher::run但函数体从头到尾没有更新过进度，那当然不会有 progressValueChanged。若想快速获得进度，优先用 map/mapped 让框架自动上报；若必须用 run，就得自己维护范围与当前值，并在合适的位置调用进度接口。

4.2 点击“取消”后，任务还在后台跑

这不是 bug，取消是协作式的。QProgressDialog 的取消按钮只负责通知界面，真正中断任务有两个前提：外部调用QFuture::cancel()，以及后台任务能感知取消请求，比如在循环里检查QFuture::isCanceled()并在相应位置退出循环。

官方示例里那个可以取消的对话框，任务函数里是带了取消检查点的。你的移植代码如果只是设置了setFuture，但函数体内没有检查点，那点了取消，界面关闭了，计算还会继续占用 CPU。对轻量任务也许无所谓，对重型任务这就是隐患。我见过一个处理图片缩略图的任务，用户取消后线程池还在把整批图片全部处理完才退出，界面已经关了，机器风扇还在狂转。

4.3 主线程仍然卡顿

先确认任务真的没有在 UI 线程执行。常见错误是在 lambda 里捕获了this，然后在 lambda 里调用了某个成员函数，但这个成员函数本身并不保证跑在线程池，如果它还调用阻塞等待，那还是会卡住界面。

如果任务确实在线程池里，界面还卡，通常就是进度信号频率太高。比如一个任务有十万个小步骤，每完成一步就发一次信号，UI 线程就要被唤醒十万次，光刷新进度条就够喝一壶。解决办法是节流：不是每个中间值都刷新，而是“至少隔 N 毫秒刷新一次”，或者只在值跨过某个百分比阈值时才调用setValue。对进度条来说，显示“当前进度 53%”和“当前进度 53.0001%”没有实际差别，中间值刷新的时间成本却是真金白银。

4.4 跨平台细节：对话框消失又复活

在 Windows 上，进度对话框通常没问题；但在某些 Linux 窗口管理器下，QProgressDialog的最小时长与close()事件配合不当，可能出现“对话框关了但任务还在，任务结束又因为某个 pending 信号把它拉回来”的情况。排查办法是确保finished → close的连接只触发一次，并且不要在有 pending 信号时创建一个同名的局部对话框。

macOS 上则要注意WindowModal行为。如果用exec()启动进度对话框，会进入嵌套事件循环，此时再次点击主窗口按钮等交互会带来难以追踪的行为；更稳的方案是用show()而不是exec()，它在 Qt 5.14 下表现更可预期。

4.5 速查表：常用“病”与“药”

4.6 我的三条排错习惯

第一条，优先用qDebug打印progressValueChanged和finished，只保留关键日志。很多连接问题靠日志一眼就穿。第二条，开着任务时，去调试器的线程面板看线程栈。如果所有核心线程都停在 UI 事件循环里，说明任务根本没启动，问题多在启动逻辑而不是信号连接。第三条，重构代码时，永远把watcher当成一个“责任对象”：它负责把异步状态变成事件，谁持有它，谁就得为它的生命周期负责。这一条能避免一多半的并发内存问题。

我对这个示例最深的体会是：套用它的壳不难，难的是理解为什么官方把一些 API 摆在那。QFutureWatcher 不是多余的一层，它让后台线程永远不需要关心 UI；QProgressDialog 也不是随便一个进度条，它帮你处理了最小显示时间和模态交互。如果你只是想要进度条，抄两行信号连接就能用。如果你想真正理解 Qt 的异步设计，建议把这个例子拆开，逐行问自己“这行代码去掉会怎样”。我在带项目做交叉验证时，发现大部分并发问题都出在事件循环和生命周期这两个词上，而 QtConcurrent Progress Dialog 恰好都把这两点演示得很清楚。最后给一个建议：后续如果你想在这个基础上扩展，可以先从“失败重试”做起。任务失败时记录错误信息，在 finished 里弹一个非模态提示，让用户可以重新提交——这一套做熟之后，你对 QFuture 状态变化的理解会比只看文档强很多。