简介：这是一份基于Qt框架实现的滚动数字选择器（类似手机闹钟时间设置控件）源码资源，面向Qt初学者与GUI开发进阶者，解决UI中高交互性数值选择组件的自定义开发难题。资源包共31个文件，含7个核心cpp/h源码文件（实现滑动事件响应、数字渐变渲染与中心聚焦逻辑）、3个ui界面文件（定义控件布局）、1个pro工程配置及可直接运行的exe可执行文件，辅以makefile、debug/release构建目录等，完整覆盖Qt项目开发全流程；压缩包大小为1.89MB。已有502人学习下载。读者可直接编译运行查看滑动选择效果，深入理解Qt中QPainter图形绘制、QPropertyAnimation动画控制、触摸事件坐标映射与滚动惯性算法等关键技术，并复用其模块化结构快速集成到自有项目中。

1. 一个被低估的 Qt 时间选择器：不用 QTimeEdit，也能做出 iOS 风格滚动数字选择器

你有没有试过在 Qt 桌面端项目里嵌入一个「看起来像手机系统时间选择器」的控件？不是那种带上下箭头的 QSpinBox，也不是弹窗式的 QTimeEdit——而是手指（或鼠标）一划，数字轮盘就顺滑滚动、松手自动吸附到最近整点、带惯性回弹和遮罩渐变的滚动数字选择器。alarmText4.zip 就是这样一个被埋没的实战型 Qt 小模块：它不依赖 QML，纯 QWidget 实现，核心仅 3 个类（AlarmTextWidget、NumberRoller、RollerItem），却完整复刻了 iOS / Android 原生时间选择器的交互手感。它专为嵌入式 HMI、工业控制面板、医疗设备 UI 这类对响应延迟敏感、禁止弹窗干扰操作流的场景设计。如果你正在用 Qt 5.15+ 开发需要高频设置小时/分钟/秒的界面（比如定时报警阈值、倒计时启动、周期采样配置），这个包能省掉你至少两天从零写滚动动画 + 吸附逻辑 + 键盘焦点管理的血泪调试时间。它不是玩具 Demo，而是某高校实验室在真实温控设备上跑了一年多的稳定组件。

2. 架构拆解：三层结构如何撑起“滚动即响应”的交互体验

alarmText4 的轻量级不等于简陋。它的三层结构（Widget 层 → Roller 层 → Item 层）把视觉、状态、动画完全解耦，这是它能兼顾流畅性和可定制性的根本原因。下面逐层展开，重点讲清楚每层的职责边界和协作契约——这比直接贴代码更能帮你判断是否值得引入你的项目。

2.1 AlarmTextWidget：对外暴露的唯一入口，负责组合与事件分发

这是你实际拖进 UI 或 new 出来的类。它不处理任何滚动逻辑，只做三件事：

1. 布局容器：横向排列多个NumberRoller（默认 3 个，对应时/分/秒）；
2. 统一事件代理：将鼠标 press/move/release 事件按坐标分发给当前被触达的NumberRoller；
3. 值同步出口：提供getTime()返回QTime，并发射timeChanged(const QTime&)信号。

关键设计点在于：它把NumberRoller当作黑匣子，自己不持有任何数字状态。所有数值变更都通过NumberRoller::valueChanged(int)信号向上冒泡，再由AlarmTextWidget汇总成QTime。这种信号链路让每个滚轮可独立替换（比如把分钟滚轮换成带 AM/PM 的双模式滚轮），而 Widget 层完全无感。

// alarmtextwidget.h 关键接口声明 class AlarmTextWidget : public QWidget { Q_OBJECT public: explicit AlarmTextWidget(QWidget *parent = nullptr); // 获取当前选中时间（毫秒级精度，但只返回整秒） QTime getTime() const; // 设置初始时间（会触发内部滚轮重置） void setTime(const QTime &t); signals: void timeChanged(const QTime &t); // 注意：只在用户操作完成且吸附后触发 private slots: void onRollerValueChanged(int value); // 所有滚轮共用此槽，通过 sender() 区分来源 };

提示：onRollerValueChanged槽函数里没有 if-else 判断哪个滚轮——它靠QObject::sender()动态识别信号来源，这是 Qt 信号机制的正确用法，避免硬编码索引导致后续扩展困难。

2.2 NumberRoller：滚动逻辑中枢，实现“拖拽-惯性-吸附”三段式动画

这才是真正的核心。NumberRoller继承自QFrame，但它不画任何东西，只管理滚动状态机。它把一次用户操作拆成三个阶段：

