简介：SideWidget.zip 是一份面向 Qt 桌面开发者的侧边栏动画示例包，重点解决侧边栏展开与收起时缺乏平滑过渡的问题，适合已掌握 Qt 基础控件、希望提升界面交互质感的中级学习者。压缩包共 12 个文件，约 9KB，以 4 个 cpp 源文件、3 个 h 头文件、3 个 ui 界面文件为主，并配有 pro 工程文件，涵盖主窗口、侧边栏与表单界面的组织方式，可直接编译对照学习。项目围绕自定义侧边栏控件展开，演示借助 QPropertyAnimation 对位置、尺寸与透明度做动画处理，通过滑出、滑入槽函数控制起止状态，并把按钮点击等交互信号与动画行为连接起来；同时涉及动画时长与缓动曲线的调节，便于按应用风格调整节奏。已有 1242 人学习，可帮助读者理解 Qt 动画机制、信号槽协作和抽屉式侧边栏的实现思路，并迁移到实际项目的导航面板与工具面板中。

1. 侧边栏不是加个抽屉那么简单：我在主窗口布局上翻过的车

给桌面端做工具类界面时，Qt 侧边栏几乎是绕不开的一块：左边挂导航树、参数面板、图层列表，右边是画布。需求方一句“展开收起的时候要有渐入渐出的感觉”，落到代码里就是一堆 QPropertyAnimation、布局重排和透明度特效的拉扯。我最早那版是在 QHBoxLayout 里塞一个 QFrame，点按钮改 setFixedWidth，动画一跑主窗口内容区就开始抽搐，快速连点两下还能把宽度卡在 37px 这种诡异数值上。SideWidget.zip 这份资源给的就是一个把侧边栏抽成独立控件、把渐入渐出收敛到单一进度属性里的实现，适合正在写 Qt Widgets 桌面应用、被侧边栏动画和布局冲突折腾过的人。

2. 拆开 SideWidget：类结构、三种形态与进度属性

拿到一份控件类源码，我不太会先跑 demo，而是先看头文件的 Q_PROPERTY 和 public 接口——这两处基本决定了这个控件能不能塞进现有工程，以及后面改起来会不会牵一发动全身。这份 SideWidget 的设计比较克制，核心就是一个继承自 QWidget 的类，对外暴露 expand / collapse / toggle 三个槽，内部用一个 0 到 1 的 progress 属性驱动全部视觉变化，动画对象只有一份。这种“单一状态源”的写法，是它比随手贴一段 QPropertyAnimation 代码更值钱的地方。

2.1 先分清三种侧边栏形态，形态决定动画属性

同样是“滑出来”，侧边栏在窗口里的角色不同，动画该改的属性完全不同。我把常见的三种形态列出来，选型的时候对着看就行：

挤压式最省事，加进布局就完事，代价是动画期间父布局每一帧都在重新计算子控件尺寸，内容区里如果有 QTableView 或者图表控件，很容易看到列宽跳动。覆盖式不碰布局，动画只改自己的位置，帧率稳，但要自己处理层级（raise）、事件穿透和阴影裁剪。抽屉式本质是覆盖式的一个特例，只是初始位置在窗口外，滑入距离更长，视觉上更“重”。

包里的 SideWidget 用了一个 enum Mode { Push, Overlay } 把前两种都覆盖了，Drawer 只是 Overlay 把起始 x 设成 -width 的写法，不需要单独一个枚举值。我在实际项目里选型的判断标准很粗暴：内容区里有重绘代价高的控件（表格、图表、视频预览）就走 Overlay，纯表单类界面走 Push，别为了省事一律 Push。

2.2 动画属性怎么选：geometry、maximumWidth 还是自定义 progress

这是整份代码里我最认可的一处设计取舍。先说说另外两条路为什么容易翻车。

直接动画geometry是网上最常见的示例写法：

// 常见但脆弱的写法：直接对 geometry 做动画 QPropertyAnimation *anim = new QPropertyAnimation(sidebar, "geometry", this); anim->setDuration(200); anim->setStartValue(QRect(0, 0, 0, h)); anim->setEndValue(QRect(0, 0, 240, h)); anim->start();

