Qt QWidget自绘实现滑动页签下划线动画实战

1. 这个效果到底难在哪：从一次桌面端项目说起

前阵子接了个桌面端的即时通讯类工具开发，UI 那边给的设计稿里，主界面左侧是一列纵向排列的功能页签——消息、联系人、群组、收藏之类，每个页签下面带一条会跟着选中项滑动的下划线。设计稿看着挺清爽，真动手写的时候才发现，这条线不是随便画一条就完事：它得跟着当前选中的页签走，切换时要有平滑的位移动画，鼠标悬停和选中状态下的颜色、粗细还不一样，窗口拉伸时位置不能错位，页签数量动态增减时也得自动适配。

这类“页签下划线跟随”的效果，在移动端和 Web 前端里几乎是标配，Flutter 有 TabBar 的 indicator，Android 有 TabLayout 的 custom indicator，CSS 里更是几行就能搞定。但放到 Qt 桌面端，尤其是用 QWidget 体系手写的时候，官方并没有现成的控件直接给你这个能力。QTabBar 自带的指示器样式受限于 QSS，想做一条独立滑动、带缓动动画的下划线，基本得自己接管绘制和动画。

所以这篇就把我当时踩过的路完整复盘一遍：怎么用 QWidget 自绘实现一条会滑动的下划线，怎么把动画做得不生硬，怎么处理悬停、选中、禁用三种状态的视觉差异，以及窗口缩放和动态增删页签时那些容易翻车的细节。内容偏实战，代码给的是可直接编译运行的思路，适合已经会写基础 Qt 界面、想把手写控件做扎实的开发者参考。哪怕你用的是 QML，思路也是通的，只是实现手段换成 Canvas 或 Rectangle 加动画而已。

2. 整体方案怎么选：三种实现路径的取舍

动手之前先把方案定下来，不然写到一半发现路子不对，返工成本很高。围绕“页签下划线跟随”这个需求，Qt 里常见的有三条路，我逐个说下各自的适用边界。

2.1 方案一：QSS 硬凑 QTabBar 指示器

最省事的想法是直接用 QTabBar，然后靠 QSS 的QTabBar::tab:selected去改边框或者背景，模拟出一条下划线。这条路我试过，能出效果，但问题很明显：QSS 画出来的“线”本质上是 tab 自身边框的一部分，它没法脱离 tab 独立存在，也就没法做跨 tab 的滑动动画。你切换页签时，线是瞬间从旧位置消失、在新位置出现的，中间没有过渡。设计稿要的那种“滑过去”的质感，QSS 给不了。

另外 QSS 对 tab 尺寸的控制也比较死，想让下划线比 tab 窄一点、居中显示，得靠 padding 和 border 的组合去凑，稍微改个字号或者换套皮肤就崩。所以这条路只适合“静态下划线、不要动画、样式简单”的场景，一旦设计要求动起来，就得放弃。

2.2 方案二：继承 QTabBar 重写 paintEvent

第二条路是继承 QTabBar，重写它的paintEvent，在画完原生 tab 之后，自己再画一条下划线。这个方案比 QSS 灵活，因为绘制权在你手里，线的位置、宽度、颜色都能算。但它有个绕不开的坑：QTabBar 内部的 tab 布局计算是私有的，你想精确知道每个 tab 的矩形区域，只能靠tabRect(index)这个公开接口去拿。这个接口本身没问题，问题是当 tab 数量多到需要滚动、或者样式表改了 tab 间距时，tabRect返回的值和你肉眼看到的位置偶尔会对不上，尤其是配合 QSS 使用的时候。

而且重写 QTabBar 意味着你要把原生那一套绘制逻辑也接管过来，否则原生 tab 和你的下划线会打架。工作量不小，收益却一般。我个人的判断是：如果你整个项目已经在用 QTabBar 且不想大改，这条路可以走；如果是新写的界面，没必要。

2.3 方案三：纯 QWidget 自绘 + 属性动画

