简介：基于Qt自定义的滑动选择器是一套面向Qt开发者的自定义控件示例，用于解决系统自带控件无法满足个性化交互需求的问题，适合有基础Qt编程知识、希望提升自定义控件设计能力的开发者。压缩包共8个文件，大小仅9KB，包含3个cpp源文件、2个h头文件、ui界面文件、pro工程文件及配置文件，cpp和h实现核心逻辑，ui定义界面，pro管理工程结构。该控件支持水平与垂直两种操作模式，可动态切换以适配不同布局；背景色、滑块颜色、边框色均可自定义，最小值和最大值及初始选中值也能灵活配置，滑动时还会触发事件回调，方便获取当前值。通过阅读这份源码，开发者可以掌握自定义控件的绘制流程、鼠标事件处理、布局适配等关键技能，将其迁移到自己的Qt项目中。已有1765人学习下载，适合作为Qt自定义控件入门的实践案例，在实际开发中用于音量调节、进度选择、参数设置等场景。
1. 画一个滑动选择器：当 QSlider 和 QComboBox 都不够用的时候
做设备设置页的时候，我接到一个需求：界面上要放一个档位选择器，五档可选，每档显示文字标签，操作方式是左右滑动，选中项要高亮，皮肤还要跟整个程序统一。第一个反应是直接拖一个 QSlider 上去，但试了半小时就放弃了——QSlider 是连续值控件，要让它“吸附”到固定档位、在每个 tick 下面显示自定义文字、再处理被选中的高亮块，代码量不比自绘少，而且样式跨平台表现不一致。换 QComboBox 更别扭，点击展开再选择，在触屏和遥控器场景下操作成本太高。最后我自己写了一个基于 Qt 自定义控件的滑动选择器，纯 QWidget 子类，paintEvent 绘制全部视觉元素，鼠标事件处理滑动与吸附，前后大概两百行代码。这篇文章把实现思路、坐标换算、交互处理和踩过的坑完整拆一遍，适合需要在 Qt Widgets 项目里做同类控件的开发者参考。
2. 架构与坐标换算：先想清楚数据和像素的关系
动手写代码之前，最值得花时间的是想清楚数据结构、像素坐标和交互状态三者怎么转换。自绘控件最大的优势是完全可控，隐患也在这里——如果一开始坐标体系没理顺，后面每加一个功能都是打补丁。
2.1 为什么不用 QSlider：原生控件的三个边界
QSlider 不是不能用，而是它面向的是“连续值调节”场景，硬要拿来做离散档位选择，会撞上三道墙。
第一道墙是吸附行为。QSlider 有 setSingleStep 和 setPageStep，但它的 handle 仍然可以在两个 tick 之间停留。要强制鼠标释放时自动归位到最近档位，需要自己重写 mouseReleaseEvent，或者监听 valueChanged 之后手动 round 一下，再 setValue 回去——这一下就会触发二次信号，后续逻辑要额外加防抖。第二道墙是自定义文字标注。QSlider 自己只画数值刻度，不负责在每个刻度下方绘制“低/中/高”这类档位文案。把 label 摆到正确位置得在 paintEvent 里自己计算每个 tick 的几何位置，这一块的坐标换算和自绘控件几乎没有区别。第三道墙是样式统一。QSS 能控制 QSlider 的 groove 和 handle，但 sub-page 高亮块的精确宽度、悬停状态下的颜色过渡、禁用态的灰化效果，都需要逐个调，而且 Linux 和 Windows 下渲染效果不完全一致。
所以结论很清楚：与其在 QSlider 的既定结构上做逆向工程，不如直接建一个 QWidget 子类，数据、绘制、交互三层都自己掌控。代码量看起来多了，但每层逻辑都是直的，没有原生的历史包袱。
2.2 类结构与数据模型：数据层和绘制层分离
我的做法是定义一个 SliderSelector 类，对外只暴露三个接口：setItems 设置档位列表、currentIndex 读取当前选中项、setCurrentIndex 外部强制指定选中项。信号只有一个 currentIndexChanged，所有外部逻辑都挂在这个信号上，避免让外部业务直接操作控件内部状态。
class SliderSelector : public QWidget { Q_OBJECT public: explicit SliderSelector(QWidget *parent = nullptr); void setItems(const QStringList &items); int currentIndex() const { return m_currentIndex; } void setCurrentIndex(int index); signals: void currentIndexChanged(int index); protected: void paintEvent(QPaintEvent *event) override; void mousePressEvent(QMouseEvent *event) override; void mouseMoveEvent(QMouseEvent *event) override; void mouseReleaseEvent(QMouseEvent *event) override; void resizeEvent(QResizeEvent *event) override; private: int indexFromPosition(int x) const; QStringList m_items; int m_currentIndex = 0; int m_itemWidth = 80; QPoint m_pressPos; int m_pressIndex = 0; bool m_dragging = false; };这里有几个关键设计。m_items 是数据源，绘制和交互都只认这个列表；m_itemWidth 是每个档位的像素宽度，在 resizeEvent 里根据控件实际宽度重新计算；indexFromPosition 是像素坐标到索引的唯一入口，交互逻辑里所有跟位置有关的计算都通过它，不直接在事件处理里写公式。这样做的目的是让“位置→索引”只有一处实现，排查问题的时候只需要盯这一个函数。
2.3 像素到索引的换算公式：四舍五入而不是截断
这是整个控件最核心的一段逻辑。控件宽度假设是 400 像素，5 个档位，那每个档位占 80 像素。鼠标点击在 x=150 的位置，对应索引是多少？150 除以 80 等于 1.875，不能直接取整为 1，因为 1.875 离索引 2 的中心点（160 像素处）更近，用户看到的效果是“点到了第二个和第三个之间，但更偏向第三个”。
int SliderSelector::indexFromPosition(int x) const { if (m_items.isEmpty()) return 0; int idx = (x + m_itemWidth / 2) / m_itemWidth; return qBound(0, idx, m_items.count() - 1); }计算时先把 x 加上半个档位宽度，再除以档位宽度，这样就把浮点结果四舍五入到了最近的整数索引。qBound 的作用是把结果钳制在有效范围内，防止 x 超出控件边界时算出的索引越界。这个函数会被三处调用：鼠标按下、鼠标移动、鼠标释放，每次调用拿到的都是“当前像素位置最合理的目标档位”，交互逻辑因此非常简单。
2.4 尺寸策略与 resizeEvent 处理
还有一个容易忽略的点是控件尺寸变化。父窗口布局调整、窗口拉伸、DPI 变化都会触发 resizeEvent，如果不重新计算 m_itemWidth，档位会挤在一起或者出现大片留白。常规做法是平均分配：控件宽度除以档位数，最小值限制为 40 像素，防止极端情况下控件被压缩到无法操作。
void SliderSelector::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); m_itemWidth = qMax(40, width() / qMax(1, m_items.count())); }注意这里必须给 item 一个最小宽度。如果窗口被压缩得很窄，每个档位只剩十几像素，鼠标操作精度会急剧下降。在触摸屏上这个值要调更高，通常不少于 60 像素，这是触控目标最小的可达区域。
3. 绘制层：paintEvent 里的轨道、刻度和文本
绘制层的目标是让控件在任何尺寸、任何状态下都保持视觉完整。绘制顺序会直接影响最终效果，一般按照背景、轨道、选中高亮、刻度线、文字这个顺序来，先画的在底层，后画的覆盖在上面。
3.1 paintEvent 的完整绘制流程
void SliderSelector::paintEvent(QPaintEvent *) { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing, true); // 1. 绘制背景 painter.fillRect(rect(), m_bgColor); // 2. 绘制滑动轨道，垂直方向居中，高度 4 像素 int trackY = height() / 2 - 2; painter.fillRect(0, trackY, width(), 4, m_trackColor); // 3. 绘制选中项的高亮块 int left = m_currentIndex * m_itemWidth; painter.fillRect(left, 0, m_itemWidth, height(), m_highlightColor); // 4. 绘制刻度和文字 for (int i = 0; i < m_items.count(); ++i) { int centerX = i * m_itemWidth + m_itemWidth / 2; QPen pen(m_textColor); painter.setPen(pen); painter.drawLine(centerX, height() / 2 - 8, centerX, height() / 2 + 8); QRect textRect(centerX - m_itemWidth / 2, height() / 2 - 34, m_itemWidth, 24); painter.drawText(textRect, Qt::AlignCenter, m_items.at(i)); } }绘制顺序安排有一个讲究：高亮块在轨道之上、文字之下，这样文字永远清晰可读，不会被高亮色盖住。刻度和文字的垂直分布也有意错开——刻度线从轨道中心向上向下各延伸 8 像素，文字则整体抬升到轨道上方 34 像素处，两者不会重叠。第一次写这个控件的时候我把文字直接画在轨道同一行，结果刻度线从文字中间穿过去，视觉上非常乱。
颜色来源是几个成员变量，例如 m_bgColor、m_trackColor、m_highlightColor、m_textColor。我一般用 QColor 成员加默认值，不直接写死在 paintEvent 里，方便后面接主题系统。如果需要更强的定制能力，可以加一个 setHighlightColor 之类的接口，但这是后话，先保证基础功能完整。
3.2 状态驱动绘制：选中态、悬停态与禁用态
控件不能只有一种视觉状态。至少要考虑三种：正常态、选中态、禁用态。选中态通过 m_currentIndex 决定高亮块的位置，这是最基础的。禁用态则需要在 paintEvent 开头做一次判断：
void SliderSelector::paintEvent(QPaintEvent *event) { Q_UNUSED(event); QPainter painter(this); if (!isEnabled()) { painter.fillRect(rect(), m_disabledBgColor); QPen pen(Qt::gray); painter.setPen(pen); // 绘制灰色版本的轨道和文字 // ... return; } // 正常绘制逻辑 }禁用态提前 return，避免和正常逻辑混在一起。如果还想支持鼠标悬停状态，需要配合 setMouseTracking(true)，并在 mouseMoveEvent 里记下当前鼠标位置，paintEvent 里依据位置和高亮块的几何关系决定是否绘制悬停效果。这个功能加在交互层会更顺，第 4 章细说。
3.3 QSS 能做什么、不能做什么
很多第一次写自绘控件的人会问：能不能用 QSS 控制这个控件的颜色？答案是部分能。QWidget 子类通过 setProperty 设置动态属性后，标准 QSS 属性如 background-color、border-radius 是可以生效的，因为这些属性由 QStyle 统一处理。但 QPainter 手动绘制的元素，例如轨道、刻度、文字颜色，QSS 管不到。
this->setProperty("highlightColor", QColor("#3D7EFF")); // QSS 只能控制控件的边框、圆角、背景，不能控制内部轨道和文字实际项目中我的做法是：QSS 负责外层视觉，圆角边框、整体背景、鼠标悬停边框变色这些；内部元素颜色全部由代码成员变量控制。如果你确实想让 QSS 驱动内部元素颜色，一个变通方案是解析动态属性后在 paintEvent 里取值，例如调 property("trackColor").value<QColor>()，但这样写代码会啰嗦不少。我一般只在控件样式需要跟随全局主题切换时才这么做，单机场景直接成员变量就够了。
4. 交互层：鼠标事件、坐标系偏移与索引吸附
交互层的代码量比绘制层小，但逻辑分支更多。鼠标事件的三个处理函数各司其职，按下记录起点、移动计算偏移、释放统一吸附。如果这层处理不当，会表现为拖动不跟手、快速滑动选中错误项、拖出控件边界后状态错乱。
4.1 按下、移动、释放三个事件的分工
鼠标按下时只记录状态，不做任何 UI 更新。鼠标移动时根据当前位置实时计算索引并触发重绘，让用户看到高亮块跟随手指移动。鼠标释放时做最终吸附，并对外发射 currentIndexChanged 信号。
void SliderSelector::mousePressEvent(QMouseEvent *event) { if (event->button() != Qt::LeftButton) return; m_pressPos = event->pos(); m_pressIndex = m_currentIndex; m_dragging = false; } void SliderSelector::mouseMoveEvent(QMouseEvent *event) { if (!(event->buttons() & Qt::LeftButton)) return; int dx = event->pos().x() - m_pressPos.x(); if (qAbs(dx) < 4) return; m_dragging = true; m_currentIndex = indexFromPosition(event->pos().x()); update(); } void SliderSelector::mouseReleaseEvent(QMouseEvent *event) { if (event->button() != Qt::LeftButton) return; m_currentIndex = indexFromPosition(event->pos().x()); update(); if (m_dragging) { emit currentIndexChanged(m_currentIndex); } m_dragging = false; }移动事件里的 4 像素阈值是一个防抖细节。鼠标在点击时难免有几像素的抖动，如果没有任何阈值，按下后稍微动一下就会改变选中状态，用户会觉得控件过于“灵敏”。这个阈值我一般设为 4 像素，触摸屏上会放大到 8 像素，因为指尖的接触面积和抖动幅度都比鼠标大。
按下事件里记录 m_pressIndex 不是每次都用，但它很关键。后续如果要实现“从按下位置开始拖动，而不是瞬间跳转到鼠标当前位置”，需要以 m_pressIndex 为基准，计算相对偏移量来切换索引。如果完全用绝对位置 indexFromPosition 计算，点下后鼠标轻微越过边界就会立刻跳转，体感不好。我最终采用的方案是：按下记录基准点，移动时以相对距离为主要依据，再结合绝对位置做二次校验，两者一致时更新索引。
4.2 点击选择和拖动选择的区分
点击和拖动是两种不同的操作意图，但鼠标事件序列很相似，都需要一套判断规则来区分。按下后马上释放，移动距离不超过 4 像素，属于“点击”；按下后移动超过阈值再释放，属于“拖动”。
这个区分有什么用？纯点击场景可以做成“点哪个选哪个”，按下直接跳转，不需要等释放。拖动场景则必须让高亮块跟手移动，释放时才定格。两种模式都通过 m_dragging 标志来分流——移动超过阈值的瞬间置为 true，后续逻辑按拖动处理；否则按点击处理。
4.3 触摸场景的适配注意点
在触摸屏上跑这个控件，Qt 默认会把触摸事件合成为鼠标事件，所以 mousePressEvent 系列仍能收到消息。但合成事件有一些特性要注意：触摸过程中可能收不到 buttons() 的状态位，某些平台在手指按住不动时会周期性触发 move 事件，导致高亮块抖动。更稳妥的做法是显式开启触摸事件支持，在触摸事件里做同样的一套逻辑。
setAttribute(Qt::WA_AcceptTouchEvents); bool SliderSelector::event(QEvent *event) { if (event->type() == QEvent::TouchBegin || event->type() == QEvent::TouchUpdate || event->type() == QEvent::TouchEnd) { QTouchEvent *touchEvent = static_cast<QTouchEvent *>(event); // 取第一个触摸点，走和鼠标事件相同的换算逻辑 // 注意触摸事件里必须 accept，不能继续传给鼠标合成逻辑 event->accept(); return true; } return QWidget::event(event); }我的经验是：纯鼠标项目直接依赖鼠标事件即可；需要支持触摸的项目，从一开始就把触摸事件处理和鼠标事件处理抽成同一个内部函数，例如 handleDragTo(qreal x)，两个入口都调它，避免同一套逻辑写两遍。触摸和鼠标混用时的最大坑是事件重复——触摸事件如果没有被完全接受，Qt 后续还会合成鼠标事件，导致索引被计算两次。
4.4 释放时的吸附计算
吸附本质上就是释放瞬间调用一次 indexFromPosition，让索引落到最近的档位上。真正的细节在于——释放位置在最后几个像素时，吸附的结果可能与用户视觉预期不一致。例如用户在第三个档位中心稍微偏右释放，按四舍五入规则会选中第四个档位，但用户可能觉得“我明明是停在第三个上面的”。
这个场景没有绝对正确的答案，我的处理逻辑是：如果释放时鼠标位置距离当前索引中心点不超过 itemWidth 的 25%，则保持当前索引不变；否则按照四舍五入吸附到新位置。这个“25% 容差”是调出来的数值，比纯四舍五入的手感柔和不少。
5. 常见问题与避坑：五个高发坑的记录与排查
自绘控件的坑大多集中在坐标计算、事件触发时机、重绘遗漏这几个方面。下面五条是实际开发中复现率最高的问题，每一条都按现象、原因、解决三个步骤记录。
5.1 窗口缩放后档位布局错乱
现象：把控件所在的窗口拉宽，档位之间的间距没有变化，右侧出现大块空白；把窗口缩小，档位互相叠在一起。
原因：resizeEvent 没有被正确触发，或者触发时 m_itemWidth 的计算公式错误。第一种情况通常是控件没有 setAttribute(Qt::WA_ResizeEvent)（实际上 Qt 默认就会触发），第二种情况是档位数目没有参与计算。还有个隐蔽原因：设置 fixedWidth 之后控件宽度不再变化，resize 事件可能不会被调用。
解决：在 resizeEvent 里统一重算 m_itemWidth，并且每次计算都基于 width() 而不是缓存的旧值。同时保证 setItems 之后也调用一次 updateGeometry，让布局系统知道控件尺寸偏好发生了变化。
5.2 快速滑动时选中项与手指位置不一致
现象：鼠标快速从左向右扫过控件，高亮块移动速度跟不上鼠标，最终停下的位置比鼠标位置左移了一到两个档位。
原因：鼠标移动事件的触发频率受系统轮询间隔限制，快速移动时两次事件之间鼠标可能已经跨过好几个档位。如果索引计算依赖事件触发的频率，就会漏掉中间状态。
解决：不要依赖鼠标事件的累计次数计算位置。每次 mouseMoveEvent 都用事件自带的 pos() 做绝对坐标换算，而不是用“上次位置 + 偏移量”的方式累加。累加方式在慢速场景没问题，一快就掉帧。
5.3 释放时索引跳动两个档位
现象：用户停在第二个档位中心，松开鼠标，高亮块跳到第四个档位，完全不符合预期。
原因：mouseReleaseEvent 里没有检查当前鼠标 buttons 状态，导致移动事件和释放事件交错触发；或者 release 事件触发了两次，第一次把索引吸附到新位置，第二次又基于新位置计算了一次。
解决：在 release 里先判断 event->button() 是否等于左键，同时用上面的“25% 容差”策略做吸附，避免最后几像素导致跳变。另外如果发现 release 被触发两次，检查父类是否有事件过滤器吞掉了部分事件。
5.4 高 DPI 屏幕下文字模糊、线条错位
现象：在 Windows 系统开了 150% 缩放的屏幕上，文字边缘发虚，刻度线粗细不均。
原因：绘制时没有启用抗锯齿，文字也没有根据 devicePixelRatio 做缩放。Qt 在高 DPI 下会自动缩放坐标，但个别情况下 painter 的变换矩阵没有应用完整。
解决：paintEvent 开头统一加 painter.setRenderHint(QPainter::Antialiasing, true)。如果文字仍然模糊，在绘制前调用 painter.scale(devicePixelRatioF(), devicePixelRatioF())，并把所有绘制坐标按逻辑像素计算。注意 fillRect 的宽度也要乘以缩放因子，否则轨道会出现一边粗一边细的情况。
5.5 信号重复发射导致业务逻辑执行两次
现象：拖动一次档位，连接了 currentIndexChanged 的业务函数执行了两次甚至三次。
原因：mouseMoveEvent 里每次更新索引都发射一次信号，若业务逻辑里有弹窗或请求，就会累积多次调用。或者释放吸附后的值和移动过程中的最后一个值相同，仍然无条件发射了一次。
解决：统一收口到 release 时发射，移动过程中只做视觉更新不发射信号。同时在发射前比较新旧索引，只有索引实际变化时才发射。这是最稳妥的防抖策略。
6. 进阶：吸附动画、禁用态绘制与自测习惯
基础功能跑通之后，实际项目还差两件事：切换档位时加一点过渡动画，让交互反馈更明确；以及面向不同的使用场景做自测，确认控件在边界情况下不会翻车。吸附动画的做法是用 QVariantAnimation 从当前值插值到目标值，动画过程中持续重绘高亮块位置，视觉上就是高亮块平滑滑动到新档位。动画时长一般控制在 150 到 200 毫秒，太短感知不到，太长会显得拖沓。注意动画过程中还要响应新的鼠标输入，用户中途按下鼠标时应立刻停止动画并切换回手动拖动模式。
禁用态的绘制要在 paintEvent 里单独分流，把所有颜色替换成灰色调，并且不再响应鼠标事件。外部调用 setEnabled(false) 后，Qt 会自动忽略鼠标事件，绘制层只需要根据 isEnabled() 选择颜色方案即可。
自测清单是每次改完这个控件之后必走的一套流程：第一，点击每个档位的正中位置，确认选中项正确；第二，按住拖拉拽跨多个档位，确认释放后索引吸附正确；第三，把窗口宽度拉大缩小，确认档位等宽分布；第四，在 150% DPI 缩放下检查文字清晰度；第五，如果目标平台有触摸屏，实测触摸滑动灵敏度是否需要调整阈值。这套清单看着平淡，但每一条都在前面某个版本里真实出过问题。从那以后我每次写完自定义控件都强制自己走一遍这五条，再交出去给界面集成，省掉了大量来回沟通的成本。希望帮到你。
本文还有配套的精品资源，点击获取