问题在于，只要 sidebar 参与了布局管理，布局在每一次 resize 事件里都会按自己的规则重新摆放子控件，动画刚把 geometry 设成 120px，布局下一帧就给你改回去，两边打架的结果就是抖动或者干脆不动。要让它生效，得先把控件从布局里摘出来，那又回到了 Overlay 的路子上。

动画maximumWidth是挤压式的常规做法，能用，但有两个细节要注意：一是必须同时保证 minimumWidth 不被别处设死，二是动画结束时要复位成 QWIDGETSIZE_MAX，否则后续用户拖拽调整宽度会被这个残留的 maximumWidth 卡住。我见过不止一个项目在动画结束后忘了复位，用户怎么拖都拖不宽，查了半天以为是 splitter 的锅。

这份实现走的是第三条路：自定义一个 qreal 类型的 progress 属性，0 表示完全收起，1 表示完全展开，setProgress 里根据当前 Mode 分别换算成宽度或者位置加透明度。

// sidewidget.h —— 只保留关键部分 class SideWidget : public QWidget { Q_OBJECT Q_PROPERTY(qreal progress READ progress WRITE setProgress) public: enum Mode { Push, Overlay }; explicit SideWidget(QWidget *parent = nullptr); void setMode(Mode m); // Push: 参与布局挤压; Overlay: 浮在父窗口上 void setExpandedWidth(int px); // 展开后的宽度，默认 240 void setDuration(int ms); // 动画时长，默认 180 void setEasing(const QEasingCurve &curve); public slots: void expand(); void collapse(); void toggle(); signals: void progressChanged(qreal p); void expanded(); void collapsed(); private: void setProgress(qreal p); // Q_PROPERTY 的 WRITE，动画每帧调用 qreal progress() const { return m_progress; } void animateTo(qreal target); qreal m_progress = 0.0; // 当前进度，唯一状态源 qreal m_target = 0.0; // 目标进度，用于判断动画方向 int m_width = 240; int m_duration = 180; Mode m_mode = Push; QEasingCurve m_easing = QEasingCurve::OutCubic; QPropertyAnimation *m_anim = nullptr; QGraphicsOpacityEffect *m_opacity = nullptr; };

参数说明几个：m_width是展开态宽度，用 int 而不是 qreal，因为最终要落到像素；m_duration默认 180ms，属于“快但不突兀”的区间，后面第 3 章会讲不同场景怎么调；m_easing默认 OutCubic，起步快、收尾缓，符合侧边栏“弹出来”的体感。m_progress对外只读，写入必须走动画或者 setProgress，外部代码拿不到“只改一半”的机会，这就是单一状态源的价值。

关键实现：

// sidewidget.cpp SideWidget::SideWidget(QWidget *parent) : QWidget(parent) { setObjectName("sideWidget"); // 让 QSS 里的 background 直接生效，自定义 QWidget 子类不加这句背景是透明的 setAttribute(Qt::WA_StyledBackground, true); setSizePolicy(QSizePolicy::Fixed, QSizePolicy::Expanding); m_anim = new QPropertyAnimation(this, "progress", this); m_anim->setDuration(m_duration); m_anim->setEasingCurve(m_easing); connect(m_anim, &QPropertyAnimation::finished, this, [this] { if (qFuzzyIsNull(m_target)) { if (m_mode == Overlay) hide(); // Overlay 收起后隐藏，避免拦截鼠标 emit collapsed(); } else { emit expanded(); } }); setFixedWidth(0); if (m_mode == Overlay) hide(); } void SideWidget::setProgress(qreal p) { m_progress = qBound(0.0, p, 1.0); const int w = qRound(m_width * m_progress); if (m_mode == Push) { // 挤压式：只动宽度，父布局会自动把内容区让出来 setFixedWidth(w); setVisible(w > 0); } else { // 覆盖式：宽度固定，动 x 坐标 + 透明度 setFixedWidth(m_width); move(qRound(-m_width * (1.0 - m_progress)), 0); if (m_opacity) m_opacity->setOpacity(m_progress); if (m_progress > 0.0) { show(); raise(); } } emit progressChanged(m_progress); } void SideWidget::animateTo(qreal target) { m_target = target; m_anim->stop(); // 先停，避免两个动画抢同一个属性 m_anim->setStartValue(m_progress); // 从当前值接着走，连点不回跳 m_anim->setEndValue(target); // 时长按剩余距离缩放：走到一半再点收回，不应该还跑满 180ms m_anim->setDuration(qRound(m_duration * qAbs(target - m_progress))); m_anim->start(); }