最后我选的是第三条路：完全不用 QTabBar，自己用 QWidget 搭一套页签栏。每个页签是一个子 QWidget（或者干脆不建子控件，全部在一个父控件里自绘），下划线作为父控件绘制层的一部分，位置由一个qreal类型的偏移量控制，切换时用QPropertyAnimation驱动这个偏移量做插值，paintEvent里根据当前偏移量把线画出来。

这个方案的好处是彻底解耦：页签的布局、下划线的位置、动画的节奏，全部由我自己算，不受任何原生控件私有逻辑的干扰。窗口缩放时我重算一遍布局就行，动态增删页签时我更新一下页签列表和总宽度，下划线自动跟着走。代价是要自己处理鼠标事件、悬停检测、点击命中判断这些原本 QTabBar 帮你做的事。但说实话，这些逻辑加起来也就百来行，换来的是完全可控的视觉效果，值。

下面这张表把三个方案的核心差异列一下，方便你按自己的项目情况对号入座。

选型这件事没有绝对的对错，关键看你的约束。如果项目里已经有一堆 QTabBar 且不想动，那就走方案二；如果是新起的界面，又想要设计稿那种顺滑感，方案三是最省心的。

3. 核心细节拆解：下划线的位置、宽度与动画节奏

方案定了，接下来把几个关键细节掰开说。这些细节决定了最终效果是“能用”还是“好看”，差别往往就在几个像素和几十毫秒之间。

3.1 下划线的位置怎么算才不跑偏

下划线的水平位置，本质上是当前选中页签的中心点减去线宽的一半。听起来简单，但有几个坑。

第一个坑是页签的坐标系。如果你的页签是父控件的子 QWidget，那tab->geometry()返回的是相对父控件的坐标，直接用没问题。但如果你像我一样选择全部自绘，那页签的矩形是你自己算出来的，得保证这套计算和paintEvent里画文字用的是同一套数据，否则文字和线会对不齐。我的做法是抽一个recalcLayout()函数，把所有页签的矩形算好存进一个QVector<QRect>，绘制、命中检测、下划线定位全部读这个 vector，单一数据源，不会出现两处算法不一致的情况。

第二个坑是线的宽度。设计稿通常要求下划线比页签文字略宽一点，比如文字宽 40px，线宽给到 48px，视觉上更稳。但如果你直接按页签矩形宽度来画，页签之间的间距会让线看起来太宽。我的处理是：线宽 = min(页签宽度 × 0.7, 一个上限值)，同时保证不小于文字宽度。这样窄页签和宽页签下都不会难看。

第三个坑是垂直位置。下划线一般贴在页签底部，但不要真的贴到最底边，留 2 到 4 个像素的呼吸空间会精致很多。这个值我建议做成常量，方便统一调整。

3.2 动画为什么不能线性插值

位置算对了，接下来是动画。很多人第一版会用线性插值（QEasingCurve::Linear），结果就是线滑过去的时候匀速运动，看起来机械、生硬，像机器人走路。真实世界里物体加速和减速是有过程的，所以缓动曲线要用QEasingCurve::OutCubic或者InOutQuad这类先快后慢或两头慢中间快的类型。

我实测下来，OutCubic在页签切换这个场景里最舒服：起步快，快到目标位置时自然减速，有种“吸附”过去的感觉。动画时长控制在 180 到 220 毫秒之间，太短了看不出动画，太长了显得拖沓。我最后定的是 200ms，配合 OutCubic，切换时的观感很顺。

还有一个细节：如果用户在动画还没结束时又点了另一个页签，动画要能被打断并从当前位置重新开始，而不是排队或者跳变。QPropertyAnimation 默认的行为是重新设置 startValue 和 endValue 后从头播，但 startValue 如果写死成旧位置就会跳。正确做法是每次启动动画前，把 startValue 设为下划线当前的实时偏移量（也就是动画对象的当前值），这样打断时是平滑接续的。

