QPropertyAnimation通过动画化windowOpacity（顶级窗口）或opacity（子控件）实现淡入淡出，需设置Qt::WA_TranslucentBackground、显式设起始值、show()后启动动画，并在finished信号中调用hide()或close()。
QPropertyAnimation 怎么控制窗口透明度
Qt 里实现淡入淡出，核心是动画化 windowOpacity 属性（对顶级窗口）或 opacity 属性（对 QWidget 子控件）。直接改值没动画效果，必须用 QPropertyAnimation 驱动。
注意：只有设置了 Qt::WA_TranslucentBackground 的窗口才能看到透明度变化；未设置时，windowOpacity 虽然生效，但可能被系统合成器截断或表现异常。
常见错误是调用 setWindowOpacity(0.0) 后立刻 show()，结果窗口一闪就消失——因为没加动画，系统直接渲染了全透明帧。正确做法是先 show()，再启动动画。
- 对主窗口淡入：
animation->setTargetObject(this)，animation->setPropertyName(b"windowOpacity") - 对子控件（如 QLabel）淡入：
animation->setTargetObject(label)，animation->setPropertyName(b"opacity") - 起始值必须显式设为 0.0（淡入）或 1.0（淡出），不能依赖当前值——控件刚创建时
opacity默认是 1.0，但windowOpacity可能因平台而异
为什么 fadeOut 后窗口没隐藏，还占任务栏
动画结束只是把透明度设成 0.0，窗口本身依然存在、可见（isVisible() 返回 true）、可交互（除非你禁用）。用户看不到，但系统仍把它当活跃窗口处理。
所以淡出完成后必须手动调用 hide() 或 close()，且要绑定在动画的 finished 信号上，不能写在动画 start() 后面——那会立刻执行，动画根本来不及播。
示例关键片段：
self.fade_out = QPropertyAnimation(self, b"windowOpacity") self.fade_out.setDuration(300) self.fade_out.setStartValue(1.0) self.fade_out.setEndValue(0.0) self.fade_out.finished.connect(self.hide) # 注意：是 self.hide，不是 self.hide() self.fade_out.start()
如果用 close()，记得检查是否允许关闭（比如有未保存数据），否则用户点 X 关闭时可能被动画打断逻辑。
QWidget::opacity 和 windowOpacity 的区别与兼容性
opacity 是 QWidget 的属性，作用于控件自身及其所有子控件，支持任意嵌套层级，但仅在父窗口启用 Qt::WA_TranslucentBackground 时才真正生效；windowOpacity 是顶层窗口属性，影响整个窗口（包括边框、标题栏），Windows/macOS/Linux 行为基本一致，但某些桌面环境（如 Wayland 下的 GNOME）可能忽略它。
性能上，opacity 是纯 Qt 渲染层操作，开销小；windowOpacity 依赖系统窗口管理器，频繁修改可能触发重绘同步，尤其在多屏或高 DPI 场景下偶现卡顿。
- 做局部动效（比如按钮悬停淡入）→ 用
opacity - 做整个窗口进出 → 优先用
windowOpacity，但测试时务必覆盖目标部署环境（特别是 Linux 发行版） - Qt 6.5+ 开始，
QQuickWindow推荐用OpacityAnimator替代，QWidget 项目仍以QPropertyAnimation为主
动画卡顿或不触发的几个硬坑
最常被忽略的是事件循环没跑起来：动画对象必须依附在有效的 QObject 上，且该对象生命周期不能早于动画结束；如果在局部函数里创建 QPropertyAnimation 并 start()，它可能在函数返回后就被析构，动画直接静默失败。
另一个典型问题是属性名写错——Python 中必须传 bytes（b"windowOpacity"），C++ 里用 QByteArrayLiteral("windowOpacity")，写成字符串字面量或 QString 会导致动画无声无息不工作。
- 确保动画对象是成员变量（如
self.anim），不是临时变量 - 检查目标对象是否已 show()，未显示的窗口无法触发动画重绘
- 避免在动画运行中反复 start() 同一个 animation 实例，应先
stop()再重新配置 - Qt 5.15+ 在 macOS 上若启用了
setGraphicsEffect，可能干扰 opacity 动画，临时移除特效可验证是否为此原因
透明度动画看着简单，实际要稳住得抠清对象生命周期、平台差异和属性绑定时机。尤其是跨平台发布前，一定在目标系统上实测淡出后 hide() 是否真从任务栏消失。
