当前位置：首页 > news >正文

Qt 倒计时功能从入门到弃坑：一个老码农的实战笔记

news 2026/4/18 2:42:25

Qt 倒计时功能从入门到弃坑：一个老码农的实战笔记

事情是这样的，上周接到一个需求：做个倒计时功能，要能传秒数、能弹窗、能触发信号，还得在多个地方同时用。我一听，这不挺简单吗？结果写着写着发现坑还不少…

先说说为啥要自己写

Qt 自带QTimer，但你要做个像样的倒计时，光靠它还真不够。比如：

定时器会有累积误差（别问我是怎么发现的）
需要同时管理多个倒计时实例
还得支持 QML 绑定（产品经理临时加的）

所以干脆封装一个，一劳永逸。

最终成品长这样

头文件countdowntimer.h：

#ifndefCOUNTDOWNTIMER_H#defineCOUNTDOWNTIMER_H#include<QObject>#include<QTimer>#include<QElapsedTimer>#include<QString>classCountdownTimer:publicQObject{Q_OBJECTQ_PROPERTY(intremainingSeconds READ remainingSeconds NOTIFY remainingSecondsChanged)public:explicitCountdownTimer(QObject*parent=nullptr);// 开始倒计时// seconds: 倒计时秒数（必须 > 0）// finishMessage: 倒计时结束时的弹窗文本// showPopup: 是否显示倒计时结束弹窗voidstart(intseconds,constQString&finishMessage,boolshowPopup=true);// 停止倒计时voidstop();boolisActive()const;intremainingSeconds()const;signals:voidfinished();// 倒计时结束信号voidtick(intsecondsLeft);// 每秒触发一次voidremainingSecondsChanged();// 剩余秒数变化信号privateslots:voidonTimeout();private:QTimer m_timer;QElapsedTimer m_elapsedTimer;intm_totalSeconds;intm_lastRemaining;QString m_finishMessage;boolm_showPopup;boolm_isActive;};#endif

实现文件countdowntimer.cpp：

#include"countdowntimer.h"#include<QMessageBox>#include<QApplication>CountdownTimer::CountdownTimer(QObject*parent):QObject(parent),m_totalSeconds(0),m_lastRemaining(0),m_showPopup(true),m_isActive(false){connect(&m_timer,&QTimer::timeout,this,&CountdownTimer::onTimeout);m_timer.setSingleShot(false);m_timer.setInterval(1000);}voidCountdownTimer::start(intseconds,constQString&finishMessage,boolshowPopup){if(seconds<=0){qWarning()<<"CountdownTimer: seconds must be > 0";return;}if(m_isActive){stop();}m_totalSeconds=seconds;m_finishMessage=finishMessage;m_showPopup=showPopup;m_isActive=true;m_elapsedTimer.start();m_lastRemaining=seconds;emitremainingSecondsChanged();emittick(seconds);if(seconds==0){onTimeout();}else{m_timer.start();}}voidCountdownTimer::stop(){if(!m_isActive)return;m_timer.stop();m_isActive=false;m_totalSeconds=0;m_finishMessage.clear();}boolCountdownTimer::isActive()const{returnm_isActive;}intCountdownTimer::remainingSeconds()const{if(!m_isActive)return0;qint64 elapsedMs=m_elapsedTimer.elapsed();intremaining=m_totalSeconds-static_cast<int>(elapsedMs/1000);returnremaining<0?0:remaining;}voidCountdownTimer::onTimeout(){if(!m_isActive)return;qint64 elapsedMs=m_elapsedTimer.elapsed();intremaining=m_totalSeconds-static_cast<int>(elapsedMs/1000);if(remaining<=0){m_timer.stop();m_isActive=false;emitfinished();if(m_showPopup&&!m_finishMessage.isEmpty()){QMessageBox::information(qApp->activeWindow(),tr("倒计时结束"),m_finishMessage);}m_totalSeconds=0;m_finishMessage.clear();}else{if(remaining!=m_lastRemaining){m_lastRemaining=remaining;emitremainingSecondsChanged();emittick(remaining);}}}

用起来啥感觉

基础用法

