教案对齐官方方案书：重写为 5 天 C++/Qt 教学设计，补齐 6 个 Qt 技术缺口示例

- docs/teaching/OUTLINE.md、slides/day1-5.html、index.html：替换此前自定义的 4 天方案，严格对齐 docs/TRAINING_PLAN_2026.md「C++方向」Day1-5 课堂内容（Day6-10 为纯项目实作，不在教案范围） - docs/teaching/examples/：官方方案书要求但仓库 p03/(wiki 抓取内容) 未覆盖的 QSS/Model-View/JSON/QThread/QPropertyAnimation/QStateMachine 六个技术点，各补一个最小可运行示例 + README 教学文档，均已离屏验证跑通；手工维护，不属于 gen_part3.py 生成产物 - 根 CMakeLists.txt：接入 docs/teaching/examples 构建（BUILD_QT_PART 分支内），不改动生成器管理的 p01/p03 CMakeLists - 任务卡改为目标/验收标准/基础知识参考三段式模板，custom.css 配套新增样式 - docs/teaching/PRETEST.md：10 题 10 分钟 C++ 摸底测验，验证教案假定的受众基础是否成立，并与 OUTLINE.md §0 的分层预案挂钩
2026-07-02 11:31:44 +08:00
parent 6bb38563b5
commit 83620c0cf5
23 changed files with 1862 additions and 1041 deletions
@@ -0,0 +1,47 @@
+# QSS 界面美化 —— 教学补充示例
+
+> 对应方案书「C++方向 Day2」："基础 UI 控件、布局管理与 QSS 界面美化"。
+> 仓库 `p03/` 的 wiki 抓取内容里没有 QSS 相关代码，本示例是手工补写的教学补充，
+> **不属于** `tools/gen_part3.py` 的生成产物，重新生成 `p01`/`p03` 不会影响它。
+
+## 概念
+
+QSS（Qt Style Sheets）是 Qt 提供的类 CSS 样式语言，用来把"控件长什么样"和"控件
+做什么"分离开：
+
+- 类型选择器：`QPushButton { ... }` —— 命中所有该类型控件；
+- ID 选择器：`QPushButton#okButton { ... }` —— 通过 `setObjectName()` 精确命中
+  某一个控件；
+- 伪状态：`:hover`、`:pressed`、`:disabled` 等 —— 不用手写事件处理就能做交互反馈；
+- 既可以调用 `qApp->setStyleSheet(...)` 全局生效，也可以 `widget->setStyleSheet(...)`
+  只作用于这个控件和它的子控件。
+
+## 代码走读
+
+见 [`qt_qss_styling.cpp`](qt_qss_styling.cpp)：
+
+1. 三个控件（标题 `QLabel`、确定/取消两个 `QPushButton`）分别设置 `objectName`；
+2. 整个窗口调一次 `setStyleSheet()`，用 ID 选择器分别美化每个控件，
+   `okButton`/`cancelButton` 还各自定义了 `:hover`/`:pressed` 效果；
+3. 不改变任何业务逻辑（没有新增信号槽），只改变外观——这正是 QSS 的定位：
+   与逻辑正交。
+
+## 验证方式
+
+```bash
+QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_qss_styling   # 离屏跑通，200ms 自动退出
+tools/run_qt.sh qt_qss_styling                              # 有 X 环境可直接看窗口
+```
+
+## 练习方向（供任务卡引用）
+
+- 把 `okButton`/`cancelButton` 换成类型选择器 `QPushButton { ... }` 一次性美化，
+  对比 ID 选择器和类型选择器的适用场景差异；
+- 给 `title` 加一个 `:hover` 伪状态（`QLabel` 默认不接收鼠标事件，需要先
+  `setAttribute(Qt::WA_Hover)` 之类的前置条件——留给学员自己踩一次坑）。
+
+## 参考
+
+- 本仓库对照：[`p03/ch08/custom_widget.cpp`](../../../../p03/ch08/custom_widget.cpp)
+  （展示了 `QHBoxLayout` 布局管理，可与本示例的样式部分组合练习）
+- Qt 官方文档：*Qt Style Sheets Reference*（doc.qt.io，选读·需联网）
@@ -0,0 +1,58 @@
+// ============================================================================
+//  qt_qss_styling —— 教学补充示例（非 wiki 生成，手工维护）
+//  用途：方案书「C++方向 Day2」要求的 QSS 界面美化，仓库 p03/ 原有 wiki 抓取内容
+//        未覆盖这一点，故补一个最小示例。
+//  配套文档：docs/teaching/examples/qss_styling/README.md
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_qss_styling
+// ============================================================================
+
+#include <QApplication>
+#include <QWidget>
+#include <QPushButton>
+#include <QLabel>
+#include <QVBoxLayout>
+#include <QTimer>
+
+class StyledPanel : public QWidget {
+    Q_OBJECT
+public:
+    explicit StyledPanel(QWidget* parent = nullptr) : QWidget(parent) {
+        auto* title = new QLabel(QStringLiteral("QSS 样式演示"), this);
+        title->setObjectName("title");
+
+        auto* okBtn = new QPushButton(QStringLiteral("确定"), this);
+        okBtn->setObjectName("okButton");
+
+        auto* cancelBtn = new QPushButton(QStringLiteral("取消"), this);
+        cancelBtn->setObjectName("cancelButton");
+
+        auto* layout = new QVBoxLayout(this);
+        layout->addWidget(title);
+        layout->addWidget(okBtn);
+        layout->addWidget(cancelBtn);
+
+        // 整个窗口一份样式表：按 objectName 选择器精确命中控件，
+        // 也可以只用类型选择器（QPushButton { ... }）一次性套所有按钮。
+        setStyleSheet(
+            "QWidget { background-color: #f4f6f8; }"
+            "QLabel#title { font-size: 18px; font-weight: bold; color: #2b6cb0; padding: 6px; }"
+            "QPushButton { border-radius: 6px; padding: 6px 14px; color: white; }"
+            "QPushButton#okButton { background-color: #2f855a; }"
+            "QPushButton#okButton:hover { background-color: #276749; }"
+            "QPushButton#cancelButton { background-color: #a0522d; }"
+            "QPushButton#cancelButton:pressed { background-color: #7b3f22; }"
+        );
+    }
+};
+
+int main(int argc, char* argv[]) {
+    QApplication app(argc, argv);
+    StyledPanel panel;
+    panel.resize(240, 160);
+    panel.show();
+    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    QTimer::singleShot(200, &app, &QApplication::quit);
+    return app.exec();
+}
+
+#include "qt_qss_styling.moc"