每个「讲」知识点补齐核心概念 + 常见的坑,幻灯片与大纲同步

此前一版「讲」部分基本只是代码演示(贴代码 + 一句出处说明),没有讲透
知识点本身的原理。改为覆盖清单原则:每个知识点在大纲里至少固定两项——
核心概念(是什么/为什么,不只是怎么写)+ 常见的坑(注意事项/误区),
课堂实际讲解深度按学员反馈现场调整,但大纲必须列全,以免漏讲或退化成
纯代码演示。

- custom.css 新增 .concept-box/.pitfall-box 卡片样式
- day1–5.html 每个知识点前插入对应卡片,内容与 OUTLINE.md 的覆盖清单一一对应
This commit is contained in:
张宗平
2026-07-02 16:25:46 +08:00
parent ee902fb1e0
commit a6743fcea0
7 changed files with 716 additions and 31 deletions
+102
View File
@@ -30,6 +30,30 @@
<h2>2D 绘图 / 多线程 <span class="tag tag-lecture"></span></h2>
</section>
<section>
<h3>QPainter:由 Qt 驱动的重绘模型 <span class="tag tag-lecture"></span></h3>
<div class="concept-box">
<h4>核心概念</h4>
<ul>
<li>Qt 的绘制是"框架驱动"而非"你想画就画":所有绘制只能发生在 <code>paintEvent</code>
里,由 Qt 在需要重绘时(窗口刚显示、被遮挡后重新露出、你主动请求)自动调用——这和直接式
绘图(想画就立刻画到屏幕)是不同的模型。</li>
<li>控件想主动触发重绘要调用 <code>update()</code>(异步,排队到下次事件循环处理)而不是
直接调用 <code>paintEvent()</code><code>QPainter</code> 只是"在哪个设备上画"的画笔,
画布可以是控件本身,也可以是 <code>QImage</code>/<code>QPixmap</code> 等离屏设备。</li>
</ul>
</div>
<div class="pitfall-box">
<h4>常见的坑</h4>
<ul>
<li><code>paintEvent</code> 之外的地方直接 <code>new QPainter(this)</code> 画东西:
要么无效要么未定义行为,绘制必须在 <code>paintEvent</code> 回调期间进行。</li>
<li>数据变了却忘记调用 <code>update()</code>:界面不会自动感知"要重画了",看起来像是
"画错了",其实是"根本没重画"。</li>
</ul>
</div>
</section>
<section>
<h3>绘图:QPainter <span class="tag tag-lecture"></span></h3>
<pre><code class="cpp" data-trim data-noescape>
@@ -48,6 +72,33 @@ void paintEvent(QPaintEvent*) override {
<a class="filelink" target="_blank" href="../../../p03/ch10/paint_device_pixmaps.cpp">paint_device_pixmaps.cpp</a></small></p>
</section>
<section>
<h3>QThread:线程亲和性与 worker-object <span class="tag tag-lecture"></span></h3>
<div class="concept-box">
<h4>核心概念</h4>
<ul>
<li>"线程亲和性"thread affinity):每个 QObject 都归属于创建它/被
<code>moveToThread</code> 移动到的那个线程,它的槽函数默认在所属线程执行——GUI 控件必须
始终归属主线程,这是 Qt 线程模型的核心约束。</li>
<li>官方推荐的是 worker-object 模式(把耗时逻辑放进一个普通 QObject,
<code>moveToThread</code> 到工作线程),而不是继承 <code>QThread</code> 重写
<code>run()</code>——前者能继续用信号槽通信,后者容易把线程亲和性搞混。</li>
<li>跨线程的信号槽连接会自动变成 Queued(回顾
<a class="filelink" target="_blank" href="day2.html">Day2</a>),结果通过事件循环
安全地"带回"接收者所在线程,不需要手动加锁。</li>
</ul>
</div>
<div class="pitfall-box">
<h4>常见的坑</h4>
<ul>
<li>在工作线程里直接操作 GUI 控件(比如直接 <code>label->setText()</code>):Qt 的 GUI
模块不是线程安全的,这是未定义行为/崩溃的常见来源——正确做法永远是发信号,排队回主线程处理。</li>
<li><code>moveToThread</code> 要在 <code>connect</code><code>thread.start()</code>
之前完成;对象一旦有耗时任务在跑,中途再挪线程会有竞态。</li>
</ul>
</div>
</section>
<section>
<h3>QThread 多线程(教学补充) <span class="tag tag-lecture"></span></h3>
<pre><code class="cpp" data-trim data-noescape>
@@ -117,6 +168,32 @@ connect(&workerThread, &QThread::started, &worker, &Worker::process);
<h2>动画框架 / 状态机 <span class="tag tag-lecture"></span></h2>
</section>
<section>
<h3>QPropertyAnimation:动画建立在属性系统上 <span class="tag tag-lecture"></span></h3>
<div class="concept-box">
<h4>核心概念</h4>
<ul>
<li>Qt 的属性系统(<code>Q_PROPERTY</code>,同样靠
<a class="filelink" target="_blank" href="day2.html">Day2</a> 讲过的 moc 生成)给每个属性配了
统一的 get/set 接口;动画框架的本质就是"在一段时间内,用缓动曲线不断调用某个属性的
setter",所以任何声明成 <code>Q_PROPERTY</code> 的属性(不只是内置的 geometry/opacity
都能被动画驱动。</li>
<li><code>QEasingCurve</code> 决定的是"数值随时间变化的曲线形状"(线性/回弹/加减速……),
动画本身只是"定时器 + 插值 + 调 setter"的组合,理解这点能解释为什么几乎所有属性都能做动画。</li>
</ul>
</div>
<div class="pitfall-box">
<h4>常见的坑</h4>
<ul>
<li>要动画化的属性必须是真正的 <code>Q_PROPERTY</code>(有 setter),随手传一个字符串
属性名如果对应类没有声明该属性,动画不会报错,只是什么也不会发生。</li>
<li>动画作用的对象在动画播放完成前被销毁会导致悬空访问;
<code>QAbstractAnimation::DeleteWhenStopped</code> 能让动画结束后自动释放自身,但不管
目标对象的生命周期,目标对象仍需自己保证不提前销毁。</li>
</ul>
</div>
</section>
<section>
<h3>QPropertyAnimation 动画(教学补充) <span class="tag tag-lecture"></span></h3>
<pre><code class="cpp" data-trim data-noescape>
@@ -132,6 +209,31 @@ anim->start(QAbstractAnimation::DeleteWhenStopped);
<a class="filelink" target="_blank" href="../examples/property_animation/README.md">配套 README</a></small></p>
</section>
<section>
<h3>QStateMachine:状态机建立在信号槽上 <span class="tag tag-lecture"></span></h3>
<div class="concept-box">
<h4>核心概念</h4>
<ul>
<li>状态机解决的是"同一个控件在不同状态下行为/外观不同"的问题——与其用一堆
<code>bool</code> 标志位加 if-else 判断当前处于什么状态,不如让"状态"本身成为一等对象
<code>QState</code>),每个状态自己声明"进入这个状态要怎样"(<code>assignProperty</code>
又用到了 Qt 属性系统)。</li>
<li>状态之间的切换(<code>addTransition</code>)本质是"信号触发的转移"——转移条件就是
一个信号,这让状态机和信号槽自然衔接:任何能发信号的事件都能驱动状态切换。</li>
</ul>
</div>
<div class="pitfall-box">
<h4>常见的坑</h4>
<ul>
<li>忘记 <code>machine.setInitialState(...)</code> 或忘记调用 <code>machine.start()</code>
状态机对象存在但从未真正运行,所有 <code>assignProperty</code>/<code>addTransition</code>
都不会生效。</li>
<li>某个状态没有覆盖所有可能触发的信号/条件,会导致状态机"卡住"——设计状态机前先把所有
状态和转移条件画成图,比直接写代码更不容易漏。</li>
</ul>
</div>
</section>
<section>
<h3>QStateMachine 状态机(教学补充) <span class="tag tag-lecture"></span></h3>
<pre><code class="cpp" data-trim data-noescape>