Qt手绘水波纹需用QPainter逐帧绘制正弦波形，参数应封装为成员变量并配合QTimer更新相位；呼吸灯动效应驱动自定义Q_PROPERTY浮点属性而非样式表。
Qt 中用 QPainter 手绘水波纹动画的关键点
水波纹不是靠控件自带效果，得自己算正弦曲线并逐帧重绘。核心是用 QPainter::drawPolyline() 或 QPainter::drawPath() 绘制随时间偏移的波形，再叠加透明度渐变模拟扩散感。
常见错误是直接在 paintEvent() 里硬编码波长/振幅，导致缩放适配差、多控件复用难。正确做法是把波形参数（如周期 period、相位偏移 phaseOffset、衰减系数 decay）抽成成员变量，配合 QTimer 每次只更新 phaseOffset += 0.1。
- 波形顶点数别太少（建议 ≥ 64），否则锯齿明显；也别太多（>256），CPU 绘制压力陡增
- 横向采样步长要和控件宽度对齐：
step = width() / (pointCount - 1)，避免波形拉伸变形 - 务必启用
painter.setRenderHint(QPainter::Antialiasing)，否则边缘毛刺严重 - 如果控件尺寸动态变化，必须重载
resizeEvent()并调用update()，否则波形错位
用 QPropertyAnimation 实现呼吸灯动效的陷阱
呼吸灯本质是颜色透明度或亮度的周期性缓动，但直接对 QWidget::setStyleSheet() 做动画会触发频繁样式解析，卡顿明显。更稳的方式是用 QPropertyAnimation 驱动自定义属性，再在 paintEvent() 中读取该值重绘。
典型错误是绑定到 QColor 的 alpha 通道却没声明可动画属性，结果动画无声无息。必须先用 Q_PROPERTY 定义浮点型透明度变量，并配上 READ/WRITE 方法：
Q_PROPERTY(qreal pulseAlpha READ pulseAlpha WRITE setPulseAlpha)
然后让 QPropertyAnimation 动画这个属性，范围设为 0.0 到 1.0，缓动曲线选 QEasingCurve::InCurve 或 OutInSine 更接近真实呼吸节奏。
- 动画时长别设太短（
- 多个呼吸灯共用一个
QTimer而非各自QPropertyAnimation，省资源且节奏一致 - 若背景色非纯黑，光靠改 alpha 不够，得同步调整 RGB 基色亮度，否则明暗对比失真
水波纹 + 呼吸灯叠加时的合成顺序与性能取舍
两者叠加不是简单套两层动画，而是要在单次 paintEvent() 中按顺序绘制：先画背景（含呼吸灯主色），再在其上叠加油漆式水波纹（带 alpha 渐变），最后加高光点模拟水滴落点。顺序反了就会被遮盖。
性能瓶颈常出在每帧都新建 QPainterPath 或反复构造 QPolygonF。应提前在初始化时生成基础波形点集，动画中只做平移/缩放变换，用 QTransform 应用到路径上比重算坐标快 3–5 倍。
- 水波纹的扩散半径建议用指数衰减：
alpha = baseAlpha * qExp(-r / decayRadius)，比线性衰减更自然 - 呼吸灯的亮度峰值和水波纹最大振幅不要同步到达，错开约 1/4 周期，视觉更有层次
- 真机部署时关掉
QPainter::SmoothPixmapTransform（除非你真在画缩放图片），它会拖慢 20%+ 绘制帧率
移动端 Qt Quick 里替代方案：用 ShaderEffect 加速
如果目标平台是 Android/iOS，纯 CPU 绘制水波纹在低端机上容易掉帧。此时应切到 Qt Quick，用 ShaderEffect + GLSL 片元着色器实现，把波形计算压给 GPU。
关键不是写多炫的 shader，而是复用 Qt 已有的 qt_LightPosition 和 qt_Opacity 内置变量，避免重复传参。水波纹函数用 sin(2.0 * PI * (x + time * speed) / wavelength) 就够用，呼吸灯则用 0.5 + 0.5 * sin(time * breathSpeed) 控制整体 alpha。
- 着色器里禁止用
pow()或log()，移动端 GPU 支持差，用abs()或fract()替代 -
ShaderEffect的sourceItem必须是Item类型，不能是Rectangle直接赋值，否则编译报Invalid source item type - 调试时加一行
gl_FragColor = vec4(vTexCoord.x, vTexCoord.y, 0.0, 1.0);看 UV 是否映射正常，比猜强得多
实际项目里最常被忽略的是动效与系统主题的冲突——比如深色模式下呼吸灯用纯白会过曝，水波纹的默认蓝绿色在 OLED 屏上烧屏风险高。这些没法靠代码自动适配，得留配置入口让用户调基色和最大亮度。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
