本页内容

QVariantAnimation Class

QVariantAnimation 类为动画提供了基类。更多内容...

头文件: #include <QVariantAnimation>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
继承自: QAbstractAnimation
被继承者:

QPropertyAnimation

公共类型

属性

公共函数

QVariantAnimation(QObject *parent = nullptr)
virtual ~QVariantAnimation()
QBindable<int> bindableDuration()
QBindable<QEasingCurve> bindableEasingCurve()
QVariant currentValue() const
QEasingCurve easingCurve() const
QVariant endValue() const
QVariant keyValueAt(qreal step) const
QVariantAnimation::KeyValues keyValues() const
void setDuration(int msecs)
void setEasingCurve(const QEasingCurve &easing)
void setEndValue(const QVariant &value)
void setKeyValueAt(qreal step, const QVariant &value)
void setKeyValues(const QVariantAnimation::KeyValues &keyValues)
void setStartValue(const QVariant &value)
QVariant startValue() const

重新实现的公共函数

virtual int duration() const override

信号

void valueChanged(const QVariant &value)

受保护函数

virtual QVariant interpolated(const QVariant &from, const QVariant &to, qreal progress) const
virtual void updateCurrentValue(const QVariant &value)

重新实现的受保护函数

virtual bool event(QEvent *event) override
virtual void updateCurrentTime(int) override
virtual void updateState(QAbstractAnimation::State newState, QAbstractAnimation::State oldState) override
void qRegisterAnimationInterpolator(QVariant (*func)(const T &, const T &, qreal))

详细说明

该类是《动画框架》的一部分。它作为属性动画和项目动画的基类,提供了用于实现共享功能的函数。

该类对QVariant进行插值,但将如何使用插值结果留给其子类处理。目前,Qt提供了QPropertyAnimation ,用于对Qt属性进行动画处理。若需对这类属性进行动画处理,请参阅QPropertyAnimation 类的描述。

随后,您可以通过调用setStartValue()和setEndValue()为属性设置起始值和结束值,最后调用start()来启动动画。QVariantAnimation将对目标对象的属性进行插值,并发出valueChanged()信号。若要响应当前值的变更,您需要重写updateCurrentValue()虚拟函数,或连接到该信号。

还可以为起始值和结束值之间的指定步长设置数值。此时,插值过程将在这些指定步长处经过这些点。请注意,起始值和结束值被定义为 0.0 和 1.0 处的关键值。

有两种方法可以影响 QVariantAnimation 对值的插值方式。您可以通过调用setEasingCurve() 设置缓入缓出曲线,并通过调用setDuration() 配置持续时间。您还可以通过创建 QVariantAnimation 的子类,并重写虚拟函数interpolated() 来更改QVariant的插值方式。

如果您有QVariant,但不希望将其声明为Qt属性,那么继承QVariantAnimation可以作为一种替代方案。但请注意,在大多数情况下,将QVariant 声明为属性会更好。

并非所有QVariant 类型都受支持。以下是当前受支持的QVariant 类型列表:

如果您需要对其他变体类型(包括自定义类型)进行插值,则必须自行实现这些类型的插值功能。为此,您可以为给定类型注册一个插值函数。该函数接受 3 个参数:起始值、结束值和当前进度。

示例:

QVariant myColorInterpolator(constQColor&start, constQColor&end,qreal progress)
{
    // ...
    returnQColor(/*...*/);
}
// ...
voidsomeFunc()
{
    // ...
    qRegisterAnimationInterpolator<QColor>(myColorInterpolator);
   // ...
}

另一种方法是重写 `interpolated()` 方法,该方法会返回待插值的值的插值结果。

另请参阅 QPropertyAnimation 、QAbstractAnimation 以及《动画框架》。

成员类型文档

[alias] QVariantAnimation::KeyValue

这是一个对 std::pair<qreal,QVariant> 的类型定义。

QVariantAnimation::KeyValues

这是QList 的typedef <KeyValue>

属性文档

[read-only] currentValue : QVariant

该属性存储动画的当前值。

该属性描述了当前值;它是根据当前时间作为进度基准,在start value 和end value 之间插值得到的值。该值本身由interpolated()获取,该函数会在动画运行期间被反复调用。

QVariantAnimation 当当前值发生变化时,会调用虚拟函数 `updateCurrentValue()`。这对需要跟踪更新的子类特别有用。例如,`QPropertyAnimation ` 便使用该函数来对 Qt属性进行动画处理。

访问函数:

QVariant currentValue() const

Notifier 信号:

void valueChanged(const QVariant &value)

另请参阅 startValue 和endValue 。

[bindable] duration : int

注意:此 属性支持QProperty 绑定。

该属性用于指定动画的持续时间

该属性描述动画的持续时间(以毫秒为单位)。默认持续时间为 250 毫秒。

访问函数:

virtual int duration() const override
void setDuration(int msecs)

另请参阅 QAbstractAnimation::duration()。

[bindable] easingCurve : QEasingCurve

注意:此 属性支持QProperty 绑定。

该属性用于指定动画的缓动曲线

