Qt自定义控件实现平滑下划线动画：QPropertyAnimation与paintEvent实战

1. 从一个“不起眼”的交互细节说起

做桌面端开发的朋友大概率都遇到过这种需求：左侧一个竖直的导航栏，里面排着“联系人”“群组”“讨论组”几个页签，用户点击哪个页签，哪个页签下面（或者旁边）就出现一条会“滑过去”的下划线，而不是生硬地闪现。这个效果在移动端几乎是标配，各种前端框架里都有现成组件，但一旦落到 Qt 桌面端，尤其是用 QWidget 体系手写的时候，很多人第一反应是“这玩意儿怎么搞”——Qt 自带的 QTabWidget 样式表能改颜色，但那条下划线要么是静态的，要么根本没法做平滑动画。

我自己在做一款即时通讯类的桌面客户端时，就完整踩过这个坑。当时的需求很明确：左侧是分组列表，顶部有几个页签（联系人、群组、最近会话），点击页签时下划线要从当前位置平滑滑动到目标位置，同时页签文字颜色也要跟着变。听起来简单，但真动手写的时候，涉及到自定义控件、QPropertyAnimation、paintEvent 重绘、坐标计算、动画与点击事件的时序配合等一堆细节。这篇文章就把我整个实现过程拆开揉碎讲清楚，从设计思路到核心代码，再到实际调试中遇到的各种坑，全部摊开来说。

这篇文章适合谁看？如果你已经会写基本的 Qt 控件、用过样式表、了解信号槽，但没怎么碰过自定义绘制和属性动画，那这篇就是为你准备的。如果你已经做过类似效果，也可以看看我在坐标计算和动画时序上的处理方式，说不定能帮你省掉几个小时的调试时间。核心关键词就三个：Qt 自定义控件、QPropertyAnimation 属性动画、paintEvent 下划线绘制。把这三个东西串起来，这个效果就成立了。

2. 整体设计思路与方案选型

2.1 为什么不用 QTabWidget 现成的方案

很多人第一反应是用 QTabWidget，然后通过样式表把 tab 改成竖直排列，再用border-bottom模拟下划线。我一开始也是这么想的，试了大概半小时就放弃了。原因有几个：第一，QTabWidget 的样式表对下划线的控制非常有限，你只能设置边框颜色和宽度，但没法让这条线“动起来”；第二，QTabWidget 的 tab 位置和尺寸是由内部布局算出来的，你想拿到某个 tab 的精确矩形区域去做动画，得去翻 QStyleOptionTab 那一套，代码写出来又臭又长；第三，竖直排列的 QTabWidget 在样式表下的表现很不稳定，不同平台、不同 Qt 版本渲染出来的间距都不一样。

所以结论很明确：这个效果必须自定义控件。自己画页签、自己画下划线、自己控制动画，虽然代码量上去了，但每一行都在你掌控之中，调试起来也直观。

2.2 自定义控件的整体架构

我的方案是做一个继承自 QWidget 的UnderlineTabBar控件，内部维护一个页签文本列表和一个当前选中索引。整个控件的绘制分两层：底层是页签文字，上层是下划线。下划线的位置由一个qreal类型的属性underlinePos控制，这个属性通过 QPropertyAnimation 驱动，每次切换页签时从当前位置动画到目标位置。

这里有个关键设计决策：下划线的位置用“中心点坐标”而不是“左边界坐标”来表示。为什么？因为不同页签的文字宽度不一样，“联系人”三个字和“最近会话”四个字的宽度差很多。如果用左边界做动画，从短文本切到长文本时，下划线会先跳到左边再滑过去，视觉上很别扭。用中心点坐标就自然多了——下划线始终以目标页签的文字中心为中心，宽度等于文字宽度加上一点 padding，动画过程中中心点平滑移动，宽度也可以同步做动画（如果想让宽度也变化的话）。

2.3 动画方案的选择：QPropertyAnimation vs QVariantAnimation