这段逻辑里有两个容易被忽略但很关键的点。一是m_anim->stop()必须在设置 startValue 之前，QPropertyAnimation 如果在运行中直接改 endValue，动画会从原始起点重新插值，视觉上就是“弹回去再走一遍”。二是时长按剩余距离缩放，快速连点时动画不会因为固定时长而显得拖沓。qRound不能省，qreal 转 int 直接截断在宽度很小时会出现“最后一像素跳变”。

2.3 把控件挂进主窗口：最小可运行集成

代码看得再顺，也得先能跑起来。Push 模式的集成是最小代价的，直接塞进现有布局：

// mainwindow.cpp 构造函数片段 auto *central = new QWidget(this); auto *layout = new QHBoxLayout(central); layout->setContentsMargins(0, 0, 0, 0); layout->setSpacing(0); auto *side = new SideWidget(central); side->setMode(SideWidget::Push); side->setExpandedWidth(240); side->setDuration(180); auto *content = new QWidget(central); content->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding); layout->addWidget(side); layout->addWidget(content, 1); // 拉伸因子 1，让内容区吃掉剩余空间 setCentralWidget(central); // 入口按钮挂到工具栏或内容区左上角 connect(toggleAction, &QAction::triggered, side, &SideWidget::toggle);

布局这块的坑集中在两处：contentsMargins必须清零，否则侧边栏收起后左边会留一条 9px 的白边，看起来像没关干净；addWidget(content, 1)的拉伸因子不能漏，漏了之后内容区会按 sizeHint 缩成一团。

Overlay 模式的集成要换一种写法，侧边栏不加入布局，而是作为父窗口的直接子控件：

// Overlay 模式：不参与布局，手动定位 auto *side = new SideWidget(this); // 父对象是主窗口本身 side->setMode(SideWidget::Overlay); side->setExpandedWidth(260); side->resize(260, height()); // 高度先跟窗口对齐 side->move(-260, 0); // 初始停在窗口左侧外 side->raise(); // 保证盖在内容区上面

Overlay 模式还必须处理主窗口 resize：窗口变大变小，侧边栏的高度得跟着改，否则会出现“侧边栏只有上半截有背景”的割裂感。常见做法是重写主窗口的 resizeEvent，在里面调一次side->setFixedHeight(height())。另外别忘了在合适的时机 raise()，否则新建的任何子控件都会盖在它上面。

3. 渐入渐出的手感：时长、缓动和打断策略

动画能不能看，八成取决于三个参数：时长、缓动曲线、起始值。剩下的两成是打断逻辑——用户不会等你动画播完再点第二次，快速连点是常态。这一章把这几个参数拆开讲，每个都给出我实际用下来比较稳的取值区间，以及为什么。

3.1 时长与缓动：180ms 不是拍脑袋定的

时长这件事有明确的体感边界。低于 100ms，人眼基本感知不到“过程”，只能看到状态跳变，渐入渐出的意义就没了；超过 300ms，第一次点还行，连续操作时会明显觉得界面在拖后腿。桌面端侧边栏我一般落在 160 到 220ms 之间，默认 180ms 覆盖大多数场景。

缓动曲线这块，QEasingCurve 内置的类型够用，不需要自己写贝塞尔。OutCubic 在 t=0.5 时大约完成 87% 的位移，前段快后段慢，视觉上是“弹出来然后稳住”，非常适合展开动作。InOutQuad 两头慢中间快，适合遮罩层这种需要“柔和出现”的元素。QEasingCurve::OutBack 会有一点回弹，很多 demo 喜欢用，但侧边栏带回弹会让边缘短暂超出父窗口被裁掉，除非你确定父窗口留了足够 margin，否则别碰。

side->setEasing(QEasingCurve(QEasingCurve::OutCubic));