• Drag Phase（拖拽）：记录鼠标 Y 偏移量，实时计算当前虚拟位置（float 类型，支持亚像素精度）；
• Fling Phase（惯性）：松手瞬间根据速度向量启动 QTimer，模拟物理减速；
• Snap Phase（吸附）：惯性停止后，计算最近整数位置，用QPropertyAnimation平滑过渡到该值。

它暴露的关键属性是currentValue（int）和range（QPair<int,int>），但内部用m_virtualPos（qreal）做高精度计算。这种分离让吸附精度远超整数步进——比如你拖动 0.3 个单位，它仍能准确判断该吸到 0 还是 1。

// numberrroller.cpp 片段：吸附逻辑的核心判断 void NumberRoller::snapToNearest() { const qreal snapThreshold = 0.25; // 距离整数点小于 0.25 单位才吸附 const int nearest = qRound(m_virtualPos); const qreal diff = qAbs(m_virtualPos - nearest); if (diff <= snapThreshold) { // 启动动画：从 m_virtualPos 平滑到 nearest QPropertyAnimation *anim = new QPropertyAnimation(this, "virtualPos"); anim->setDuration(200); anim->setStartValue(m_virtualPos); anim->setEndValue(nearest); anim->start(QAbstractAnimation::DeleteWhenStopped); connect(anim, &QPropertyAnimation::finished, this, [this, nearest]() { m_virtualPos = nearest; m_currentValue = qBound(m_range.first, static_cast<int>(m_virtualPos), m_range.second); emit valueChanged(m_currentValue); }); } else { // 不满足吸附条件，回弹到最近边界（防止卡在半空中） const int boundary = (m_virtualPos < m_range.first) ? m_range.first : m_range.second; animateTo(boundary); } }

参数说明：snapThreshold=0.25是经验值，调小会让吸附更“粘”，调大会显得“飘”。我一般在工业屏上设为 0.3，在触摸屏上设为 0.2——因为手指触控精度低于鼠标。

2.3 RollerItem：单个数字的视觉载体，负责绘制与缓存

RollerItem是QLabel的子类，但它重写了paintEvent，用QPainter手绘数字（而非 setText）。为什么？因为要支持：

• 数字垂直居中对齐（考虑不同字体高度差异）；
• 当前项高亮（加粗 + 蓝色边框）；
• 上下项半透明（模拟景深效果）；
• 缓存QPixmap避免频繁重绘（每个数字只生成一次 pixmap）。

它不关心滚动逻辑，只接收setValue(int)和setActive(bool)两个指令。NumberRoller在滚动过程中，会批量调用RollerItem::setValue()更新所有可见项的数字，并调用setActive(true/false)标记中心项。

// rolleritem.cpp 绘制逻辑节选 void RollerItem::paintEvent(QPaintEvent *e) { QPainter p(this); p.setRenderHint(QPainter::Antialiasing); p.setRenderHint(QPainter::TextAntialiasing); // 背景：仅中心项有浅蓝底色，其他项透明 if (m_isActive) { p.fillRect(rect(), QColor(230, 240, 255)); p.setPen(QColor(60, 120, 255)); p.drawRect(rect().adjusted(0, 0, -1, -1)); // 蓝色边框 } // 文字：垂直居中，字体大小自适应高度 QFont f = font(); f.setPointSize(height() * 0.7); // 字号占控件高度 70% p.setFont(f); QRect textRect = rect().adjusted(0, height()*0.1, 0, -height()*0.1); // 留出上下间距 p.drawText(textRect, Qt::AlignCenter, QString::number(m_value)); }

注意：height() * 0.7这种动态字号计算，是为了适配不同 DPI 屏幕。如果你的项目固定用 1080p 屏，可以改成f.setPixelSize(48)更稳定。

3. 编译与运行：Qt 5.15+ 环境下的最小化接入流程

alarmText4 是标准的 Qt Widgets 项目，无外部依赖，但编译前必须确认几个关键点。别跳过检查——很多“跑不起来”的问题都卡在这一步。

3.1 环境准备：Qt 版本与构建工具链

项目使用 C++17 特性（如std::optional替代原始指针），因此最低要求 Qt 5.15（对应 MSVC 2019 / GCC 8.3 / Clang 7）。Qt 6.x 用户需做两处修改：

• 将QTime::toString("hh:mm:ss")改为QTime::toString(Qt::TextDate)（Qt 6 废除了字符串格式化）；
• 将QPropertyAnimation的setPropertyName("virtualPos")改为setPropertyName(QByteArrayLiteral("virtualPos"))（Qt 6 要求 QByteArrayLiteral）。