该属性定义了动画的缓入缓出曲线。默认情况下,使用线性缓入缓出曲线,从而产生线性插值。还提供了其他曲线,例如QEasingCurve::InCirc ,它提供了一种圆形的起始曲线。另一个例子是QEasingCurve::InOutElastic ,它对插值变量的值产生弹性效果。

QVariantAnimation 将使用QEasingCurve::valueForProgress() 函数,将动画的“归一化进度”(currentTime() /totalDuration()) 转换为动画实际使用的有效进度。当调用interpolated() 时,该有效进度即为进度值。此外,keyValues 中的步骤也基于此有效进度。

缓动曲线与插值器、interpolated() 虚拟函数以及动画的持续时间配合使用,以控制当前值在动画进行过程中如何变化。

访问函数:

QEasingCurve easingCurve() const
void setEasingCurve(const QEasingCurve &easing)

endValue : QVariant

该属性存储动画的结束值

该属性描述了动画的结束值。

访问函数:

QVariant endValue() const
void setEndValue(const QVariant &value)

另请参阅 startValue 。

startValue : QVariant

该属性用于存储动画的可选起始值

该属性描述了动画的可选起始值。如果省略该属性,或者将空QVariant 赋值为起始值,则动画在开始时将使用当前结束位置。

访问函数:

QVariant startValue() const
void setStartValue(const QVariant &value)

另请参阅 endValue 。

成员函数文档

QVariantAnimation::QVariantAnimation(QObject *parent = nullptr)

创建一个 QVariantAnimation 对象。将 `parent ` 传递给 `QAbstractAnimation` 的构造函数。

[virtual noexcept] QVariantAnimation::~QVariantAnimation()

销毁该动画。

[override virtual protected] bool QVariantAnimation::event(QEvent *event)

重写了:QAbstractAnimation::event(QEvent *event)。

[virtual protected] QVariant QVariantAnimation::interpolated(const QVariant &from, const QVariant &to, qreal progress) const

该虚拟函数返回在坐标点progress 处,对变量from 和to 进行线性插值的结果,通常是一个介于 0 和 1 之间的值。您可以在QVariantAnimation 的子类中重写此函数,以提供自己的插值算法。

请注意,若要使插值功能与返回小于 0 或大于 1 的值的QEasingCurve 兼容(例如QEasingCurve::InBack ),应确保该函数支持外推。若数据类型的语义不允许外推,则该函数应能优雅地处理此情况。

若希望您的类处理 Qt 已支持的类型(支持的类型列表请参见类QVariantAnimation 的描述),应调用该函数的QVariantAnimation 实现。

另请参阅 QEasingCurve 。

QVariant QVariantAnimation::keyValueAt(qreal step) const

返回给定step 的帧值。给定的step 必须在0到1之间。如果step 没有KeyValue ,则返回一个无效的QVariant 。

另请参阅 keyValues() 和setKeyValueAt()。

QVariantAnimation::KeyValues QVariantAnimation::keyValues() const

返回此动画的关键帧。

另请参阅 keyValueAt() 和setKeyValues()。

void QVariantAnimation::setKeyValueAt(qreal step, const QVariant &value)

在给定的step 处,使用给定的value 创建一个关键帧。给定的step 必须在0到1之间。

另请参阅 setKeyValues() 和keyValueAt()。

void QVariantAnimation::setKeyValues(const QVariantAnimation::KeyValues &keyValues)

用给定的keyValues 替换当前的一组关键帧。关键帧的步长必须在0到1之间。

另请参阅 keyValues() 和keyValueAt()。

[override virtual protected] void QVariantAnimation::updateCurrentTime(int)

重写了:QAbstractAnimation::updateCurrentTime(int currentTime)。

[virtual protected] void QVariantAnimation::updateCurrentValue(const QVariant &value)

每当动画的当前值发生变化时,都会调用此虚拟函数。参数 `value ` 表示新的当前值。

基类的实现不执行任何操作。

另请参阅 currentValue 。

[override virtual protected] void QVariantAnimation::updateState(QAbstractAnimation::State newState, QAbstractAnimation::State oldState)

重写了:QAbstractAnimation::updateState(QAbstractAnimation::State newState, QAbstractAnimation::State oldState)。

[signal] void QVariantAnimation::valueChanged(const QVariant &value)

QVariantAnimation 每当当前value 发生变化时,都会发出此信号。

注意: 这是属性currentValue 的通知器 信号。

另请参阅 currentValue 、startValue 和endValue 。

相关的非成员

template <typename T> void qRegisterAnimationInterpolator(QVariant (*func)(const T &, const T &, qreal))

为模板类型T 注册自定义插值器func 。必须在构建动画之前注册该插值器。若要取消注册(并使用默认插值器),请将func 设置为nullptr 。

警告: 为 Qt XML 内置类型(例如int )注册 自定义插值器, 将影响后续基于该类型创建的所有动画。这可能是意想不到的行为。因此,建议在创建所需动画后,将插值器重置为默认值。

注意:此函数是线程安全的。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.