3.3 悬停、选中、禁用三种状态怎么区分

页签的视觉状态不止“选中”一种。鼠标悬停时要有反馈，禁用时要有区分，这些都得在下划线之外单独处理。

我的做法是：下划线只负责表达“选中”，悬停反馈用页签文字颜色的变化来实现，禁用态则把文字颜色调灰、同时屏蔽点击。这样下划线始终只有一条，视觉焦点清晰，不会出现“悬停也画一条线、选中又画一条线”的混乱。

具体颜色上，选中态文字用主色（比如深蓝），悬停态用主色的浅一档，普通态用中性灰，禁用态用更浅的灰。下划线颜色跟选中态文字保持一致，这样视觉上是一体的。这些颜色我建议抽成常量或者放进一个主题结构体里，方便以后换肤。

提示：悬停检测不要用 enterEvent/leaveEvent 逐个页签去挂，页签多了事件管理很乱。直接在父控件的 mouseMoveEvent 里根据鼠标坐标和页签矩形做命中判断，配合 setMouseTracking(true)，一个函数搞定所有页签的悬停状态。

4. 动手实现：从零写出可滑动的页签下划线

前面把思路和细节都过了一遍，这一节直接上代码。我会按“数据结构 → 布局计算 → 绘制 → 事件 → 动画”的顺序来写，每一步都说明为什么这么写。代码基于 QWidget，Qt5 和 Qt6 都能跑，差异我会标注。

4.1 数据结构与类骨架

先定义页签栏这个类。核心成员包括：页签文本列表、每个页签的矩形、当前选中索引、悬停索引、下划线当前偏移量、动画对象。

class TabBarWidget : public QWidget { Q_OBJECT public: explicit TabBarWidget(QWidget *parent = nullptr); void addTab(const QString &text); void removeTab(int index); void setCurrentIndex(int index); int currentIndex() const { return m_currentIndex; } protected: void paintEvent(QPaintEvent *event) override; void mousePressEvent(QMouseEvent *event) override; void mouseMoveEvent(QMouseEvent *event) override; void leaveEvent(QEvent *event) override; void resizeEvent(QResizeEvent *event) override; private: void recalcLayout(); qreal indicatorTargetX(int index) const; QStringList m_tabs; QVector<QRect> m_tabRects; int m_currentIndex = -1; int m_hoverIndex = -1; qreal m_indicatorX = 0.0; QPropertyAnimation *m_anim = nullptr; };

这里m_indicatorX是下划线左边缘的 x 坐标，用qreal是为了动画插值平滑。m_tabRects缓存每个页签的矩形，避免每次绘制都重算。动画对象在构造函数里创建，绑定到m_indicatorX这个属性上——注意，m_indicatorX得是 Q_PROPERTY 才能被 QPropertyAnimation 驱动，或者用QPropertyAnimation配合 lambda 的valueChanged信号手动更新。我这里为了简洁，用后者，下面会写。

4.2 布局计算：recalcLayout 的写法

recalcLayout负责根据当前控件宽度和页签数量，算出每个页签的矩形。这里我采用等宽布局，每个页签宽度相同，简单且视觉整齐。如果你的页签文字长短差异很大，也可以改成按文字宽度加 padding 来算，思路一样。

