Qt 自定义控件动画深度解析：从 QPropertyAnimation 到源码内幕

一、Qt 动画的三层架构

Qt 的动画系统不是"一套 API 打天下"，而是三层抽象，各有适用场景：

┌─────────────────────────────────────────────────────────────────────┐ │ Layer 3: QStateMachine + QState (状态机) │ │ 复杂状态转换、条件触发、历史状态、并行状态 │ │ 适用：复杂 UI 状态流转（向导、多步骤流程） │ └────────────────────────────┬────────────────────────────────────────┘ │ 内部用 QAbstractTransition + QPropertyAnimation ┌────────────────────────────▼────────────────────────────────────────┐ │ Layer 2: QAnimationGroup (动画组) │ │ QSequentialAnimationGroup / QParallelAnimationGroup │ │ 适用：复杂动画编排（串行、并行、嵌套） │ └────────────────────────────┬────────────────────────────────────────┘ │ 内部管理 QAbstractAnimation 子类 ┌────────────────────────────▼────────────────────────────────────────┐ │ Layer 1: QPropertyAnimation / QVariantAnimation (原子动画) │ │ 单属性插值、缓动曲线、时间线 │ │ 适用：单控件单属性动画（位置、透明度、颜色） │ └─────────────────────────────────────────────────────────────────────┘

选择原则：

二、QPropertyAnimation：属性动画核心

2.1 基本用法

// 最简单的属性动画：移动控件 QPropertyAnimation *animation = new QPropertyAnimation(button, "geometry"); animation->setDuration(1000); // 1 秒 animation->setStartValue(QRect(0, 0, 100, 30)); animation->setEndValue(QRect(200, 150, 100, 30)); animation->setEasingCurve(QEasingCurve::OutBounce); // 弹跳缓动 animation->start(QAbstractAnimation::DeleteWhenStopped);

关键点：QPropertyAnimation通过 Qt 的属性系统工作。目标对象必须有Q_PROPERTY，且该属性有READ/WRITE函数。

2.2 自定义控件动画属性

// 自定义圆形进度条 class CircularProgress : public QWidget { Q_OBJECT Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged) Q_PROPERTY(qreal angle READ angle WRITE setAngle NOTIFY angleChanged) public: explicit CircularProgress(QWidget *parent = nullptr); int value() const { return m_value; } void setValue(int v) { if (m_value == v) return; m_value = v; update(); // 触发重绘 emit valueChanged(v); } qreal angle() const { return m_angle; } void setAngle(qreal a) { m_angle = a; update(); emit angleChanged(a); } protected: void paintEvent(QPaintEvent *) override { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing); // 背景圆环 painter.setPen(QPen(Qt::gray, 8)); painter.drawArc(rect().adjusted(10, 10, -10, -10), 0, 360 * 16); // 进度圆弧 painter.setPen(QPen(Qt::blue, 8)); int span = static_cast<int>(m_angle * 16); // 1/16 度单位 painter.drawArc(rect().adjusted(10, 10, -10, -10), 90 * 16, -span); // 中心文字 painter.drawText(rect(), Qt::AlignCenter, QString::number(m_value) + "%"); } signals: void valueChanged(int); void angleChanged(qreal); private: int m_value = 0; qreal m_angle = 0; }; // 使用动画 CircularProgress *progress = new CircularProgress(this); progress->resize(120, 120); // 动画：0° → 360° 旋转 QPropertyAnimation *anim = new QPropertyAnimation(progress, "angle"); anim->setDuration(2000); anim->setStartValue(0.0); anim->setEndValue(360.0); anim->setLoopCount(-1); // 无限循环 anim->start();

三、QPropertyAnimation 源码解析

3.1 继承层次

// qtbase/src/corelib/animation/qabstractanimation.h class Q_CORE_EXPORT QAbstractAnimation : public QObject { Q_OBJECT Q_PROPERTY(State state READ state NOTIFY stateChanged) Q_PROPERTY(int duration READ duration) Q_PROPERTY(int loopCount READ loopCount WRITE setLoopCount) public: enum State { Stopped, Paused, Running }; enum Direction { Forward, Backward }; virtual int duration() const = 0; // 动画总时长（毫秒） State state() const; void start(DeletionPolicy policy = KeepWhenStopped); void pause(); void resume(); void stop(); void setCurrentTime(int msecs); protected: virtual void updateCurrentTime(int currentTime) = 0; // 核心虚函数 virtual void updateState(State newState, State oldState); };

3.2 QVariantAnimation：插值引擎

// qtbase/src/corelib/animation/qvariantanimation.h class Q_CORE_EXPORT QVariantAnimation : public QAbstractAnimation { Q_OBJECT Q_PROPERTY(QVariant startValue READ startValue WRITE setStartValue) Q_PROPERTY(QVariant endValue READ endValue WRITE setEndValue) Q_PROPERTY(QEasingCurve easingCurve READ easingCurve WRITE setEasingCurve) public: QVariant startValue() const; QVariant endValue() const; QVariant currentValue() const; // 当前插值结果 void setEasingCurve(const QEasingCurve &easing); protected: // 核心：子类重写此方法处理插值结果 virtual void updateCurrentValue(const QVariant &value) = 0; // 插值函数（可注册自定义类型） typedef QVariant (*ValueInterpolator)(const QVariant &from, const QVariant &to, qreal progress); static void registerInterpolator(ValueInterpolator func, int type); };

3.3 插值算法源码

// qtbase/src/corelib/animation/qvariantanimation.cpp void QVariantAnimation::updateCurrentTime(int currentTime) { // 计算进度 [0, 1] qreal progress = qreal(currentTime) / qreal(duration()); // 应用缓动曲线 progress = m_easingCurve.valueForProgress(progress); // 插值 QVariant result = interpolate(m_startValue, m_endValue, progress); // 通知子类 updateCurrentValue(result);