Qt 里做属性动画有两个常用类：QPropertyAnimation 和 QVariantAnimation。前者需要目标对象有一个用Q_PROPERTY声明的属性，后者更灵活，可以动画任意值，但需要自己连接valueChanged信号去更新。我选的是 QPropertyAnimation，因为下划线的位置本身就是一个天然的控件属性，用 Q_PROPERTY 声明出来，代码更清晰，而且 QPropertyAnimation 对 QWidget 子类的支持很好，不需要额外处理线程问题。

动画曲线我用的是QEasingCurve::OutCubic。试过 Linear、InOutQuad、OutQuint 几种，最后觉得 OutCubic 最舒服——起步快、收尾缓，有一种“滑过去然后轻轻停住”的感觉，不会像 Linear 那样机械，也不会像 OutQuint 那样收得太慢显得拖沓。这个纯属个人手感，你可以根据自己产品的调性调整。

3. 核心细节解析与实操要点

3.1 页签文字的绘制与宽度计算

页签文字的绘制看起来简单，但有几个细节要注意。首先是字体，我建议在控件构造时就固定好字体，不要在 paintEvent 里临时创建 QFont，那样每次重绘都会触发字体加载，性能很差。其次是文字宽度的计算，必须用 QFontMetrics 来算，不能用text.length() * 某个固定值这种土办法，因为中英文混排时字符宽度差异巨大。

// 在构造函数中预先计算每个页签的文字宽度 QFontMetrics fm(font()); for (const QString &text : m_tabTexts) { int w = fm.horizontalAdvance(text); m_tabWidths.append(w); }

这里用horizontalAdvance而不是老版本的width，因为 Qt 5.11 之后width已经被标记为废弃了，新代码应该用horizontalAdvance。如果你还在用更老的 Qt 版本，那就只能用width，但建议尽早升级。

文字绘制时，我用drawText的矩形对齐方式，把每个页签的文字画在它对应的区域内，水平居中、垂直居中。这里有个小技巧：给每个页签预留的宽度要比文字实际宽度大一些，比如加上 24px 的 padding，这样页签之间不会挤在一起，点击区域也更友好。

3.2 下划线的绘制：位置、宽度与圆角

下划线的绘制是整个效果的核心。我用的是QPainter::drawRoundedRect，画一个高度 3px、带 1.5px 圆角的矩形。为什么用圆角？因为直角的下划线在视觉上比较生硬，圆角看起来更精致，尤其是当你的产品整体风格偏圆润的时候。

下划线的水平位置由underlinePos决定，这个值是下划线的中心点 x 坐标。宽度我做了两种处理：一种是固定宽度（比如始终等于当前页签文字宽度），另一种是动画过程中宽度也变化。我最终选的是固定宽度等于目标页签文字宽度，动画只动位置。原因是宽度也做动画的话，视觉上会有点“抖”，而且计算量更大，收益不明显。

void UnderlineTabBar::paintEvent(QPaintEvent *event) { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing); // 绘制页签文字 for (int i = 0; i < m_tabTexts.size(); ++i) { QRect tabRect = tabRectAt(i); QColor textColor = (i == m_currentIndex) ? m_activeColor : m_inactiveColor; painter.setPen(textColor); painter.drawText(tabRect, Qt::AlignCenter, m_tabTexts[i]); } // 绘制下划线 if (m_currentIndex >= 0) { qreal underlineWidth = m_tabWidths[m_currentIndex] + 8; qreal left = m_underlinePos - underlineWidth / 2.0; QRectF underlineRect(left, height() - 6, underlineWidth, 3); painter.setPen(Qt::NoPen); painter.setBrush(m_activeColor); painter.drawRoundedRect(underlineRect, 1.5, 1.5); } }

注意这里下划线的 y 坐标是height() - 6，意思是距离控件底部 6px。这个值可以根据你的设计稿调整，但建议不要贴着底部，留一点呼吸空间更好看。

3.3 Q_PROPERTY 的声明与动画驱动

要让 QPropertyAnimation 能驱动underlinePos，必须用 Q_PROPERTY 宏声明它：