改缓动只需要这一行，因为曲线是在 animateTo 里每次 start 前应用的。如果想让展开和收起用不同曲线（展开用 OutCubic，收起用 InCubic 会更快收干净），在 animateTo 里按 target 分支设置就行，但要记得在 start 之前设，运行中改曲线不会立即生效。

3.2 位移和透明度并行：什么时候需要 QParallelAnimationGroup

自定义 progress 属性把位移和透明度绑在一个变量上了，好处是一致性强，代价是没法给两者设不同的时长和曲线。有些场景确实需要分开：比如覆盖式侧边栏滑入 200ms，但它背后的半透明遮罩层只要 120ms 淡入，视觉层次会更清楚。

这种时候就用 QParallelAnimationGroup，几个动画同时跑，各自的时长独立：

// 遮罩层 + 侧边栏并行动画，各自独立时长 auto *group = new QParallelAnimationGroup(this); auto *slide = new QPropertyAnimation(side, "pos", group); slide->setDuration(200); slide->setEasingCurve(QEasingCurve::OutCubic); slide->setStartValue(QPoint(-260, 0)); slide->setEndValue(QPoint(0, 0)); auto *fade = new QPropertyAnimation(mask, "opacity", group); // mask 是带 opacity 属性的遮罩控件 fade->setDuration(120); fade->setEasingCurve(QEasingCurve::OutQuad); fade->setStartValue(0.0); fade->setEndValue(0.6); group->start(QAbstractAnimation::DeleteWhenStopped);

这里mask的 opacity 属性得自己定义，QWidget 本身没有可动画的 opacity，常见做法是套一个 QGraphicsOpacityEffect，或者用一个自绘的半透明 QWidget 加自定义 Q_PROPERTY。DeleteWhenStopped让 group 在播完后自动销毁，省掉手动 deleteLater，但要注意别在别处还留着一个裸指针指向它。

用 group 的时候有个坑：多个动画同时作用于同一个控件，如果其中一个的 startValue 和另一个的写入冲突（比如一个改 pos 一个改 geometry），最终结果取决于属性写入顺序，这种不确定性在跨平台时尤其难查。原则是同一个视觉维度只让一个动画负责。

3.3 打断与连点：别让两个动画抢同一个属性

侧边栏被快速连点是必然会发生的，尤其是在“展开/收起”共用一个按钮的界面上。没处理好的表现是：点三下，侧边栏停在半开状态，或者宽度变成负数。

正确的做法在前面 animateTo 里已经写了：stop → 读当前值当起点 → 设终点 → 按剩余距离算时长 → start。这里再补充两个边界。

第一，动画进行中用户点了“收起”，此时 m_progress 可能是 0.6，目标 0.0，剩余距离 0.6，时长按比例缩到 108ms。但如果用户点得非常快，m_progress 只走到 0.02 就反向，时长会缩到 4ms 左右，动画几乎等于瞬移，视觉上会闪一下。解决办法是给时长设一个下限：