CountdownTimer*timer=newCountdownTimer(this);// 60秒倒计时，结束弹窗"休息一下"timer->start(60,"休息一下",true);// 结束干点别的connect(timer,&CountdownTimer::finished,this,&MyClass::onTimeout);// 实时显示剩余时间connect(timer,&CountdownTimer::tick,[](intsecondsLeft){qDebug()<<"还剩"<<secondsLeft<<"秒";});

多个倒计时同时跑

// 支付倒计时（15分钟，弹窗提醒）autopaymentTimer=newCountdownTimer(this);paymentTimer->start(900,"支付超时，订单已取消",true);// 验证码倒计时（60秒，不弹窗，只更新按钮文字）autocodeTimer=newCountdownTimer(this);codeTimer->start(60,"",false);connect(codeTimer,&CountdownTimer::tick,[](intleft){ui->getCodeBtn->setText(QString("重新获取(%1)").arg(left));});

踩过的坑和经验

1. 定时器误差问题

QTimer不是精确定时器，累积误差会越来越大。用QElapsedTimer记录实际经过的时间，每次根据实际耗时计算剩余秒数，完美解决。

// 错误做法：依赖定时器次数累加m_remaining--;if(m_remaining<=0){/* 结束 */}// 正确做法：根据实际耗时计算qint64 elapsedMs=m_elapsedTimer.elapsed();intremaining=m_totalSeconds-(elapsedMs/1000);

2. 弹窗的父窗口传什么

// 传 nullptr：弹窗独立，可能不在最前QMessageBox::information(nullptr,"提示","时间到");// 传 activeWindow：跟随当前窗口，体验更好QMessageBox::information(qApp->activeWindow(),"提示","时间到");// 最佳实践：允许调用方传入父窗口voidstart(intseconds,constQString&msg,boolshowPopup,QWidget*parent=nullptr);

3. 信号别乱用

// tick：每秒都触发，适合刷新UIconnect(timer,&CountdownTimer::tick,ui->label,&QLabel::setNum);// remainingSecondsChanged：值变化才触发，适合QML绑定// QML里可以直接写 timer.remainingSeconds// finished：只触发一次，适合业务逻辑connect(timer,&CountdownTimer::finished,this,&Order::cancel);

Q_PROPERTY 是什么鬼

很多新手看到这个一脸懵，简单说：

Q_PROPERTY(intremainingSeconds READ remainingSeconds NOTIFY remainingSecondsChanged)

这句话的意思是：我把remainingSeconds这个属性暴露给 Qt 的元对象系统了。

有啥用？

QML 可以直接绑定这个属性，值变了 UI 自动更新
Qt Designer 里能显示和编辑
可以配合 QPropertyAnimation 做动画

什么时候用？

要做 QML 界面 → 必须用
纯 C++ Widgets 项目 → 可以不用

我加这个是考虑到产品经理随时可能让上 QML，提前写好省的回头改。

几个真实使用场景

场景：考试系统倒计时

classExamSystem:publicQWidget{CountdownTimer*m_timer;voidstartExam(){m_timer=newCountdownTimer(this);m_timer->start(3600,"考试时间到，系统自动交卷",true);// 实时显示connect(m_timer,&CountdownTimer::tick,this,&ExamSystem::updateDisplay);// 自动交卷connect(m_timer,&CountdownTimer::finished,this,&ExamSystem::autoSubmit);// 每分钟自动保存connect(m_timer,&CountdownTimer::remainingSecondsChanged,[this](){if(m_timer->remainingSeconds()%60==0){saveProgress();}});}};

场景：游戏技能冷却

classSkillCoolDown{QMap<QString,CountdownTimer*>m_cooldowns;voidcastSkill(constQString&skillName,intcooldownSec){if(isOnCooldown(skillName)){QMessageBox::warning(nullptr,"提示","技能还在冷却中");return;}autotimer=newCountdownTimer(this);timer->start(cooldownSec,"",false);m_cooldowns[skillName]=timer;// 更新UI按钮文字connect(timer,&CountdownTimer::tick,[=](intleft){updateButtonText(skillName,left);});connect(timer,&CountdownTimer::finished,[=](){m_cooldowns.remove(skillName);enableButton(skillName);});}};