From 6d1895d6964266a8e5dfcff45a5c9f28737d3c0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E5=AE=97=E5=B9=B3?= Date: Sun, 5 Jul 2026 12:49:20 +0800 Subject: [PATCH] =?UTF-8?q?=E6=95=99=E5=AD=A6=E7=A4=BA=E4=BE=8B=E8=A1=A5?= =?UTF-8?q?=205=20=E4=B8=AA=EF=BC=9A3=20=E4=B8=AA=E5=9D=91=E7=82=B9?= =?UTF-8?q?=E5=A4=8D=E7=8E=B0=20+=20QTableWidget=20+=20Day5=20=E5=AD=A6?= =?UTF-8?q?=E5=91=98=E7=AE=A1=E7=90=86=E5=99=A8=E5=8F=82=E8=80=83=E5=AE=9E?= =?UTF-8?q?=E7=8E=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - pitfall_stack_widget / pitfall_lambda_capture / pitfall_double_connect： 默认跑正确写法（离屏验证退出码 0），--crash / --dangle 开关课堂现场触发 真实崩溃/悬空访问 - table_widget：QTableWidget 单元格事件最小示例（新安排 Day4「表格事件」） - student_manager：Day5 综合案例参考实现，离屏自测覆盖 JSON round-trip 与 QThread 后台导入闭环 - 均接入 examples/CMakeLists.txt 的 add_teaching_example，手工维护区不影响生成器 --- docs/teaching/examples/CMakeLists.txt | 16 +- .../examples/pitfall_double_connect/README.md | 37 +++ .../qt_pitfall_double_connect.cpp | 69 +++++ .../examples/pitfall_lambda_capture/README.md | 40 +++ .../qt_pitfall_lambda_capture.cpp | 70 +++++ .../examples/pitfall_stack_widget/README.md | 45 +++ .../qt_pitfall_stack_widget.cpp | 62 ++++ .../examples/student_manager/README.md | 52 ++++ .../student_manager/qt_student_manager.cpp | 284 ++++++++++++++++++ docs/teaching/examples/table_widget/README.md | 44 +++ .../table_widget/qt_table_widget_basics.cpp | 80 +++++ 11 files changed, 798 insertions(+), 1 deletion(-) create mode 100644 docs/teaching/examples/pitfall_double_connect/README.md create mode 100644 docs/teaching/examples/pitfall_double_connect/qt_pitfall_double_connect.cpp create mode 100644 docs/teaching/examples/pitfall_lambda_capture/README.md create mode 100644 docs/teaching/examples/pitfall_lambda_capture/qt_pitfall_lambda_capture.cpp create mode 100644 docs/teaching/examples/pitfall_stack_widget/README.md create mode 100644 docs/teaching/examples/pitfall_stack_widget/qt_pitfall_stack_widget.cpp create mode 100644 docs/teaching/examples/student_manager/README.md create mode 100644 docs/teaching/examples/student_manager/qt_student_manager.cpp create mode 100644 docs/teaching/examples/table_widget/README.md create mode 100644 docs/teaching/examples/table_widget/qt_table_widget_basics.cpp diff --git a/docs/teaching/examples/CMakeLists.txt b/docs/teaching/examples/CMakeLists.txt index 0140e0f..7482b23 100644 --- a/docs/teaching/examples/CMakeLists.txt +++ b/docs/teaching/examples/CMakeLists.txt @@ -19,10 +19,24 @@ add_teaching_example(qt_thread_worker qthread_worker) add_teaching_example(qt_property_animation property_animation) add_teaching_example(qt_state_machine state_machine) +# 坑点最小复现示例（OUTLINE_4DAY.md §9.2）：默认跑「正确写法」离屏可验证退出码 0， +# 错误写法一律用命令行开关现场触发（--crash / --dangle），不影响自动化验证。 +add_teaching_example(qt_pitfall_stack_widget pitfall_stack_widget) +add_teaching_example(qt_pitfall_lambda_capture pitfall_lambda_capture) +add_teaching_example(qt_pitfall_double_connect pitfall_double_connect) +add_teaching_example(qt_table_widget_basics table_widget) +# Day5 综合案例参考实现（OUTLINE_4DAY.md §3 / §9.3） +add_teaching_example(qt_student_manager student_manager) + add_custom_target(all_teaching_examples DEPENDS qt_qss_styling qt_model_view_basics qt_json_parse_write qt_thread_worker qt_property_animation - qt_state_machine) + qt_state_machine + qt_pitfall_stack_widget + qt_pitfall_lambda_capture + qt_pitfall_double_connect + qt_table_widget_basics + qt_student_manager) diff --git a/docs/teaching/examples/pitfall_double_connect/README.md b/docs/teaching/examples/pitfall_double_connect/README.md new file mode 100644 index 0000000..89dc58f --- /dev/null +++ b/docs/teaching/examples/pitfall_double_connect/README.md @@ -0,0 +1,37 @@ +# 坑点复现：重复 connect 导致槽触发多次 —— 教学补充示例 + +> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) Day2 下午 ★坑卡 +> 「重复 connect 导致槽触发多次」。手工维护，非生成产物。 + +## 概念 + +`connect` 每调用一次就**新增一条**连接——Qt 不会去重。同一对信号槽连了两次， +信号一发槽就被调两次。典型事故现场：`connect` 写在会被多次执行的路径上 +（每次打开对话框/每次刷新界面都跑一遍的「初始化」函数）。 + +现象非常有迷惑性：「点一次按钮弹两次框」——学员的第一反应是查按钮、查事件， +而根源在连接次数。 + +## 两种修复 + +1. **把 connect 收拢到只执行一次的地方**（构造函数）——首选，从结构上杜绝； +2. `Qt::UniqueConnection`——同一对（发送者,信号,接收者,槽）只允许一条连接。 + **注意它只对成员函数指针有效**：lambda 没有可比较的身份，UniqueConnection + 对 lambda 连接不起作用（这是它常被误用的点）。 + +## 验证方式 + +```bash +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_pitfall_double_connect # 确定性输出：2 次 → 1 次，退出码 0 +``` + +## 练习方向（供任务卡引用） + +- 把 `Popup::showOnce` 换成 lambda 再加 `Qt::UniqueConnection`，验证「lambda + 防不了重」； +- 在 `showOnce` 里打印 `sender()`，观察两次调用来自同一发送者的两条连接。 + +## 参考 + +- 本仓库对照：[`p03/ch04/custom_signal_slot.cpp`](../../../../p03/ch04/custom_signal_slot.cpp) +- Qt 官方文档：`QObject::connect`（`Qt::ConnectionType` 一节，选读·需联网） diff --git a/docs/teaching/examples/pitfall_double_connect/qt_pitfall_double_connect.cpp b/docs/teaching/examples/pitfall_double_connect/qt_pitfall_double_connect.cpp new file mode 100644 index 0000000..ac40aff --- /dev/null +++ b/docs/teaching/examples/pitfall_double_connect/qt_pitfall_double_connect.cpp @@ -0,0 +1,69 @@ +// ============================================================================ +// qt_pitfall_double_connect —— 坑点最小复现：重复 connect 导致槽触发多次 +// 对应教案：OUTLINE_4DAY.md Day2 下午 ★坑卡「重复 connect 导致槽触发多次」 +// 配套文档：docs/teaching/examples/pitfall_double_connect/README.md +// +// 现象还原：「点一次按钮弹两次框」——根源不在按钮，在 connect 被执行了两次。 +// 同时演示 Qt::UniqueConnection 防重（只对成员函数指针有效，lambda 用不了）。 +// 确定性输出，无 UB，离屏/终端直接跑，退出码 0。 +// ============================================================================ + +#include +#include +#include + +class Button : public QObject { + Q_OBJECT +public: + using QObject::QObject; +signals: + void clicked(); +}; + +class Popup : public QObject { + Q_OBJECT +public: + using QObject::QObject; + int shownCount = 0; +public slots: + void showOnce() { + ++shownCount; + qInfo() << " 弹框！（第" << shownCount << "次）"; + } +}; + +int main(int argc, char* argv[]) { + QCoreApplication app(argc, argv); + Button btn; + Popup popup; + + // 典型事故现场：connect 写在会被反复执行的函数里（比如每次打开某个界面 + // 都调一次 setup()），每调一次就多一条连接——信号一发，槽被调 N 次。 + auto setup = [&]() { QObject::connect(&btn, &Button::clicked, &popup, &Popup::showOnce); }; + setup(); + setup(); // 第二次“初始化”——现实里往往藏在另一条调用路径上 + + qInfo() << "重复 connect 两次后，点一次按钮："; + emit btn.clicked(); + qInfo() << "槽被调用了" << popup.shownCount << "次（预期演示值：2）"; + + // 修复一：连接前先断开旧连接 + QObject::disconnect(&btn, &Button::clicked, &popup, &Popup::showOnce); + QObject::disconnect(&btn, &Button::clicked, &popup, &Popup::showOnce); + + // 修复二：Qt::UniqueConnection——同一对(发送者,信号,接收者,槽)只允许一条连接。 + // 注意它只认成员函数指针；lambda 没有身份，UniqueConnection 对 lambda 无效。 + popup.shownCount = 0; + QObject::connect(&btn, &Button::clicked, &popup, &Popup::showOnce, Qt::UniqueConnection); + QObject::connect(&btn, &Button::clicked, &popup, &Popup::showOnce, Qt::UniqueConnection); + + qInfo() << "改用 Qt::UniqueConnection 连两次后，点一次按钮："; + emit btn.clicked(); + qInfo() << "槽被调用了" << popup.shownCount << "次（预期演示值：1）"; + + qInfo() << "结论：connect 不要写在会被多次执行的路径上；防御手段是" + "UniqueConnection（仅限成员函数槽）或把 connect 收拢到构造函数里只做一次。"; + return 0; +} + +#include "qt_pitfall_double_connect.moc" diff --git a/docs/teaching/examples/pitfall_lambda_capture/README.md b/docs/teaching/examples/pitfall_lambda_capture/README.md new file mode 100644 index 0000000..1d4bae4 --- /dev/null +++ b/docs/teaching/examples/pitfall_lambda_capture/README.md @@ -0,0 +1,40 @@ +# 坑点复现：lambda 槽的生命周期与 connect 第五参数 —— 教学补充示例 + +> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) Day2 下午 ★坑卡 +> 「lambda 槽的生命周期与第五参数」。手工维护，非生成产物。 + +## 概念 + +`connect` 的第五参数（context object）决定这条连接**跟谁的生命周期挂钩**： + +- `connect(sender, signal, lambda)`——连接只跟 sender 挂钩，**接收方对象销毁后 + lambda 仍会被调用**，捕获的指针就是悬空指针； +- `connect(sender, signal, receiver, lambda)`——receiver 析构时 Qt 自动断开 + 连接，lambda 不可能再访问已销毁的对象。 + +规则：**lambda 里捕获了某个 QObject，就把它作为第五参数传进去**。 + +## 运行结果解读 + +默认运行打印两次 emit 的对比：delete receiver 之后，只有「无 context」的连接 +还在触发。`--dangle` 让这条 lambda 真的去访问已销毁对象——你可能看到程序崩溃， +也可能看到它**打印出看似正常的旧值**（刚释放的内存还没被复用）。后者更危险： +UB 在开发机上「看起来正常」，到了演示/交付现场才炸。 + +## 验证与演示方式 + +```bash +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_pitfall_lambda_capture # 确定性对比输出，退出码 0 +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_pitfall_lambda_capture --dangle # 课堂演示：真实悬空访问（UB） +``` + +## 练习方向（供任务卡引用） + +- 把连接 A 的 lambda 改成按引用捕获一个局部 `QString`，在函数返回后触发信号， + 分析这是哪一种悬空（对象悬空 vs 捕获变量悬空）； +- 用 `QObject::destroyed` 信号打印 receiver 的销毁时机，确认连接 B 断开发生在何时。 + +## 参考 + +- 本仓库对照：[`p03/ch04/lambda_signal_slot.cpp`](../../../../p03/ch04/lambda_signal_slot.cpp)（lambda 槽基本写法） +- Qt 官方文档：*Differences between String-Based and Functor-Based Connections*（选读·需联网） diff --git a/docs/teaching/examples/pitfall_lambda_capture/qt_pitfall_lambda_capture.cpp b/docs/teaching/examples/pitfall_lambda_capture/qt_pitfall_lambda_capture.cpp new file mode 100644 index 0000000..87d96e3 --- /dev/null +++ b/docs/teaching/examples/pitfall_lambda_capture/qt_pitfall_lambda_capture.cpp @@ -0,0 +1,70 @@ +// ============================================================================ +// qt_pitfall_lambda_capture —— 坑点最小复现：lambda 槽的生命周期与第五参数 +// 对应教案：OUTLINE_4DAY.md Day2 下午 ★坑卡「lambda 槽的生命周期与第五参数」 +// 配套文档：docs/teaching/examples/pitfall_lambda_capture/README.md +// +// 默认运行：对比两条连接——不带 context 的 lambda 在接收者销毁后**仍会被调用**， +// 带 context（connect 第五参数）的连接随接收者销毁自动断开。退出码 0。 +// 加 --dangle：不带 context 的 lambda 里真的去访问已销毁的接收者（悬空指针， +// UB，课堂演示专用——可能打印垃圾值、也可能直接崩，两种结果都是教学素材）。 +// ============================================================================ + +#include +#include +#include +#include + +class Sender : public QObject { + Q_OBJECT +public: + using QObject::QObject; +signals: + void ping(); +}; + +class Receiver : public QObject { + Q_OBJECT +public: + explicit Receiver(QObject* parent = nullptr) + : QObject(parent), m_name(QStringLiteral("接收者甲")) {} + QString name() const { return m_name; } +private: + QString m_name; +}; + +int main(int argc, char* argv[]) { + QCoreApplication app(argc, argv); + const bool dangle = (argc > 1 && std::strcmp(argv[1], "--dangle") == 0); + + Sender sender; + auto* receiver = new Receiver; + + // 连接 A（错误示范）：lambda 捕获了 receiver 指针，但没有传第五参数。 + // 这条连接的生存期只跟 sender 挂钩——receiver 死了它也不会断开。 + QObject::connect(&sender, &Sender::ping, [receiver, dangle]() { + qInfo() << "[无 context] lambda 被调用"; + if (dangle) { + // 悬空访问：第二次触发时 receiver 已被 delete —— UB + qInfo() << " 访问 receiver->name() =" << receiver->name(); + } + }); + + // 连接 B（正确写法）：第五参数传 receiver 作为 context object， + // receiver 析构时 Qt 自动断开这条连接，lambda 不可能再被调用。 + QObject::connect(&sender, &Sender::ping, receiver, [receiver]() { + qInfo() << "[带 context] lambda 被调用，receiver->name() =" << receiver->name(); + }); + + qInfo() << "---- 第一次 emit（receiver 活着，两条连接都触发）----"; + emit sender.ping(); + + delete receiver; + qInfo() << "---- delete receiver 之后，第二次 emit ----"; + emit sender.ping(); // 只有连接 A 还会触发——这就是悬空风险所在 + + qInfo() << "结论：lambda 槽捕获了对象指针，就必须把该对象作为 connect 的" + "第五参数（context），让连接的生命周期跟着对象走。"; + return 0; +} + +#include "qt_pitfall_lambda_capture.moc" diff --git a/docs/teaching/examples/pitfall_stack_widget/README.md b/docs/teaching/examples/pitfall_stack_widget/README.md new file mode 100644 index 0000000..f6e5267 --- /dev/null +++ b/docs/teaching/examples/pitfall_stack_widget/README.md @@ -0,0 +1,45 @@ +# 坑点复现：栈对象与父子所有权打架（双重释放）—— 教学补充示例 + +> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) Day2 上午 ★坑卡 +> 「栈对象与父子所有权打架」。手工维护，非 `tools/gen_part3.py` 生成产物。 + +## 概念 + +Qt 的父子树是一套**所有权**机制：parent 析构时会 `delete` 它的所有子对象。 +这隐含一个硬性前提——**交给父子树管的对象必须建在堆上**。一个对象只能有一个 +所有者：给了 parent，就不能再由栈作用域、智能指针或手动 `delete` 管理。 + +## 错在哪（`--crash` 演示的代码） + +```cpp +QPushButton btn("我建在栈上"); // 先声明 → 后析构 +QWidget window; // 后声明 → 先析构 +btn.setParent(&window); +// 离开作用域：window 先析构 → 父子树 delete &btn（栈地址！）→ +// glibc 报 "free(): invalid pointer" 后 abort +``` + +注意声明顺序反过来（parent 先声明）时这段代码**恰好不崩**——`btn` 先析构时会把 +自己从 parent 的子对象列表里摘除。「有时不崩」正是这类所有权错误难查的原因： +不要依赖析构顺序的运气，规则只有一条——**给了 parent 就必须在堆上**。 + +## 验证与演示方式 + +```bash +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_pitfall_stack_widget # 正确写法，退出码 0 +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_pitfall_stack_widget --crash # 课堂演示：现场崩给学员看 +``` + +`--crash` 必然非正常退出（core dump），**不要**放进自动化验证。 + +## 练习方向（供任务卡引用） + +- 把错误版本的两行声明顺序对调，观察「恰好不崩」，再解释为什么它仍然是错的； +- 同一误区的第三次出现：非模态对话框建在栈上一闪而过，见 + [`p03/ch06/modeless_dialog_stack.cpp`](../../../../p03/ch06/modeless_dialog_stack.cpp) + 与堆版/`WA_DeleteOnClose` 版的三方对照。 + +## 参考 + +- 本仓库对照：[`p03/ch03/button_creation.cpp`](../../../../p03/ch03/button_creation.cpp)（正确的 parent 用法） +- 前置概念：Day1 ★坑卡「所有权心智模型：谁负责 delete」 diff --git a/docs/teaching/examples/pitfall_stack_widget/qt_pitfall_stack_widget.cpp b/docs/teaching/examples/pitfall_stack_widget/qt_pitfall_stack_widget.cpp new file mode 100644 index 0000000..7bae647 --- /dev/null +++ b/docs/teaching/examples/pitfall_stack_widget/qt_pitfall_stack_widget.cpp @@ -0,0 +1,62 @@ +// ============================================================================ +// qt_pitfall_stack_widget —— 坑点最小复现：栈对象与父子所有权打架（双重释放） +// 对应教案：OUTLINE_4DAY.md Day2 上午 ★坑卡「栈对象与父子所有权打架」 +// 配套文档：docs/teaching/examples/pitfall_stack_widget/README.md +// +// 默认运行：正确写法（子控件建在堆上、交给 parent 管），离屏验证退出码 0。 +// 加 --crash：错误写法（带 parent 的控件建在栈上），亲眼看双重释放崩溃—— +// 课堂演示专用，退出码必然非 0，不要用于自动化验证。 +// ============================================================================ + +#include +#include +#include +#include +#include +#include +#include +#include + +// 错误写法：child 声明在 parent 之前 → 作用域结束时 parent（后声明）先析构， +// 父子树机制会 delete 它的所有子对象——包括这个根本不在堆上的 btn（UB，典型 +// 表现是 glibc 报 "free(): invalid pointer" 后 abort）；随后 btn 自己的栈析构 +// 又会跑一遍。一个对象只能有一个所有者：交给了 Qt 父子树，就不能再由栈管理。 +static void wrongVersion() { + QPushButton btn(QStringLiteral("我建在栈上")); // 先声明 → 后析构 + QWidget window; // 后声明 → 先析构 + btn.setParent(&window); + // 离开作用域：window 析构 → delete &btn（栈地址！）→ 崩溃 +} + +// 正确写法：子控件一律 new 在堆上、把 parent 传进去（或加进布局，布局会代为 +// 设置 parent），此后它的生命周期完全由父子树负责，不写任何 delete。 +static QWidget* correctVersion() { + auto* window = new QWidget; + auto* layout = new QVBoxLayout(window); + layout->addWidget(new QLabel(QStringLiteral("子控件都在堆上，由父子树负责释放"), window)); + layout->addWidget(new QPushButton(QStringLiteral("确定"), window)); + return window; // window 析构时自动 delete 上面所有子对象 +} + +int main(int argc, char* argv[]) { + QApplication app(argc, argv); + + if (argc > 1 && std::strcmp(argv[1], "--crash") == 0) { + qInfo() << "演示错误写法：栈上控件交给父子树管……"; + wrongVersion(); // 走不到下一行就崩 + qInfo() << "（如果你看到这行，说明该平台的 UB 恰好没炸——它仍然是错的）"; + return 0; + } + + QWidget* window = correctVersion(); + window->setWindowTitle(QStringLiteral("正确写法：堆 + parent")); + window->resize(320, 120); + window->show(); + + if (qgetenv("QT_QPA_PLATFORM") == "offscreen") { + QTimer::singleShot(200, &app, &QApplication::quit); + } + int rc = app.exec(); + delete window; // 顶层窗口没有 parent，是唯一需要我们自己负责的对象 + return rc; +} diff --git a/docs/teaching/examples/student_manager/README.md b/docs/teaching/examples/student_manager/README.md new file mode 100644 index 0000000..8469cdb --- /dev/null +++ b/docs/teaching/examples/student_manager/README.md @@ -0,0 +1,52 @@ +# 学员信息管理器 —— Day5 综合案例参考实现 + +> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) §3「Day5 综合项目案例讲解」。 +> 教师侧参考答案：把 Day1–4 作业线（计算器→主窗口化→JSON 落盘）收束成一个完整 +> 小软件。手工维护，非生成产物。 + +## 覆盖的知识点（讲解时逐条回指） + +| 环节 | 知识点 | 首次出现 | +|---|---|---| +| 主窗口骨架 | QMainWindow 菜单/工具栏/状态栏/`setCentralWidget` | Day3 上午 | +| 列表展示 | QTableWidget + item 所有权 | Day4 上午 | +| 添加记录 | 模态 QDialog `exec()` + QFormLayout | Day3 上午/下午 | +| 通信 | 信号槽（成员函数槽 + 带 context 的 lambda 槽） | Day2 | +| 数据层 | Student ↔ QJson 互逆序列化，round-trip 校验 | Day4 下午 | +| 路径 | `applicationDirPath()` 拼数据文件路径（不用相对路径） | Day4 ★坑卡 | +| 健壮性 | `open()` 返回值、`QJsonParseError` 都检查 | Day4 坑卡 | +| **提升** | QThread worker-object 模式后台导入，界面不冻结 | Day5 新授 | + +QThread 三件套在 `startImport()` 里全部有注释标注：worker 不给 parent、 +`moveToThread` 在 `start()` 之前、跨线程信号→主线程槽自动 Queued（`addRow` +安全地在 GUI 线程执行）。 + +## 验证方式（自测模式） + +```bash +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_student_manager +# 自测流程：添加 2 条 → 保存 JSON → 清空 → 读回校验 → +# 后台线程导入 3 条 → 总数校验 5 条；全过退出码 0，任一步失败退出码 1 +tools/run_qt.sh qt_student_manager # 有 X 环境：完整交互（菜单/工具栏/对话框/后台导入） +``` + +有显示环境时数据保存在可执行文件旁的 `students.json`（状态栏显示完整路径）。 + +## 课堂讲解建议（对应 OUTLINE_4DAY.md §3 时段表） + +1. 上午先讲界面骨架与数据层（自顶向下：先跑成品，再拆 MainWindow → 数据层）； +2. 下午「后台导入」是提升重点：先把 `msleep` 挪进主线程按钮槽里演示界面冻结， + 再回到 worker 版本对比——「卡与不卡」亲眼见一次胜过讲十分钟； +3. 每讲完一段，回指上表对应的 Day1–4 知识点，让学员意识到「项目 = 已学内容的组装」。 + +## 练习方向（供 Day6–10 项目热身） + +- 加「删除选中行」（`currentRow` + `removeRow`）； +- 保存前若有未保存修改，关窗时弹确认框（`closeEvent` + `QMessageBox::question`）； +- 把成绩列改为按数值排序（提示：`QTableWidgetItem::setData(Qt::EditRole, double)`）。 + +## 参考 + +- 前身作业：[`../json_io/`](../json_io/README.md)（Day4 数据落盘）、 + [`../table_widget/`](../table_widget/README.md)（Day4 表格）、 + [`../qthread_worker/`](../qthread_worker/README.md)（worker 模式最小版） diff --git a/docs/teaching/examples/student_manager/qt_student_manager.cpp b/docs/teaching/examples/student_manager/qt_student_manager.cpp new file mode 100644 index 0000000..e15f556 --- /dev/null +++ b/docs/teaching/examples/student_manager/qt_student_manager.cpp @@ -0,0 +1,284 @@ +// ============================================================================ +// qt_student_manager —— Day5 综合案例参考实现：学员信息管理器 +// 对应教案：OUTLINE_4DAY.md §3（Day5 综合项目案例讲解）——把 Day1–4 作业线 +// 收束成一个完整小软件：QMainWindow 骨架 + QTableWidget 列表 + 增改对话框 + +// JSON 落盘读回 + QThread 后台导入不卡界面。 +// 配套文档：docs/teaching/examples/student_manager/README.md +// +// 离屏验证（自测模式）：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_student_manager +// 自测流程：添加 2 条记录 → 保存 JSON → 清空 → 读回校验 → 后台导入 3 条 → +// 总数校验，全部通过退出码 0，任一步失败退出码 1。 +// ============================================================================ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +// ---------------------------------------------------------------- 数据层 ---- + +struct Student { + QString name; + double score = 0.0; + QString tag; +}; + +// 序列化/反序列化是一对互逆操作（Day4）：正确性标准 = 写出去再读回来数据一致。 +static QJsonObject toJson(const Student& s) { + return QJsonObject{{"name", s.name}, {"score", s.score}, {"tag", s.tag}}; +} + +static Student fromJson(const QJsonObject& obj) { + // 类型不匹配时 toString()/toDouble() 不报错只给默认值（Day4 坑卡）—— + // 教学示例里字段固定，生产代码应先 contains()+isDouble() 逐字段校验。 + return Student{obj["name"].toString(), obj["score"].toDouble(), obj["tag"].toString()}; +} + +// ---------------------------------------------------------- 添加记录对话框 ---- + +class AddStudentDialog : public QDialog { + Q_OBJECT +public: + explicit AddStudentDialog(QWidget* parent = nullptr) : QDialog(parent) { + setWindowTitle(QStringLiteral("添加学员")); + m_name = new QLineEdit(this); + m_score = new QLineEdit(this); + m_tag = new QLineEdit(this); + + auto* buttons = new QDialogButtonBox( + QDialogButtonBox::Ok | QDialogButtonBox::Cancel, this); + connect(buttons, &QDialogButtonBox::accepted, this, &QDialog::accept); + connect(buttons, &QDialogButtonBox::rejected, this, &QDialog::reject); + + auto* form = new QFormLayout(this); + form->addRow(QStringLiteral("姓名"), m_name); + form->addRow(QStringLiteral("成绩"), m_score); + form->addRow(QStringLiteral("标签"), m_tag); + form->addRow(buttons); + } + + Student student() const { + return Student{m_name->text(), m_score->text().toDouble(), m_tag->text()}; + } + +private: + QLineEdit* m_name; + QLineEdit* m_score; + QLineEdit* m_tag; +}; + +// ------------------------------------------------------ 后台导入 worker ---- + +// worker-object 模式（而非继承 QThread）：耗时活儿放进 worker，把 worker +// moveToThread 到工作线程；worker 与界面之间只通过信号槽通信——跨线程连接 +// 自动变 Queued，槽在接收者所属线程执行，天然不碰 GUI 线程以外的控件。 +class ImportWorker : public QObject { + Q_OBJECT +public slots: + void doImport(int rows) { + for (int i = 1; i <= rows; ++i) { + QThread::msleep(20); // 模拟耗时 IO；放主线程就是界面冻结（Day4 埋点） + emit rowReady(QStringLiteral("导入学员%1").arg(i), 60.0 + i, QStringLiteral("导入")); + } + emit finished(); + } +signals: + void rowReady(const QString& name, double score, const QString& tag); + void finished(); +}; + +// -------------------------------------------------------------- 主窗口 ---- + +class MainWindow : public QMainWindow { + Q_OBJECT +public: + explicit MainWindow(QWidget* parent = nullptr) : QMainWindow(parent) { + setWindowTitle(QStringLiteral("学员信息管理器")); + + // QMainWindow 不是大号 QWidget：中心部件必须显式安放（Day3 坑卡） + m_table = new QTableWidget(0, 3, this); + m_table->setHorizontalHeaderLabels( + {QStringLiteral("姓名"), QStringLiteral("成绩"), QStringLiteral("标签")}); + m_table->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch); + setCentralWidget(m_table); + + auto* actAdd = new QAction(QStringLiteral("添加记录"), this); + auto* actSave = new QAction(QStringLiteral("保存"), this); + auto* actLoad = new QAction(QStringLiteral("读取"), this); + m_actImport = new QAction(QStringLiteral("后台导入"), this); + auto* actAbout = new QAction(QStringLiteral("关于"), this); + + QMenu* fileMenu = menuBar()->addMenu(QStringLiteral("文件(&F)")); + fileMenu->addAction(actSave); + fileMenu->addAction(actLoad); + QMenu* recordMenu = menuBar()->addMenu(QStringLiteral("记录(&R)")); + recordMenu->addAction(actAdd); + recordMenu->addAction(m_actImport); + menuBar()->addMenu(QStringLiteral("帮助(&H)"))->addAction(actAbout); + + QToolBar* bar = addToolBar(QStringLiteral("main")); + bar->addAction(actAdd); + bar->addAction(actSave); + bar->addAction(actLoad); + bar->addAction(m_actImport); + + // QAction 显示出来 ≠ 生效：忘 connect 就是「菜单点了没反应」（Day3 坑卡） + connect(actAdd, &QAction::triggered, this, &MainWindow::onAdd); + connect(actSave, &QAction::triggered, this, [this] { saveTo(m_dataPath); }); + connect(actLoad, &QAction::triggered, this, [this] { loadFrom(m_dataPath); }); + connect(m_actImport, &QAction::triggered, this, &MainWindow::onImport); + connect(actAbout, &QAction::triggered, this, [this] { + QMessageBox::about(this, QStringLiteral("关于"), + QStringLiteral("Day5 综合案例参考实现：Day1–4 全部知识点的收束。")); + }); + + // 相对路径随工作目录漂移（Day4 坑卡）——一律基于 applicationDirPath 拼路径 + m_dataPath = QCoreApplication::applicationDirPath() + "/students.json"; + statusBar()->showMessage(QStringLiteral("数据文件：") + m_dataPath); + } + + int rowCount() const { return m_table->rowCount(); } + void clearAll() { m_table->setRowCount(0); } + + void addRow(const Student& s) { + const int row = m_table->rowCount(); + m_table->insertRow(row); + m_table->setItem(row, 0, new QTableWidgetItem(s.name)); + m_table->setItem(row, 1, new QTableWidgetItem(QString::number(s.score))); + m_table->setItem(row, 2, new QTableWidgetItem(s.tag)); + } + + bool saveTo(const QString& path) { + QJsonArray arr; + for (int row = 0; row < m_table->rowCount(); ++row) { + arr.append(toJson(Student{m_table->item(row, 0)->text(), + m_table->item(row, 1)->text().toDouble(), + m_table->item(row, 2)->text()})); + } + QFile file(path); + if (!file.open(QIODevice::WriteOnly)) { // open() 必须检查（Day4 坑卡） + statusBar()->showMessage(QStringLiteral("保存失败：打不开 ") + path); + return false; + } + file.write(QJsonDocument(arr).toJson(QJsonDocument::Indented)); + statusBar()->showMessage(QStringLiteral("已保存 %1 条记录").arg(arr.size())); + return true; + } + + bool loadFrom(const QString& path) { + QFile file(path); + if (!file.open(QIODevice::ReadOnly)) { + statusBar()->showMessage(QStringLiteral("读取失败：打不开 ") + path); + return false; + } + QJsonParseError err; // 不检查 ParseError = 坏文件静默变空表（Day4 坑卡） + const QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &err); + if (err.error != QJsonParseError::NoError || !doc.isArray()) { + statusBar()->showMessage(QStringLiteral("JSON 解析失败：") + err.errorString()); + return false; + } + clearAll(); + const QJsonArray arr = doc.array(); + for (const QJsonValue& v : arr) addRow(fromJson(v.toObject())); + statusBar()->showMessage(QStringLiteral("已读取 %1 条记录").arg(arr.size())); + return true; + } + + void startImport(int rows) { + m_actImport->setEnabled(false); // 防重复启动（也防重复 connect，Day2 坑卡） + auto* thread = new QThread(this); + auto* worker = new ImportWorker; // 不能给 parent：有 parent 的对象禁止 moveToThread + worker->moveToThread(thread); // 必须在 start() 之前（Day5 讲授点） + + connect(thread, &QThread::started, worker, [worker, rows] { worker->doImport(rows); }); + // 跨线程信号 → 主线程槽：自动 Queued，addRow 在 GUI 线程安全执行 + connect(worker, &ImportWorker::rowReady, this, + [this](const QString& name, double score, const QString& tag) { + addRow(Student{name, score, tag}); + }); + connect(worker, &ImportWorker::finished, this, [this] { + m_actImport->setEnabled(true); + statusBar()->showMessage(QStringLiteral("后台导入完成")); + emit importFinished(); + }); + connect(worker, &ImportWorker::finished, thread, &QThread::quit); + connect(thread, &QThread::finished, worker, &QObject::deleteLater); + connect(thread, &QThread::finished, thread, &QObject::deleteLater); + thread->start(); + } + +signals: + void importFinished(); + +private slots: + void onAdd() { + AddStudentDialog dlg(this); // 模态：exec() 阻塞等结果（Day3） + if (dlg.exec() == QDialog::Accepted) addRow(dlg.student()); + } + void onImport() { startImport(10); } + +private: + QTableWidget* m_table = nullptr; + QAction* m_actImport = nullptr; + QString m_dataPath; +}; + +// ------------------------------------------------------------ 自测入口 ---- + +// 离屏自测：走一遍「添加→保存→清空→读回→后台导入」完整闭环并校验。 +static void runSelfTest(MainWindow* win) { + const QString path = QCoreApplication::applicationDirPath() + "/students_selftest.json"; + win->addRow({QStringLiteral("张三"), 91.5, QStringLiteral("组长")}); + win->addRow({QStringLiteral("李四"), 88.0, QStringLiteral("美工")}); + if (!win->saveTo(path)) { QCoreApplication::exit(1); return; } + win->clearAll(); + if (!win->loadFrom(path) || win->rowCount() != 2) { + qCritical() << "自测失败：JSON 读回记录数 =" << win->rowCount() << "预期 2"; + QCoreApplication::exit(1); + return; + } + qInfo() << "自测 1/2 通过：JSON 写入→清空→读回，2 条记录完整"; + + QObject::connect(win, &MainWindow::importFinished, win, [win, path] { + QFile::remove(path); + if (win->rowCount() != 5) { + qCritical() << "自测失败：导入后总数 =" << win->rowCount() << "预期 5"; + QCoreApplication::exit(1); + return; + } + qInfo() << "自测 2/2 通过：后台线程导入 3 条，总计 5 条，界面未阻塞"; + QCoreApplication::exit(0); + }); + win->startImport(3); +} + +int main(int argc, char* argv[]) { + QApplication app(argc, argv); + MainWindow win; + win.resize(560, 360); + win.show(); + + if (qgetenv("QT_QPA_PLATFORM") == "offscreen") { + QTimer::singleShot(0, &win, [&win] { runSelfTest(&win); }); + } + return app.exec(); +} + +#include "qt_student_manager.moc" diff --git a/docs/teaching/examples/table_widget/README.md b/docs/teaching/examples/table_widget/README.md new file mode 100644 index 0000000..2e6e708 --- /dev/null +++ b/docs/teaching/examples/table_widget/README.md @@ -0,0 +1,44 @@ +# QTableWidget 表格与单元格事件 —— 教学补充示例 + +> 对应教案 [`OUTLINE_4DAY.md`](../../OUTLINE_4DAY.md) Day4 上午「表格」环节 +> （新版 10 天安排原文「绘图事件及表格事件」）。手工维护，非生成产物。 + +## 概念 + +Qt 展示表格数据有两条路线： + +- **item 类控件（本示例）**：`QTableWidget`——数据直接塞进控件 + （`QTableWidgetItem`），上手快，中小项目够用； +- **Model/View 架构（延伸钩子）**：数据（model）与展示（view）彻底分离， + 同一模型可喂多个视图，见 [`../model_view/`](../model_view/README.md)。 + +「表格事件」以**信号**形式暴露：`cellClicked` / `cellDoubleClicked` / +`itemChanged`（编辑单元格后触发）……常规交互不需要重写 `event` 函数。 + +## 代码走读 + +见 [`qt_table_widget_basics.cpp`](qt_table_widget_basics.cpp)： + +1. 构造 3×3 表格，`setHorizontalHeaderLabels` 设列头，列宽 `Stretch` 自适应； +2. 每个单元格一个 `QTableWidgetItem`，`new` 出来交给表格接管所有权 + （又是父子所有权模型——第几次出现了？）； +3. `cellClicked` 连成员函数槽、`itemChanged` 连 lambda（注意第五参数传了 + `this`，呼应 Day2 坑卡），点击/编辑结果显示在下方 `QLabel`。 + +## 验证方式 + +```bash +QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_table_widget_basics # 离屏跑通，200ms 自动退出 +tools/run_qt.sh qt_table_widget_basics # 有 X 环境：点击/编辑单元格看状态栏变化 +``` + +## 练习方向（供任务卡引用） + +- 加一个「添加行」按钮：`insertRow` + 三个新 item； +- 双击某行弹 `QMessageBox` 显示整行内容（`cellDoubleClicked`）； +- 进阶：改用 `../model_view/` 的做法重做本例，体会两条路线的差异。 + +## 参考 + +- 本仓库对照：[`../model_view/qt_model_view_basics.cpp`](../model_view/qt_model_view_basics.cpp) +- 综合运用：[`../student_manager/`](../student_manager/README.md)（Day5 案例的核心控件就是它） diff --git a/docs/teaching/examples/table_widget/qt_table_widget_basics.cpp b/docs/teaching/examples/table_widget/qt_table_widget_basics.cpp new file mode 100644 index 0000000..46c5664 --- /dev/null +++ b/docs/teaching/examples/table_widget/qt_table_widget_basics.cpp @@ -0,0 +1,80 @@ +// ============================================================================ +// qt_table_widget_basics —— 教学补充示例：QTableWidget 表格与单元格事件 +// 对应教案：OUTLINE_4DAY.md Day4 上午「表格」环节（新安排原文「表格事件」） +// 配套文档：docs/teaching/examples/table_widget/README.md +// 离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_table_widget_basics +// +// QTableWidget 是「item 类」控件：数据直接塞进控件里（QTableWidgetItem）， +// 上手快、够中小项目用；数据/展示彻底分离的完整 Model/View 架构见 +// ../model_view/qt_model_view_basics.cpp（延伸钩子）。 +// ============================================================================ + +#include +#include +#include +#include +#include +#include +#include + +class TableDemo : public QWidget { + Q_OBJECT +public: + explicit TableDemo(QWidget* parent = nullptr) : QWidget(parent) { + m_table = new QTableWidget(3, 3, this); // 行列数在构造时给定 + m_table->setHorizontalHeaderLabels( + {QStringLiteral("姓名"), QStringLiteral("成绩"), QStringLiteral("标签")}); + m_table->horizontalHeader()->setSectionResizeMode(QHeaderView::Stretch); + + const char* names[] = {"张三", "李四", "王五"}; + const char* scores[] = {"91.5", "88", "76"}; + const char* tags[] = {"组长", "美工", "测试"}; + for (int row = 0; row < 3; ++row) { + // 每个单元格一个 QTableWidgetItem，new 出来交给表格接管所有权 + m_table->setItem(row, 0, new QTableWidgetItem(QString::fromUtf8(names[row]))); + m_table->setItem(row, 1, new QTableWidgetItem(QString::fromUtf8(scores[row]))); + m_table->setItem(row, 2, new QTableWidgetItem(QString::fromUtf8(tags[row]))); + } + + m_status = new QLabel(QStringLiteral("点击任意单元格试试"), this); + + auto* layout = new QVBoxLayout(this); + layout->addWidget(m_table); + layout->addWidget(m_status); + + // 「表格事件」以信号形式暴露：cellClicked / cellDoubleClicked / + // itemChanged（编辑单元格后触发）…… 不需要重写 event 函数。 + connect(m_table, &QTableWidget::cellClicked, this, &TableDemo::onCellClicked); + connect(m_table, &QTableWidget::itemChanged, this, [this](QTableWidgetItem* item) { + m_status->setText(QStringLiteral("(%1,%2) 被改为 %3") + .arg(item->row()).arg(item->column()).arg(item->text())); + }); + } + +private slots: + void onCellClicked(int row, int column) { + QTableWidgetItem* item = m_table->item(row, column); + m_status->setText(QStringLiteral("点击了 (%1,%2)：%3") + .arg(row).arg(column) + .arg(item ? item->text() : QStringLiteral("<空>"))); + } + +private: + QTableWidget* m_table = nullptr; + QLabel* m_status = nullptr; +}; + +int main(int argc, char* argv[]) { + QApplication app(argc, argv); + TableDemo demo; + demo.setWindowTitle(QStringLiteral("QTableWidget 基础")); + demo.resize(420, 240); + demo.show(); + + if (qgetenv("QT_QPA_PLATFORM") == "offscreen") { + QTimer::singleShot(200, &app, &QApplication::quit); + } + return app.exec(); +} + +#include "qt_table_widget_basics.moc"