void SideWidget::animateTo(qreal target) { m_target = target; m_anim->stop(); m_anim->setStartValue(m_progress); m_anim->setEndValue(target); // 下限 80ms：剩余距离再短也留一点过渡，避免高刷屏上出现单帧跳变 const int ms = qMax(80, qRound(m_duration * qAbs(target - m_progress))); m_anim->setDuration(ms); m_anim->start(); }

第二，动画结束的回调里不要再无条件触发动画。finished 信号在 stop() 时不会发出，但在 setEndValue 之后自然结束时一定会发出，如果槽函数里有“结束后自动收起”之类的逻辑，容易和用户的主动操作打架。我的习惯是在槽里判断m_target而不是判断当前进度，因为 target 是意图，progress 只是过程值。

还有一个容易被忽略的：窗口在动画进行中被销毁。QPropertyAnimation 的父对象设成了 this，正常情况下没问题，但如果侧边栏是被 new 出来且没有父对象的（Overlay 模式误写成new SideWidget()），窗口关闭时动画还在跑，访问已析构的对象就是崩溃。这也是第 5 章要专门说的一条。

4. 接进真实界面：布局、高 DPI、焦点与样式

demo 里跑得顺，接进真实工程立刻会冒出另一批问题：窗口缩放时内容区闪烁、4K 屏上宽度算出小数、侧边栏展开后焦点还在隐藏的按钮上、QSS 背景写好了却不显示。这些不是控件本身的 bug，是集成层面的细节，但每一个都能让上线延期。

4.1 挤压式的内容区闪烁，和它的三种缓解办法

Push 模式每一帧都在改 setFixedWidth，父布局随之重排，内容区里的子控件会收到大量 resizeEvent。如果内容区里有 QTableView、QChart 或者自绘的波形图，它们的 resize 处理往往是“重新计算 + 重新布局”，一秒钟触发六十次就会出现可见的闪烁。

第一种缓解办法是动画期间关闭内容区的重绘更新：

// 动画期间冻结内容区绘制，结束后恢复 connect(side, &SideWidget::progressChanged, content, [content](qreal p) { content->setUpdatesEnabled(p <= 0.0 || p >= 1.0); });

setUpdatesEnabled(false) 会让控件在这段时间里不处理 paintEvent，动画结束后一次性重绘。代价是动画期间内容区会“冻住”不动，如果内容本身是静态的（表单、参数面板），这个代价可以接受，如果是视频预览之类的动态内容就不行了。

第二种是给内容区加固定最小宽度，避免在动画过程中触发内部的换行逻辑。比如内部是按宽度决定单列还是双列的面板，动画经过某个临界宽度时会来回切换，视觉上像抽搐。给它设一个 minimumWidth 大于那个临界值，问题就消失了。

第三种就是换 Overlay 模式，从根上不重排。这也是我在内容区复杂时默认选 Overlay 的原因——省下来的调试时间远超多写的那几十行定位代码。

4.2 高 DPI 与像素对齐：qRound 不能省

Qt5 要开Qt::AA_EnableHighDpiScaling，Qt6 默认开启。开了之后逻辑像素和物理像素是分开的，qRound(m_width * m_progress)里的乘法结果是 qreal，直接赋给 setFixedWidth(int) 会隐式截断。在 125% 缩放下，240 * 0.583 算出来是 139.92，截断成 139，动画每一帧都少半个像素，累积下来能看到边缘“爬行”。

// main.cpp，Qt5 工程需要，Qt6 可省 QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling); QCoreApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);

除了宽度，move 的坐标也要 qRound。Overlay 模式下move(qRound(-m_width * (1.0 - m_progress)), 0)如果不取整，屏幕缩放为 150% 时侧边栏右侧会出现一条 1 物理像素的缝隙，露出底下的内容区。这种问题在开发机上往往看不出来，到了客户的缩放环境里就变成“界面有缝”的反馈。

另外，判断进度是否到 0 或 1 不要用==，用 qFuzzyIsNull 和 qFuzzyCompare。浮点累加之后 1.0 可能是 0.99999994，用==判断会导致 hide() 永远不执行，侧边栏“看起来收起了但还在拦截鼠标”。

4.3 焦点、快捷键和 Esc 关闭

侧边栏收起之后，如果里面的按钮还持有焦点，用户按 Tab 会跳进一个看不见的控件，按空格还会触发它。这是无障碍层面也说不通的行为。

// 收起完成时清焦点，并把焦点还给内容区 connect(side, &SideWidget::collapsed, this, [this, content] { if (side->focusWidget()) side->focusWidget()->clearFocus(); content->setFocus(Qt::OtherFocusReason); });

展开时的焦点策略相反：如果侧边栏里第一个可交互控件是搜索框，展开后自动 setFocus 会让用户直接开始输入，体验最好。但要注意别在动画中途设焦点，控件位置还在变，某些平台上输入法候选框会跟着乱飘，放到 expanded 信号里做。

快捷键我一般配两个：一个全局的 toggle（比如 Ctrl+B，跟主流编辑器一致），一个 Esc 收起。

auto *toggleSc = new QShortcut(QKeySequence("Ctrl+B"), this); connect(toggleSc, &QShortcut::activated, side, &SideWidget::toggle); auto *escSc = new QShortcut(QKeySequence(Qt::Key_Escape), this); connect(escSc, &QShortcut::activated, side, [side] { if (side->isExpanded()) side->collapse(); });

Esc 这个键要小心和对话框的默认行为冲突。如果主窗口里弹了模态对话框，Esc 会先被对话框吃掉，这没问题；但如果侧边栏本身是个 Popup 或者带 Qt::Popup 标志，Esc 的默认处理会先关闭它，你的快捷键可能收不到。用 QShortcut 而不是重写 keyPressEvent，能避开大部分这类冲突。

4.4 QSS 样式、圆角和阴影：自绘那关绕不过去

自定义 QWidget 子类直接用 QSS 写 background 是不生效的，这是 Qt 样式系统里最经典的坑之一。原因是 QWidget 的 paintEvent 默认什么都不画，样式表里的背景需要控件自己通过 PE_Widget 绘制出来。两种解法：

// 解法一：构造函数里加一行，最省事 setAttribute(Qt::WA_StyledBackground, true); // 解法二：自己重写 paintEvent，控制力更强 void SideWidget::paintEvent(QPaintEvent *) { QStyleOption opt; opt.initFrom(this); QPainter p(this); style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this); }

第一种适合背景是纯色或者渐变的情况，第二种适合需要在背景上再画圆角、描边、分隔线的场景。我一般用第一种，圆角通过 QSS 的 border-radius 解决。

圆角加上阴影就麻烦了。QGraphicsDropShadowEffect 是作用在整个控件上的离屏渲染特效，父窗口如果开了裁剪，阴影超出父窗口边界的部分会被直接切掉，看起来像阴影只画了一半。Overlay 模式的常见解法是给父窗口留出 margin，让侧边栏不贴着窗口边缘，或者干脆放弃阴影，用一层半透明的描边代替。后者性能更好，视觉上也够用：

#sideWidget { background-color: #1f2329; border-right: 1px solid rgba(255, 255, 255, 0.08); }

还有一个细节：QGraphicsOpacityEffect 和 QWidget 的 border-radius 一起用时，圆角外的区域在透明度变化过程中可能出现黑边或白边，取决于底层绘制合成方式。如果侧边栏本身是圆角的，透明度动画建议只对内容做，不要对整个控件做。

5. 排查清单：侧边栏动画的五个高频翻车现场

这一章按“现象 → 原因 → 解决”列五条，都是我在集成过程中实际遇到过、并且能稳定复现的。按出现频率排序，第一条几乎是必踩。

5.1 收起后看不见，但鼠标点不穿

现象：侧边栏动画走完，视觉上已经消失，但原本侧边栏覆盖的区域点击没反应，下面的内容区按钮点不动。

原因：Push 模式下 setFixedWidth(0) 之后控件宽度为 0，理论上不接收鼠标，但如果父布局给它留了 spacing 或者 contentsMargins，实际占位还在；Overlay 模式下更常见，动画把 x 移到 -260，控件本身仍然 show 着，只是移出了可视区，它的鼠标事件判定依然在窗口坐标系里，某些情况下会吞掉边缘的点击。

解决：Overlay 模式必须在收起完成时 hide()，这份实现在 finished 回调里做了。Push 模式要确认父布局的 contentsMargins 和 spacing 都是 0，另外可以显式设setAttribute(Qt::WA_TransparentForMouseEvents, p <= 0.0)，双保险。

5.2 动画最后一帧闪一下白或者黑

现象：展开动画结束的瞬间，侧边栏整块闪一下，颜色和正常状态不一样，一闪而过但很显眼。

原因：QGraphicsOpacityEffect 在 opacity 接近 1 时会重新走一次离屏渲染合成，某些显卡驱动上这一帧的合成结果和常态绘制不一致。另一个常见原因是 finished 回调里调用了 hide() 之后又立刻 show()，中间有一帧没有内容。

解决：透明度动画的终点不要设成精确的 1.0，设 0.999 或者干脆在动画结束的槽里再把 effect 摘掉（setGraphicsEffect(nullptr)），让控件回到常规绘制路径。如果闪的是白色，检查 QSS 背景色是否只在 #sideWidget 选择器上设了，子控件背景透明导致的透出。

5.3 QGraphicsOpacityEffect 让视频或 OpenGL 控件变黑

现象：侧边栏里嵌了一个视频预览窗口或者 QOpenGLWidget，加了透明度特效之后这块区域全黑，或者干脆不刷新。

原因：QGraphicsOpacityEffect 会把整个控件树渲染到离屏缓冲区再合成，而 QOpenGLWidget 走的是独立的原生窗口句柄（native window），它没法被离屏渲染捕获，结果就是这块区域在外效果下变成空白或黑色。

解决：两种情况。如果只是整块侧边栏的透明度动画，改成用背景色的 alpha 通道做视觉过渡，不动整个控件的合成。如果必须对 GL 区域做淡入，把它从侧边栏里拆出来，作为兄弟控件单独做位置动画，透明度只作用在外围的框上。这个限制在 Qt5 和 Qt6 里都存在，换版本解决不了。

5.4 QSS 背景写好了，运行起来是透明的

现象：样式表里明明写了#sideWidget { background-color: #1f2329; }，运行后侧边栏区域完全透明，能看到底下的内容区。

原因：SideWidget 继承自 QWidget，paintEvent 没有调用 PE_Widget 绘制，样式表里的背景被忽略。这和 4.4 说的是同一个坑，但它出现的时机很随机——如果类里恰好重写了 paintEvent 画了点东西，就正常；没重写就透明，很容易误判成选择器写错了。

解决：构造函数里加setAttribute(Qt::WA_StyledBackground, true)，或者重写 paintEvent 手绘。加完之后如果背景出来了但圆角没出来，再检查 border-radius 是否写在同一个选择器上，子控件的背景是否会盖住圆角区域。

5.5 反复开关之后内存上涨

现象：侧边栏开关几十次之后，进程内存缓慢增长，任务管理器里能看到几百 KB 到几 MB 的增量，长时间运行会累积。

原因：每次 toggle 都 new 一个 QPropertyAnimation 或者 QParallelAnimationGroup，父对象挂在 this 上，理论上有父对象就会被回收，但如果动画是start(DeleteWhenStopped)且同时还有别的地方持有指针，或者 lambda 捕获了 this 又连到了长生命周期的信号上，就会出现泄漏或者悬空指针。

解决：动画对象在构造函数里 new 一次，复用，靠 setStartValue 和 setDuration 改参数，这份 SideWidget 就是这么做的。如果必须要临时创建，用start(QAbstractAnimation::DeleteWhenStopped)且不要再持有裸指针。另外检查 connect 的 lambda 捕获列表，能用值捕获就别捕获 this。

6. 进阶：把参数抽成配置，以及上线前的验证清单

到这一步控件能用了，但离“好维护”还差一点。我的习惯是把影响体感的参数全部抽成一组 setter，让不同界面按需覆盖，而不是每次改动画都去翻源码改常量。这份 SideWidget 的接口已经覆盖了大部分，还缺一个统一的配置入口：

验证方法不用写单元测试那么重，我一般跑一个手工清单：100% 和 150% 两种缩放各开关二十次，看有没有残留的 1px 缝隙；动画中途连点五次，确认最终状态和按钮状态一致；侧边栏收起后按 Tab 走一圈，确认焦点不会跑进隐藏控件；挂一个 QTimer 每 100ms 打印一次 m_progress，确认数值单调不抖；最后用 QElapsedTimer 卡一下动画实际耗时，和设定值偏差超过 20% 就说明主线程被别的东西堵了，得去查是谁在动画期间做了重活。

还有个我踩过的进阶坑：如果侧边栏里放了 QScrollArea，而滚动条策略是 AsNeeded，动画过程中宽度不断变化，滚动条会反复出现消失，内容宽度跟着跳，看起来像在抖。给滚动区设固定 verticalScrollBarPolicy，或者干脆 AlwaysOff 配鼠标滚轮，能省掉一大半这类问题。

从那以后我每次接一个新工程的侧边栏，都强制先跑一遍这个清单，尤其是焦点和鼠标穿透这两项——它们不会在截图里露馅，但会在验收当天被用户第一个点出来。包里这份实现把状态源和打断逻辑都收在一个属性上了，照着改一个自己的入口按钮就能接进现有布局，比从零拼 QPropertyAnimation 少走不少弯路。希望帮到你。

本文还有配套的精品资源，点击获取