void TabBarWidget::recalcLayout() { m_tabRects.clear(); if (m_tabs.isEmpty()) return; const int count = m_tabs.size(); const int totalWidth = width(); const int tabWidth = totalWidth / count; const int tabHeight = height(); for (int i = 0; i < count; ++i) { int x = i * tabWidth; // 最后一个页签吃掉除不尽的余数，避免右侧留缝 int w = (i == count - 1) ? (totalWidth - x) : tabWidth; m_tabRects.append(QRect(x, 0, w, tabHeight)); } // 布局变了，下划线位置也要跟着更新 if (m_currentIndex >= 0 && m_currentIndex < count) { m_indicatorX = indicatorTargetX(m_currentIndex); } }

注意最后那个“余数处理”。如果控件宽度是 500，页签 3 个，500/3 是 166 余 2，前两个页签各 166，最后一个如果也 166，右边就会空 2 像素。让最后一个页签宽度等于剩余宽度，就能严丝合缝铺满。这个细节在窗口拉伸时尤其重要，不然右边会有一条细缝，很扎眼。

indicatorTargetX负责算下划线的目标位置：

qreal TabBarWidget::indicatorTargetX(int index) const { if (index < 0 || index >= m_tabRects.size()) return 0.0; const QRect &r = m_tabRects[index]; const qreal lineWidth = qMin(r.width() * 0.7, 60.0); return r.center().x() - lineWidth / 2.0; }

线宽取页签宽度的 70%，但不超过 60 像素。这样宽页签下线不会太夸张，窄页签下线也不会太短。60 这个上限是我根据常见字号（14px 左右）定的，你可以按自己的设计稿调。

4.3 绘制：paintEvent 里画文字和线

绘制分两层：先画所有页签的文字，再画下划线。下划线画在最后，保证它压在所有文字之上（虽然位置不重叠，但逻辑上更清晰）。

void TabBarWidget::paintEvent(QPaintEvent *) { QPainter p(this); p.setRenderHint(QPainter::Antialiasing, true); QFont f = font(); f.setPixelSize(14); p.setFont(f); // 画页签文字 for (int i = 0; i < m_tabRects.size(); ++i) { QColor textColor; if (i == m_currentIndex) { textColor = QColor(0x1E, 0x6F, 0xD9); // 选中：主色 } else if (i == m_hoverIndex) { textColor = QColor(0x5A, 0x9B, 0xE8); // 悬停：浅主色 } else { textColor = QColor(0x66, 0x66, 0x66); // 普通：中性灰 } p.setPen(textColor); p.drawText(m_tabRects[i], Qt::AlignCenter, m_tabs[i]); } // 画下划线 if (m_currentIndex >= 0 && m_currentIndex < m_tabRects.size()) { const QRect &r = m_tabRects[m_currentIndex]; const qreal lineWidth = qMin(r.width() * 0.7, 60.0); const qreal lineHeight = 3.0; const qreal bottomMargin = 4.0; QRectF lineRect(m_indicatorX, height() - lineHeight - bottomMargin, lineWidth, lineHeight); p.setPen(Qt::NoPen); p.setBrush(QColor(0x1E, 0x6F, 0xD9)); p.drawRoundedRect(lineRect, 1.5, 1.5); } }

几个细节值得说。第一，drawRoundedRect的圆角半径取线高的一半，这样线两端是半圆，比直角柔和。第二，线高 3px、底部留 4px，这两个值是我调了几版之后定的，线太粗显得笨重，太细又看不清；底部留白太少会贴边，太多又显得飘。第三，抗锯齿一定要开，否则圆角会有毛边。

4.4 事件处理：点击、悬停、离开

点击事件负责切换选中页签并触发动画，移动事件负责更新悬停状态，离开事件负责清除悬停。

void TabBarWidget::mousePressEvent(QMouseEvent *event) { if (event->button() != Qt::LeftButton) return; const QPoint pos = event->pos(); for (int i = 0; i < m_tabRects.size(); ++i) { if (m_tabRects[i].contains(pos)) { setCurrentIndex(i); break; } } } void TabBarWidget::mouseMoveEvent(QMouseEvent *event) { const QPoint pos = event->pos(); int newHover = -1; for (int i = 0; i < m_tabRects.size(); ++i) { if (m_tabRects[i].contains(pos)) { newHover = i; break; } } if (newHover != m_hoverIndex) { m_hoverIndex = newHover; update(); } } void TabBarWidget::leaveEvent(QEvent *) { if (m_hoverIndex != -1) { m_hoverIndex = -1; update(); } }

别忘了在构造函数里setMouseTracking(true)，否则不按键的时候收不到 mouseMoveEvent，悬停就没反应。

4.5 动画：setCurrentIndex 里的关键几行

这是整个效果的核心。切换索引时，启动一个从当前位置到目标位置的动画。

void TabBarWidget::setCurrentIndex(int index) { if (index < 0 || index >= m_tabs.size()) return; if (index == m_currentIndex) return; m_currentIndex = index; const qreal targetX = indicatorTargetX(index); if (!m_anim) { m_anim = new QPropertyAnimation(this, "indicatorX", this); m_anim->setDuration(200); m_anim->setEasingCurve(QEasingCurve::OutCubic); } m_anim->stop(); m_anim->setStartValue(m_indicatorX); // 从当前位置接续 m_anim->setEndValue(targetX); m_anim->start(); update(); }

要让QPropertyAnimation能驱动m_indicatorX，得把它声明成 Q_PROPERTY：

Q_PROPERTY(qreal indicatorX READ indicatorX WRITE setIndicatorX)

然后实现读写函数，setIndicatorX里更新值并update()。这样动画每帧都会调用 setter，触发重绘，线就动起来了。

注意：m_anim->stop()之后再设 startValue，是为了处理“动画中途再次切换”的情况。如果不 stop，直接设 startValue，旧动画的插值状态可能残留，导致跳变。stop 之后从当前实时值重新出发，才是平滑的。

5. 动态增删与窗口缩放：那些容易翻车的地方

基础功能跑通之后，真正考验健壮性的是动态场景。页签不是一成不变的，用户可能新开一个会话、关掉一个群组，窗口也可能被随意拉伸。这些情况下下划线如果处理不好，就会出现错位、闪烁甚至崩溃。

5.1 增删页签时索引怎么维护

增加页签相对简单，往m_tabs里 append 一个文本，然后recalcLayout()加update()就行。但要注意：如果当前没有选中任何页签（m_currentIndex == -1），新增后要不要自动选中第一个？我的做法是，如果之前没有选中项，新增后自动选中新加的这个，这样下划线立刻出现，用户有反馈。

删除页签就麻烦一些，因为索引会变。假设当前选中索引是 3，删掉了索引 1 的页签，那原来的 3 就变成了 2，下划线得跟着移到新的 2 上。如果删掉的正好是当前选中的那个，得决定选中谁——通常选被删项的前一个，如果删的是第一个，就选新的第一个。

void TabBarWidget::removeTab(int index) { if (index < 0 || index >= m_tabs.size()) return; m_tabs.removeAt(index); if (m_tabs.isEmpty()) { m_currentIndex = -1; m_indicatorX = 0; recalcLayout(); update(); return; } if (index < m_currentIndex) { m_currentIndex--; // 选中项在删除项之后，索引前移 } else if (index == m_currentIndex) { m_currentIndex = qMin(index, m_tabs.size() - 1); // 选中被删，选邻近的 } // index > m_currentIndex 的情况不用动 recalcLayout(); m_indicatorX = indicatorTargetX(m_currentIndex); // 直接跳，不做动画 update(); }

这里删除后下划线我选择直接跳过去而不是做动画，因为删除本身是个突变操作，再叠个滑动动画反而显得拖沓。新增时如果是从无到有，也可以直接定位；如果是插入到中间，做不做动画看你喜好，我一般不做。

5.2 窗口缩放时下划线为什么会错位

窗口缩放触发resizeEvent，这时候必须重算布局，否则页签矩形还是旧的，下划线位置自然就错了。

void TabBarWidget::resizeEvent(QResizeEvent *event) { QWidget::resizeEvent(event); recalcLayout(); update(); }

recalcLayout里我已经处理了“布局变了同步更新 m_indicatorX”的逻辑，所以缩放时下划线会跟着页签走。但有个细节：如果缩放时动画正在播放，动画的 endValue 是旧布局下算出来的目标位置，缩放后这个值就失效了。我的处理是在recalcLayout里，如果动画在跑，就 stop 掉，然后直接把m_indicatorX设成新布局下的目标值。因为缩放过程中用户注意力在窗口边缘，下划线瞬间归位不会引起注意，反而比让它慢慢滑过去更自然。

5.3 高 DPI 屏幕下的模糊问题

现在很多笔记本是 2K、4K 屏，系统缩放 150% 甚至 200%。Qt 默认会做 DPI 缩放，但如果你在paintEvent里用整数坐标画线，缩放后可能出现半像素偏移，线看起来发虚。

解决办法有两个。一是开启QPainter的HighQualityAntialiasing，二是尽量用QRectF而不是QRect来画线，让坐标保持浮点精度。我在paintEvent里画下划线用的就是QRectF，配合抗锯齿，在高 DPI 下边缘依然锐利。另外，线高 3px 在 200% 缩放下实际是 6 个物理像素，如果觉得太粗，可以按devicePixelRatio动态调整，但大多数情况下固定值就够用。

提示：如果你发现高 DPI 下文字和线对不齐，检查一下是否在main函数里设置了Qt::AA_EnableHighDpiScaling。Qt5 需要手动开，Qt6 默认开启。这个属性不开的话，整个界面的缩放逻辑都会乱。

6. 常见问题与排查速查

实际开发中遇到的问题远不止上面这些，我把当时记录下来的典型问题和排查思路整理成一张表，方便你对照排查。

除了表里这些，还有两个我踩过的坑值得单独说。

第一个是update()的调用时机。动画驱动m_indicatorX的 setter 时，setter 里必须调update()，否则值变了但界面不重绘，线不动。我一开始忘了在 setter 里加，排查了半天才发现动画在跑、值在变，就是画面没反应。

第二个是页签文字过长时的处理。如果某个页签文字特别长，等宽布局下会被截断。我的做法是在drawText时用QFontMetrics::elidedText做省略号处理，超出部分显示成“…”。这个细节不做的话，长文字会溢出到相邻页签，很难看。

QFontMetrics fm(f); QString elided = fm.elidedText(m_tabs[i], Qt::ElideRight, m_tabRects[i].width() - 8); p.drawText(m_tabRects[i], Qt::AlignCenter, elided);

留 8 像素的边距，避免文字贴到页签边缘。

7. 还能怎么扩展：从页签栏到通用指示器组件

这套东西写完之后，我发现它的核心其实不是“页签”，而是“一个会跟随选中项滑动的指示器”。把这个逻辑抽出来，能复用到很多地方。

比如顶部导航栏、分段控制器（Segmented Control）、甚至侧边栏的选中高亮，本质上都是同一个模式：一组等距或不等距的选项，一个跟随选中的视觉标记，切换时平滑过渡。我把下划线的绘制部分抽成了一个Indicator结构体，包含位置、宽度、颜色、圆角、动画时长这些参数，页签栏只负责提供“每个选项的矩形”和“当前选中索引”，指示器负责算位置和画自己。这样换一个场景，只要提供新的矩形列表，指示器就能直接复用。

再进一步，如果你用的是 QML，这套思路可以更简洁地实现。QML 里用Row布局放Repeater生成的页签，下划线用一个独立的Rectangle，它的x属性绑定到一个Behavior on x { NumberAnimation { duration: 200; easing.type: Easing.OutCubic } }，切换时只要改x的目标值，动画自动就跑起来了，连 QPropertyAnimation 都不用写。这也是为什么我说思路是通的，工具不同而已。

最后分享一个我在调这个效果时的小习惯：把动画时长、线宽、底部留白、缓动曲线这几个参数全部提成命名常量放在文件顶部，调的时候改一处就行，不用满代码找魔法数字。这个习惯在 UI 开发里特别值，因为视觉参数往往要反复微调，集中管理能省下大量时间。