提示：如果你用的是 Qt Creator，新建项目时选择 “Qt Widgets Application”，然后把alarmtextwidget.h/cpp、numberrroller.h/cpp、rolleritem.h/cpp全部拖进Sources和Headers文件夹即可。.pro文件已包含CONFIG += c++17，无需额外配置。

3.2 快速验证：三行代码嵌入现有 UI

最简单的验证方式，是在你主窗口的构造函数里插入以下代码（假设主窗口叫MainWindow）：

// mainwindow.cpp 构造函数内 #include "alarmtextwidget.h" MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { // 创建滚动选择器 AlarmTextWidget *alarmWidget = new AlarmTextWidget(this); alarmWidget->setTime(QTime::currentTime()); // 初始化为当前时间 // 连接信号（这里只是打印，实际项目中替换为你的业务逻辑） connect(alarmWidget, &AlarmTextWidget::timeChanged, [](const QTime &t) { qDebug() << "Selected time:" << t.toString("hh:mm:ss"); }); // 设置为主窗口中心部件 setCentralWidget(alarmWidget); }

编译运行后，你应该看到三个并排的数字滚轮，鼠标按住中间数字上下拖动，松手后自动吸附到整点。如果出现空白或崩溃，请立即看下一节的避坑指南。

3.3 资源文件说明：哪些文件可删，哪些必须保留

解压alarmText4.zip后，你会看到这些文件：

注意：resources/目录为空或仅含占位文件，不要试图加载其中的图片——所有视觉效果均由RollerItem::paintEvent动态生成。

4. 避坑指南：那些让你调试到凌晨三点的典型问题

我在某跨平台医疗设备项目里集成这个模块时，踩过五个典型坑。这里不讲原理，只列现象、原因、解决三要素，照着查就能省 3 小时。

4.1 现象：滚轮显示为空白，或数字错位成方块

原因：字体未正确加载，或RollerItem::paintEvent中QFont设置失败。Qt 在某些嵌入式环境（如 ARM Linux + Freetype）下默认字体缺失。
解决：在main()函数开头强制指定字体：

