QTimer Class
QTimer 类提供重复定时器和单次定时器。更多
| 头文件： | #include <QTimer> |
| CMake.QTimer | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
| 继承： | QObject |
- 所有成员（包括继承成员）的列表
- 已废弃成员
- QTimer 属于事件类。
属性
|
|
公共功能
| QTimer(QObject *parent = nullptr) | |
| virtual | ~QTimer() |
| QBindable<bool> | bindableActive() |
| QBindable<int> | bindableInterval() |
| QBindable<bool> | bindableSingleShot() |
| QBindable<Qt::TimerType> | bindableTimerType() |
| QMetaObject::Connection | callOnTimeout(Functor &&slot) |
| QMetaObject::Connection | callOnTimeout(const QObject *context, Functor &&slot, Qt::ConnectionType connectionType = Qt::AutoConnection) |
(since 6.8) Qt::TimerId | id() const |
| int | interval() const |
| std::chrono::milliseconds | intervalAsDuration() const |
| bool | isActive() const |
| bool | isSingleShot() const |
| int | remainingTime() const |
| std::chrono::milliseconds | remainingTimeAsDuration() const |
| void | setInterval(int msec) |
| void | setInterval(std::chrono::milliseconds value) |
| void | setSingleShot(bool singleShot) |
| void | setTimerType(Qt::TimerType atype) |
| void | start(std::chrono::milliseconds msec) |
| int | timerId() const |
| Qt::TimerType | timerType() const |
公共插槽
信号
| void | timeout() |
静态公共成员
| void | singleShot(Duration interval, Functor &&functor) |
| void | singleShot(Duration interval, Qt::TimerType timerType, Functor &&functor) |
| void | singleShot(Duration interval, const QObject *context, Functor &&functor) |
| void | singleShot(Duration interval, Qt::TimerType timerType, const QObject *context, Functor &&functor) |
| void | singleShot(std::chrono::nanoseconds nsec, const QObject *receiver, const char *member) |
| void | singleShot(std::chrono::nanoseconds nsec, Qt::TimerType timerType, const QObject *receiver, const char *member) |
重新实现的受保护函数
| virtual void | timerEvent(QTimerEvent *e) override |
详细说明
QTimer 类为定时器提供了一个高级编程接口。要使用它，只需创建一个 QTimer，将其timeout() 信号连接到相应的插槽，然后调用start() 即可。从那时起，它将以固定的间隔发出timeout() 信号。
一秒（1000 毫秒）定时器示例（来自模拟时钟示例）：
QTimer *timer = new QTimer(this); connect(timer, &QTimer::timeout, this, QOverload<>::of(&AnalogClock::update)); timer->start(1000);
此后，每秒都会调用update() 槽。
您可以通过调用setSingleShot(true)，将定时器设置为只超时一次。您还可以使用静态QTimer::singleShot() 函数在指定时间间隔后调用槽：
QTimer::singleShot(200, this, &Foo::updateCaption);
在多线程应用程序中，您可以在任何有事件循环的线程中使用 QTimer。要从非 GUI 线程启动事件循环，请使用QThread::exec() 。Qt 使用定时器的thread affinity 来确定哪个线程将发出timeout() 信号。因此，您必须在其线程中启动和停止定时器；不可能从其他线程启动定时器。
作为一种特例，超时为 0 的 QTimer 会尽快超时，但 0 定时器和其他事件源之间的排序未作规定。零定时器可以用来完成一些工作，同时还能提供快速的用户界面：
QTimer *timer = new QTimer(this); connect(timer, &QTimer::timeout, this, &Foo::processOneThing); timer->start();
此后，processOneThing() 将被反复调用。它的编写方式应使其总是快速返回（通常在处理完一个数据项后），这样 Qt Quick 就能向用户界面传递事件，并在完成所有工作后立即停止定时器。这是 GUI 应用程序中实现繁重工作的传统方式，但由于如今越来越多的平台可以使用多线程，我们预计零毫秒 QTimer 对象将逐渐被QThreads 所取代。
精度和定时器分辨率
定时器的精度取决于底层操作系统和硬件。大多数平台支持 1 毫秒的分辨率，但在许多实际情况下，定时器的精度并不等同于这一分辨率。
精度还取决于timer type 。对于Qt::PreciseTimer ，QTimer 会尽量将精度保持在 1 毫秒。精确的定时器也不会比预期时间提前超时。
对于Qt::CoarseTimer 和Qt::VeryCoarseTimer 类型，QTimer 可能会提前唤醒，但不会超出这些类型的范围：Qt::CoarseTimer 为间隔的 5%，Qt::VeryCoarseTimer 为 500 毫秒。
如果系统繁忙或无法提供所需的精度，所有定时器类型的超时时间都可能晚于预期。在这种超时超限的情况下，Qt 将只发出一次timeout() ，即使多次超时已过，然后将恢复原来的时间间隔。
QTimer 的替代方案
Qt 6.8 引入了QChronoTimer 。这两个类的主要区别在于，QChronoTimer 支持更大的时间间隔范围和更高的精度 (std::chrono::nanoseconds)。QTimer 支持的最大时间间隔为 ±24 天，而QChronoTimer 支持的最大时间间隔为 ±292 年（时间间隔长于std::numeric_limits<int>::max() 时，发生时间间隔溢出的几率较小）。如果只需要毫秒级的分辨率和 ±24 天的范围，可以继续使用 QTimer。
另一种方法是在您的类（必须是QObject 的子类）中重新实现QObject::timerEvent() 方法，并使用以下方法之一：
- 使用QBasicTimer ，这是一个封装了定时器 ID 的轻量级值类。您可以使用QBasicTimer::start() 启动定时器，使用QBasicTimer::stop() 停止定时器。您可以在重新实现的timerEvent() 中处理事件。
- 更低级的方法是直接操作定时器 ID。要启动定时器，请调用QObject::startTimer() 并存储返回的 ID。要停止计时器，请调用QObject::killTimer() 。您可以在重新实现的timerEvent() 中处理事件。这种方法通常比使用QBasicTimer 更麻烦。
使用timerEvent() 的缺点是不支持某些高级功能，如单发定时器和信号。
一些操作系统限制了可使用的定时器数量；Qt 尝试绕过这些限制。
另请参阅 QBasicTimer,QTimerEvent,QObject::timerEvent(),定时器和模拟时钟。
属性文档
[bindable read-only] active : bool
注意： 该属性支持QProperty 绑定。
如果计时器正在运行，则该布尔属性为true ；否则为 false。
[bindable] interval : int
注意： 该属性支持QProperty 绑定。
该属性保存超时间隔（毫秒），默认值为 0。
该属性的默认值为 0。超时间隔为 0 的QTimer 会在窗口系统事件队列中的所有事件都处理完毕后立即超时。
设置运行中的定时器的时间间隔将改变时间间隔，stop() 然后start() 定时器，并获取新的id() 。如果定时器没有运行，则只更改时间间隔。
另请参阅 singleShot 。
[read-only] remainingTime : const int
该属性保存以毫秒为单位的剩余时间
返回定时器超时前的剩余时间（以毫秒为单位）。如果定时器处于非活动状态，则返回值为-1；如果定时器超时，则返回值为 0。
访问函数：
| int | remainingTime() const |
另请参阅 interval 。
[bindable] singleShot : bool
注： 该属性支持QProperty 绑定。
该属性表示定时器是否为单发定时器
单发定时器只触发一次，非单发定时器每interval 毫秒触发一次。
该属性的默认值是false 。
另请参阅 interval 和singleShot()。
[bindable] timerType : Qt::TimerType
注： 该属性支持QProperty 绑定。
控制计时器的精度
该属性的默认值为Qt::CoarseTimer 。
另请参阅 Qt::TimerType 。
成员函数文档
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Qt::TimerType timerType, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, Qt::TimerType timerType, const QObject *context, Functor &&functor)
[static] template <typename Duration, typename Functor> void QTimer::singleShot(Duration interval, const QObject *context, Functor &&functor)
该静态函数在interval 之后调用functor 。
使用该函数非常方便，因为您无需费心建立timerEvent 或本地QTimer 对象。
如果指定了context ，则只有在context 对象在间隔发生之前未被销毁的情况下，才会调用functor 。然后，该函数将运行context 的线程。上下文的线程必须有一个正在运行的 Qt XML 事件循环。
如果functor 是context 的成员函数，则将在对象上调用该函数。
interval 参数可以是int （解释为毫秒计数）或隐式转换为纳秒的std::chrono 类型。
注意： 在 6.8 之前的 Qt 版本中，chrono 重载使用的是 chrono::毫秒，而不是 chrono::纳秒。编译器会自动为您转换，但对于毫秒数极大的情况，转换可能会溢出。
注意：此函数为可重入函数。
另请参阅 start().
[explicit] QTimer::QTimer(QObject *parent = nullptr)
用给定的parent 构建一个定时器。
[virtual noexcept] QTimer::~QTimer()
销毁计时器。
template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(Functor &&slot)
创建定时器timeout() 信号到slot 的连接。返回连接句柄。
提供此方法是为了方便。它等同于调用
注意： 当QT_NO_CONTEXTLESS_CONNECT 已定义时，此重载不可用，请使用使用上下文对象的 callOnTimeout() 重载。
另请参阅 QObject::connect() 和timeout()。
template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(const QObject *context, Functor &&slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
此函数重载 callOnTimeout()。
创建一个从timeout() 信号到slot 的连接，将其置于context 的特定事件循环中，并返回该连接的句柄。
提供此方法是为了方便。它等同于调用
另请参阅 QObject::connect() 和timeout()。
[since 6.8] Qt::TimerId QTimer::id() const
如果定时器正在运行，则返回代表定时器 ID 的Qt::TimerId ；否则返回Qt::TimerId::Invalid 。
此函数在 Qt 6.8 中引入。
另请参阅 Qt::TimerId 。
std::chrono::milliseconds QTimer::intervalAsDuration() const
以std::chrono::milliseconds 对象形式返回该定时器的间隔时间。
另请参阅 interval 。
bool QTimer::isActive() const
如果计时器正在运行，则返回true ；否则返回false 。
注： 属性active 的获取函数。
std::chrono::milliseconds QTimer::remainingTimeAsDuration() const
以std::chrono::milliseconds 对象形式返回该定时器对象的剩余时间。如果该定时器已到期或逾期，则返回值为std::chrono::milliseconds::zero() 。如果找不到剩余时间或定时器未运行，则此函数返回负持续时间。
另请参见 remainingTime()。
[static] void QTimer::singleShot(std::chrono::nanoseconds nsec, const QObject *receiver, const char *member)
这是一个重载函数。
该静态函数在给定时间间隔后调用一个槽。
使用该函数非常方便，因为您无需费心处理timerEvent 或创建本地QTimer 对象。
receiver 是接收对象，member 是槽。时间间隔在 duration 对象nsec 中给出。
注意： 在 6.8 之前的 Qt 版本中，该函数使用的是 chrono::毫秒，而不是 chrono::纳秒。编译器会自动为您转换，但如果毫秒数过大，转换结果可能会溢出。
注意：此函数为可重入函数。
另请参阅 start().
[static] void QTimer::singleShot(std::chrono::nanoseconds nsec, Qt::TimerType timerType, const QObject *receiver, const char *member)
这是一个重载函数。
该静态函数在给定时间间隔后调用一个槽。
使用该函数非常方便，因为您无需费心处理timerEvent 或创建本地QTimer 对象。
receiver 是接收对象，member 是槽。时间间隔在持续时间对象nsec 中给出。timerType 会影响计时器的精度。
注意： 在 6.8 之前的 Qt 版本中，该函数使用的是 chrono::毫秒，而不是 chrono::纳秒。编译器会自动为您进行转换，但如果毫秒数过大，转换结果可能会溢出。
注意：此函数为可重入函数。
另请参阅 start().
[slot] void QTimer::start(int msec)
启动或重启定时器，超时间隔为msec 毫秒。
如果定时器已在运行，则将stopped 并重新启动。这也将改变其id() 。
如果singleShot 为 true，定时器将只被激活一次。这相当于
timer.setInterval(msec); timer.start();
注意： 让事件循环忙于使用零定时器必然会带来麻烦，而且用户界面的行为也会非常不稳定。
[slot] void QTimer::start()
此函数重载 start()。
以interval 中指定的超时时间启动或重启定时器。
如果定时器已在运行，则将stopped 并重新启动。这也将改变id() 。
如果singleShot 为 true，定时器将只启动一次。
void QTimer::start(std::chrono::milliseconds msec)
这是一个重载函数。
启动或重启计时器，超时时间为msec 毫秒。
如果定时器已在运行，则将stopped 并重新启动。这也将改变id() 的值。
如果singleShot 为 true，定时器将只被激活一次。这相当于
timer.setInterval(msec); timer.start();
[slot] void QTimer::stop()
停止计时器。
另请参阅 start().
[private signal] void QTimer::timeout()
计时器超时时发出该信号。
注意： 这是一个私人信号。可以在信号连接中使用，但用户不能发出。
另请参阅 interval 、start() 和stop()。
[override virtual protected] void QTimer::timerEvent(QTimerEvent *e)
重实现：QObject::timerEvent(QTimerEvent *event).
int QTimer::timerId() const
如果定时器正在运行，则返回定时器的 ID；否则返回 -1。
© 2025 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.
