教案对齐官方方案书：重写为 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,49 @@
+# Model/View 模型视图架构 —— 教学补充示例
+
+> 对应方案书「C++方向 Day3」："高级控件应用与 Model/View 模型视图架构"。
+> 仓库 `p03/` 的 wiki 抓取内容里没有 Model/View 相关代码，本示例是手工补写的
+> 教学补充，**不属于** `tools/gen_part3.py` 的生成产物。
+
+## 概念
+
+Qt 的 Model/View 架构把"数据"和"展示"彻底解耦成三层：
+
+- **Model**（模型）：只管数据，不知道自己会被怎么展示。本示例用现成的
+  `QStandardItemModel`（也可以继承 `QAbstractListModel`/`QAbstractTableModel`
+  自己实现，工作量更大，教学上先用现成模型建立概念）；
+- **View**（视图）：只管展示和交互，不持有数据副本，展示什么完全来自
+  `setModel()` 绑的那个模型。本示例用 `QListView`；
+- **Selection Model**（选中状态）：视图的选中状态也被抽成独立对象
+  `QItemSelectionModel`，可以多个视图共享同一个选中状态。
+
+对比"没有 Model/View"的写法（比如直接往 `QListWidget` 里塞 `addItem()`）：数据
+和展示是绑死的；Model/View 的好处在于同一份数据可以同时喂给
+`QListView`/`QTableView`/`QComboBox` 等多个视图，改数据所有视图自动同步。
+
+## 代码走读
+
+见 [`qt_model_view_basics.cpp`](qt_model_view_basics.cpp)：
+
+1. 建一个 `QStandardItemModel`，塞 4 行字符串数据；
+2. 建一个 `QListView`，`setModel()` 绑定上面的模型——视图本身不存数据；
+3. 监听 `view->selectionModel()->currentChanged` 信号，选中项变化时更新一个
+   `QLabel`，体现"视图状态变化 → 通知外部"的解耦方式；
+4. 代码末尾手动 `setCurrentIndex()` 选中第一行，是为了离屏自动化验证时也能
+   触发一次 `currentChanged`（真实交互中这一步由用户点击触发）。
+
+## 验证方式
+
+```bash
+QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_model_view_basics
+```
+
+## 练习方向（供任务卡引用）
+
+- 把 `QListView` 换成 `QTableView`，模型不变，观察"同一份模型换个视图"是怎么
+  做到的；
+- 增加一个"删除选中行"按钮，调用 `model->removeRow(view->currentIndex().row())`，
+  体会数据变化后视图自动刷新（不需要手动重画）。
+
+## 参考
+
+- Qt 官方文档：*Model/View Programming*（doc.qt.io，选读·需联网）
@@ -0,0 +1,61 @@
+// ============================================================================
+//  qt_model_view_basics —— 教学补充示例（非 wiki 生成，手工维护）
+//  用途：方案书「C++方向 Day3」要求的 Model/View 模型视图架构，仓库 p03/ 原有
+//        wiki 抓取内容未覆盖这一点，故补一个最小示例。
+//  配套文档：docs/teaching/examples/model_view/README.md
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_model_view_basics
+// ============================================================================
+
+#include <QApplication>
+#include <QWidget>
+#include <QListView>
+#include <QLabel>
+#include <QVBoxLayout>
+#include <QStandardItemModel>
+#include <QTimer>
+#include <QItemSelectionModel>
+
+class ModelViewDemo : public QWidget {
+    Q_OBJECT
+public:
+    explicit ModelViewDemo(QWidget* parent = nullptr) : QWidget(parent) {
+        // 模型：数据本身，与展示方式无关
+        auto* model = new QStandardItemModel(this);
+        model->appendRow(new QStandardItem(QStringLiteral("需求分析")));
+        model->appendRow(new QStandardItem(QStringLiteral("项目设计")));
+        model->appendRow(new QStandardItem(QStringLiteral("编码实现")));
+        model->appendRow(new QStandardItem(QStringLiteral("测试及回归")));
+
+        // 视图：只负责展示，不持有数据
+        auto* view = new QListView(this);
+        view->setModel(model);
+
+        auto* selectedLabel = new QLabel(QStringLiteral("当前选中：（无）"), this);
+
+        // 选中项变化 → 视图层通知 → 界面同步更新，模型和视图之间没有直接耦合
+        connect(view->selectionModel(), &QItemSelectionModel::currentChanged,
+                this, [selectedLabel](const QModelIndex& current, const QModelIndex&) {
+                    if (current.isValid())
+                        selectedLabel->setText(QStringLiteral("当前选中：%1").arg(current.data().toString()));
+                });
+
+        auto* layout = new QVBoxLayout(this);
+        layout->addWidget(view);
+        layout->addWidget(selectedLabel);
+
+        // 离屏自动化验证：选中第一行，触发一次 currentChanged
+        view->setCurrentIndex(model->index(0, 0));
+    }
+};
+
+int main(int argc, char* argv[]) {
+    QApplication app(argc, argv);
+    ModelViewDemo w;
+    w.resize(280, 220);
+    w.show();
+    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    QTimer::singleShot(200, &app, &QApplication::quit);
+    return app.exec();
+}
+
+#include "qt_model_view_basics.moc"