class UnderlineTabBar : public QWidget { Q_OBJECT Q_PROPERTY(qreal underlinePos READ underlinePos WRITE setUnderlinePos) public: qreal underlinePos() const { return m_underlinePos; } void setUnderlinePos(qreal pos) { if (qFuzzyCompare(m_underlinePos, pos)) return; m_underlinePos = pos; update(); // 触发重绘 } private: qreal m_underlinePos = 0; };

这里有个容易忽略的点：setUnderlinePos里必须调用update()，否则属性变了但界面不会重绘。另外用qFuzzyCompare做浮点数比较，避免因为精度问题导致不必要的重绘。

动画的启动逻辑是这样的：当用户点击某个页签时，先更新m_currentIndex，然后计算目标下划线位置，创建 QPropertyAnimation，从当前underlinePos动画到目标位置，时长设 250ms，曲线用 OutCubic。

void UnderlineTabBar::animateToIndex(int index) { if (index < 0 || index >= m_tabTexts.size()) return; if (index == m_currentIndex) return; m_currentIndex = index; qreal targetPos = tabRectAt(index).center().x(); if (m_animation) { m_animation->stop(); m_animation->deleteLater(); } m_animation = new QPropertyAnimation(this, "underlinePos"); m_animation->setDuration(250); m_animation->setStartValue(m_underlinePos); m_animation->setEndValue(targetPos); m_animation->setEasingCurve(QEasingCurve::OutCubic); m_animation->start(QAbstractAnimation::DeleteWhenStopped); }

注意：每次启动新动画前必须停掉旧动画，否则快速连续点击时会出现多个动画同时运行，下划线会乱跳。我用deleteLater而不是直接delete，是为了避免在动画回调中删除对象导致崩溃。

4. 完整实操过程与核心环节实现

4.1 控件初始化与页签布局计算

控件的初始化包括设置字体、计算页签宽度、确定每个页签的矩形区域。我采用的是水平等间距布局，每个页签的宽度等于文字宽度加上固定 padding，页签之间再留固定间距。整个控件的宽度就是所有页签宽度之和加上间距之和。

void UnderlineTabBar::initTabs(const QStringList &texts) { m_tabTexts = texts; m_tabWidths.clear(); m_tabRects.clear(); QFontMetrics fm(font()); int x = m_leftMargin; for (const QString &text : texts) { int textWidth = fm.horizontalAdvance(text); int tabWidth = textWidth + m_tabPadding * 2; m_tabWidths.append(textWidth); m_tabRects.append(QRect(x, 0, tabWidth, height())); x += tabWidth + m_tabSpacing; } setFixedWidth(x - m_tabSpacing + m_leftMargin); if (!texts.isEmpty()) { m_currentIndex = 0; m_underlinePos = m_tabRects[0].center().x(); } }

这里m_tabPadding我设的是 12，m_tabSpacing设的是 8，m_leftMargin设的是 16。这些值没有绝对标准，根据你的设计稿调就行。但有一点要注意：控件的固定宽度必须在所有页签布局完成后才能确定，否则会出现页签被截断或者右侧留白过多的问题。

4.2 鼠标点击与命中检测

点击事件的命中检测逻辑很直接：遍历所有页签矩形，判断鼠标位置在哪个矩形内。但这里有个细节——点击区域应该比视觉区域稍大一些，尤其是垂直方向。因为页签文字本身可能只有 20px 高，但用户点击时手指（或者鼠标）的落点不会那么精确。我的做法是把命中检测的矩形在垂直方向上下各扩展 8px。

void UnderlineTabBar::mousePressEvent(QMouseEvent *event) { if (event->button() != Qt::LeftButton) { QWidget::mousePressEvent(event); return; } QPoint pos = event->pos(); for (int i = 0; i < m_tabRects.size(); ++i) { QRect hitRect = m_tabRects[i].adjusted(0, -8, 0, 8); if (hitRect.contains(pos)) { animateToIndex(i); emit tabChanged(i); return; } } }

tabChanged信号是给外部用的，比如切换页面内容。这样控件本身只负责页签和下划线的视觉表现，业务逻辑通过信号解耦出去，符合单一职责原则。

4.3 动画时序与快速点击的处理

快速连续点击是这类动画效果最容易出问题的地方。假设用户先点“联系人”，动画刚开始 50ms，又点了“群组”，这时候如果不停掉旧动画，两个动画会同时修改underlinePos，下划线会疯狂抖动。我的处理是在animateToIndex开头就停掉旧动画，并且用DeleteWhenStopped策略让 Qt 自动清理。

但还有一个更隐蔽的问题：动画进行中，m_currentIndex已经更新了，但underlinePos还在旧位置。这时候如果触发重绘（比如窗口被遮挡后恢复），下划线的位置和当前选中页签会对不上。解决办法是在paintEvent里不要依赖m_currentIndex去反推下划线位置，而是直接用m_underlinePos画线，用m_currentIndex画文字颜色。这样即使动画中途重绘，下划线在哪儿就画在哪儿，不会跳。

另外，如果你希望动画过程中文字颜色也跟着渐变，那就需要再引入一个qreal属性来控制颜色插值。我试过，效果确实更细腻，但代码复杂度上去了。如果你的产品对细节要求没那么极致，文字颜色直接切换也完全可以接受。

4.4 与外部页面的联动

这个控件本身只负责页签栏，实际使用时通常要和 QStackedWidget 配合。我的做法是在外部用一个 QStackedWidget 存放各个页面，然后把tabChanged信号连接到QStackedWidget::setCurrentIndex。这样点击页签时，下划线动画和页面切换同时发生，视觉上很连贯。

connect(tabBar, &UnderlineTabBar::tabChanged, stackedWidget, &QStackedWidget::setCurrentIndex);

如果你想让页面切换也有动画（比如淡入淡出），那就需要自己写一个带 QGraphicsOpacityEffect 的切换逻辑，但这已经超出本文范围了，以后可以单独聊。

5. 常见问题与排查技巧实录

5.1 下划线位置偏移或抖动

这是最常见的问题，通常有三个原因。第一，tabRectAt返回的矩形和实际绘制文字的矩形不一致，导致中心点算错。排查方法是临时在 paintEvent 里把每个页签的矩形用不同颜色画出来，肉眼对比一下。第二，动画启动时m_underlinePos的初始值不对，比如控件刚创建时没有初始化，默认是 0，第一次点击时下划线会从最左边滑过来。解决办法是在initTabs里就把m_underlinePos设成第一个页签的中心点。第三，setUnderlinePos里没有做浮点数比较，导致每帧都触发重绘，性能差且可能引起抖动。

5.2 快速点击时下划线“跳变”

前面提到过，根本原因是旧动画没停。但还有一种情况：用户点击的速度极快，快到动画还没开始就被停了，这时候m_underlinePos可能还停留在上一个动画的中间值，新动画从这个中间值开始，视觉上会有一次“跳”。解决办法是在停掉旧动画后，先把m_underlinePos设成当前实际绘制位置（其实它本来就是），然后再启动新动画。如果你追求极致，可以在快速点击时缩短动画时长，比如检测到 300ms 内连续点击，就把时长降到 150ms，这样响应更快。

5.3 高 DPI 屏幕下下划线模糊

在高 DPI 屏幕上，如果下划线的高度是 3px，但实际物理像素是 1.5 倍或 2 倍，画出来的线可能会模糊。解决办法是开启QPainter::Antialiasing，并且用QRectF而不是QRect来绘制，让 Qt 自己做亚像素渲染。另外，下划线的 y 坐标最好用浮点数，不要强制转成整数，否则在缩放时会丢失精度。

5.4 页签文字过长导致布局错乱

如果某个页签的文字特别长（比如“最近会话记录”），而控件宽度是固定的，文字可能会被截断或者溢出。我的处理是在计算页签宽度时设一个上限，超过上限就用省略号。QFontMetrics 提供了elidedText方法，可以直接生成带省略号的文本。

QString displayText = fm.elidedText(text, Qt::ElideRight, maxTabWidth - m_tabPadding * 2);

但要注意，省略号后的文字宽度和原始文字宽度不一样，下划线的宽度应该以显示出来的文字宽度为准，而不是原始文字宽度。这个细节很容易忽略，导致下划线比文字长出一截。

5.5 常见问题速查表

提示：调试这类自定义绘制控件时，最有效的方法是在 paintEvent 里临时画出辅助线（页签边界、下划线中心点等），肉眼一看就知道哪里算错了。调完之后再把辅助线代码注释掉。

6. 一些进阶玩法与个人经验

6.1 让下划线宽度也动起来

前面我说宽度不做动画，但其实如果你愿意多写一点代码，宽度动画的效果会更精致。思路是再声明一个qreal underlineWidth属性，动画时同时驱动位置和宽度。但要注意，位置是中心点，宽度变化时左右两边会同时扩展或收缩，视觉上像是下划线在“呼吸”。这个效果适合页签文字宽度差异较大的场景，如果所有页签文字宽度差不多，就没必要了。

6.2 支持键盘导航

桌面端用户有时候会用键盘 Tab 键切换焦点，或者用左右方向键切换页签。我的做法是重写keyPressEvent，检测左右方向键，然后调用animateToIndex。同时把控件设置为Qt::StrongFocus，这样它能接收键盘事件。别忘了在焦点进入和离开时重绘，给页签加一个焦点框或者改变下划线颜色，让用户知道当前焦点在哪儿。

6.3 主题切换时的颜色处理

如果你的应用支持深色/浅色主题切换，下划线和文字颜色不能写死。我的做法是把颜色定义成成员变量，提供一个setThemeColors方法，主题切换时调用这个方法更新颜色并update()。注意动画进行中切换主题时，下划线的颜色会立即变，但位置动画不受影响，这个行为是合理的。

6.4 性能考量

这个控件本身很轻量，paintEvent 里只画几个文字和一条线，性能瓶颈通常不在绘制，而在动画帧率。QPropertyAnimation 默认的帧率是 60fps，对于这个效果足够了。如果你发现动画卡顿，先检查是不是在setUnderlinePos里做了耗时操作，比如重新计算布局或者查询数据库。setUnderlinePos里只应该做两件事：更新成员变量、调用update()。

另外，如果你的页签数量很多（比如超过 20 个），每次重绘都遍历所有页签画文字可能会有性能问题。这时候可以考虑只画可见区域内的页签，或者用 QPixmap 缓存静态文字。但一般来说，页签数量不会超过 10 个，不用过度优化。

6.5 一个容易忽略的细节：动画结束后的状态同步

动画结束后，underlinePos应该精确等于目标位置。但由于浮点数精度问题，可能会有极小的偏差。我的做法是在动画的finished信号里，强制把underlinePos设成精确的目标值，确保下次动画的起点是准确的。

connect(m_animation, &QPropertyAnimation::finished, this, [this, targetPos]() { setUnderlinePos(targetPos); });

这个细节在单次点击时看不出差别，但连续切换多次后，累积误差可能会导致下划线偏移一两个像素，细心的用户能看出来。

6.6 关于代码组织的一点建议

这个控件的代码量大概在 200 行左右，不算多，但如果你把它和业务逻辑混在一起写，很快就会变得难以维护。我的建议是：控件只负责视觉和交互，所有业务相关的逻辑（比如切换页面、加载数据）都通过信号抛出去。控件的头文件里只暴露必要的接口：initTabs、setCurrentIndex、currentIndex、tabChanged信号。内部实现细节（比如tabRectAt、animateToIndex）全部放在私有区域。这样以后要换动画曲线、改颜色、加页签，都不会影响到外部代码。

我在实际项目里还遇到过一个需求：页签需要支持拖拽排序。这个功能加上去之后，m_tabRects的重新计算逻辑就变得复杂了，因为拖拽过程中页签位置会实时变化。我的处理是在拖拽时暂停下划线动画，拖拽结束后重新计算所有页签矩形，然后把下划线直接设到新位置，不做动画。这个体验反而更好，因为拖拽本身已经有视觉反馈了，再加动画会显得乱。

最后分享一个小技巧：如果你想让下划线在鼠标悬停时也有反馈（比如变粗或者变色），可以重写mouseMoveEvent，记录当前悬停的页签索引，在 paintEvent 里对悬停页签做特殊处理。但要注意，悬停效果和下划线动画是两套独立的视觉反馈，不要混在一起，否则用户会分不清哪个是当前选中、哪个是悬停。