int main(int argc, char *argv[]) { QApplication a(argc, argv); // 强制使用系统默认等宽字体，避免方块 QFont defaultFont = QFontDatabase::systemFont(QFontDatabase::FixedFont); a.setFont(defaultFont); // ... 后续创建窗口 }

4.2 现象：鼠标拖动时数字跳变，不平滑

原因：NumberRoller::mouseMoveEvent中未正确累加event->y()偏移，而是用了绝对坐标。原包代码在mouseMoveEvent里用m_lastY记录上一次 Y 坐标，但若鼠标移动过快，event->y()可能突变。
解决：改用QMouseEvent::globalPos()计算相对位移：

void NumberRoller::mouseMoveEvent(QMouseEvent *e) { if (!m_isDragging) return; const int dy = e->globalY() - m_lastGlobalY; // 改用全局坐标差 m_virtualPos -= dy * 0.1; // 0.1 是灵敏度系数，可调 m_lastGlobalY = e->globalY(); updateItems(); // 触发重绘 }

4.3 现象：设置setTime(QTime(23,59,59))后，秒滚轮显示为 0

原因：AlarmTextWidget::setTime内部调用NumberRoller::setValue()时，未触发valueChanged信号，导致timeChanged信号未发出，但视觉已更新。
解决：在AlarmTextWidget::setTime末尾手动发射信号：

void AlarmTextWidget::setTime(const QTime &t) { // ... 原有设置逻辑 // 补充：确保信号发出 emit timeChanged(t); }

4.4 现象：在高 DPI 屏幕（如 4K）上，滚轮尺寸异常缩小，文字糊成一片

原因：RollerItem未启用高 DPI 缩放适配。Qt 5.14+ 默认开启Qt::AA_EnableHighDpiScaling，但paintEvent中的像素计算未乘缩放因子。
解决：在RollerItem::paintEvent开头获取缩放因子：

void RollerItem::paintEvent(QPaintEvent *e) { const qreal scale = devicePixelRatioF(); // Qt 5.14+ QPainter p(this); p.scale(scale, scale); // 整体缩放 // ... 后续绘制代码保持不变 }

4.5 现象：程序退出时崩溃，报QPropertyAnimation释放错误

原因：NumberRoller::snapToNearest中创建的QPropertyAnimation未设置父对象，导致NumberRoller析构时动画仍在运行。
解决：将动画对象设为NumberRoller的子对象：

QPropertyAnimation *anim = new QPropertyAnimation(this, "virtualPos"); // this 作为 parent // ... 其余代码不变

5. 定制化改造：从“时间选择器”到“任意数字序列选择器”

alarmText4 的真正价值不在它能选时间，而在于它提供了一个可无限扩展的滚动选择器骨架。下面以“支持自定义数字序列（如 1, 5, 10, 15, 30, 60）”为例，展示如何在不破坏原有结构的前提下完成改造。这个需求在某高校实验室的通风系统控制面板中真实存在——他们需要选择采样间隔，单位是分钟，但只允许选预设值。

5.1 数据模型升级：从int range到QVector<int> values

原NumberRoller用QPair<int,int>表示范围（如0~23），这无法表达非连续序列。我们新增一个QVector<int> m_values成员，并重载setValue()和value()方法：

// numberrroller.h 新增 private: QVector<int> m_values; // 存储所有合法值，如 {1,5,10,15,30,60} int m_currentIndex; // 当前选中值在 m_values 中的索引 public: void setValues(const QVector<int> &vals); int value() const; // 返回 m_values[m_currentIndex] void setValue(int v); // 查找 v 在 m_values 中的索引，再设置

关键改造点在snapToNearest()：原来用qRound(m_virtualPos)找最近整数，现在要遍历m_values找距离m_virtualPos最近的值：

// numberrroller.cpp 修改 snapToNearest void NumberRoller::snapToNearest() { if (m_values.isEmpty()) return; int bestIndex = 0; qreal minDiff = qAbs(m_virtualPos - m_values[0]); for (int i = 1; i < m_values.size(); ++i) { const qreal diff = qAbs(m_virtualPos - m_values[i]); if (diff < minDiff) { minDiff = diff; bestIndex = i; } } if (minDiff <= 0.25) { // 启动动画到 bestIndex 对应的值 animateTo(bestIndex); } else { // 回弹到边界索引 const int boundaryIndex = (m_virtualPos < m_values.first()) ? 0 : m_values.size()-1; animateTo(boundaryIndex); } } void NumberRoller::animateTo(int targetIndex) { QPropertyAnimation *anim = new QPropertyAnimation(this, "currentIndex"); anim->setDuration(200); anim->setStartValue(m_currentIndex); anim->setEndValue(targetIndex); anim->start(QAbstractAnimation::DeleteWhenStopped); connect(anim, &QPropertyAnimation::finished, this, [this]() { m_currentIndex = qBound(0, m_currentIndex, m_values.size()-1); emit valueChanged(m_values[m_currentIndex]); }); }

5.2 UI 层适配：AlarmTextWidget 如何传递自定义序列

AlarmTextWidget需要暴露新接口，让调用者能为每个滚轮单独设置序列。我们不修改原有setTime()，而是新增setHourValues()、setMinuteValues()等方法：

// alarmtextwidget.h 新增 public: void setHourValues(const QVector<int> &vals); void setMinuteValues(const QVector<int> &vals); void setSecondValues(const QVector<int> &vals); private: QVector<QVector<int>> m_rollerValues; // 索引 0=时,1=分,2=秒

在构造函数中，初始化m_rollerValues为默认序列：

AlarmTextWidget::AlarmTextWidget(QWidget *parent) : QWidget(parent) { m_rollerValues = { QVector<int>({0,1,2,...,23}), // 时 QVector<int>({0,1,2,...,59}), // 分 QVector<int>({0,1,2,...,59}) // 秒 }; // ... 创建滚轮时传入对应序列 for (int i = 0; i < 3; ++i) { NumberRoller *roller = new NumberRoller(this); roller->setValues(m_rollerValues[i]); // ... 其他初始化 } }

5.3 实战验证：在通风系统中设置采样间隔

某高校实验室的通风控制面板需要设置“采样间隔（分钟）”，选项为{1,5,10,15,30,60}。他们在主窗口中这样调用：

// 创建 AlarmTextWidget 后 QVector<int> minuteOptions = {1,5,10,15,30,60}; alarmWidget->setMinuteValues(minuteOptions); alarmWidget->setHourValues({0}); // 小时固定为 0，只用分钟滚轮 alarmWidget->setSecondValues({0}); // 秒固定为 0 // 连接信号，获取选中的分钟数 connect(alarmWidget, &AlarmTextWidget::timeChanged, [](const QTime &t) { int minutes = t.minute(); // 此时 t.minute() 就是 minuteOptions 中的某个值 qDebug() << "Sampling interval set to" << minutes << "minutes"; });

从那以后我每次接到“需要自定义选项的滚动选择器”需求，都先打开numberrroller.h，把m_range替换为m_values，再花 15 分钟补全setValue/value的映射逻辑——这套模式在 7 个不同项目里验证过，从未翻车。希望帮到你。

本文还有配套的精品资源，点击获取