如何为带圆角边框的QPushButton实现正常的QLinearGradient进度动画

QSS在处理圆角边框的渐变时，会将四个圆角区域的渐变与边框四条直边单独计算，导致圆角部分的渐变和当前动画的边框进度不同步，出现类似镜像的错误效果——这是QSS渲染逻辑的固有局限，直接用QSS很难解决，推荐以下两种可靠方案：

方案一：重写paintEvent自定义绘制（推荐） #

通过自定义QPushButton的绘制逻辑，直接用QPainter绘制带渐变的圆角边框，完全控制进度动画的渲染，避免QSS的局限性。

代码示例： #

#include <QPushButton>
#include <QPropertyAnimation>
#include <QPainter>
#include <QPainterPath>

class ProgressButton : public QPushButton {
    Q_OBJECT
    Q_PROPERTY(qreal progress READ progress WRITE setProgress)
public:
    explicit ProgressButton(QWidget *parent = nullptr) 
        : QPushButton(parent), m_progress(0.0) {}

    qreal progress() const { return m_progress; }
    void setProgress(qreal value) {
        m_progress = qBound(0.0, value, 1.0);
        update(); // 触发重绘
    }

protected:
    void paintEvent(QPaintEvent *event) override {
        // 先绘制按钮原有样式（文字、背景等）
        QPushButton::paintEvent(event);

        QPainter painter(this);
        painter.setRenderHint(QPainter::Antialiasing); // 抗锯齿，保证圆角平滑

        // 定义边框区域（留出边框宽度的空间，避免超出按钮范围）
        const qreal borderWidth = 2;
        QRectF borderRect = rect().adjusted(borderWidth/2, borderWidth/2, 
                                           -borderWidth/2, -borderWidth/2);
        const qreal borderRadius = 8; // 和你需要的圆角半径一致

        // 创建圆角矩形路径
        QPainterPath borderPath;
        borderPath.addRoundedRect(borderRect, borderRadius, borderRadius);

        // 根据进度创建线性渐变：从左到右，进度位置前为实色，之后为透明
        QLinearGradient gradient(borderRect.topLeft(), borderRect.topRight());
        gradient.setColorAt(0, Qt::darkCyan);
        gradient.setColorAt(m_progress, Qt::darkCyan);
        gradient.setColorAt(m_progress, Qt::transparent);
        gradient.setColorAt(1, Qt::transparent);

        // 设置画笔并绘制边框
        QPen borderPen(QBrush(gradient), borderWidth);
        painter.setPen(borderPen);
        painter.drawPath(borderPath);
    }

private:
    qreal m_progress;
};

使用动画： #

// 创建按钮并设置基础样式
ProgressButton *btn = new ProgressButton("计时按钮");
btn->setStyleSheet(R"(
    QPushButton {
        border-radius: 8px;
        background-color: #f0f0f0;
        padding: 8px 16px;
        font-size: 14px;
    }
)");

// 创建进度动画
QPropertyAnimation *anim = new QPropertyAnimation(btn, "progress");
anim->setDuration(3000); // 3秒完成进度
anim->setStartValue(0.0);
anim->setEndValue(1.0);
anim->start(QAbstractAnimation::DeleteWhenStopped);

方案二：使用border-image（局限性较大） #

提前制作带圆角的进度帧图片，通过QSS的border-image属性配合动画切换图片。这种方法适合固定样式的动画，但动态调整进度不够灵活，需要预生成多帧图片。

示例QSS（配合动画修改border-image的URL）：

QPushButton {
    border-radius: 8px;
    border: 2px solid transparent;
    border-image: url(progress_0.png) 2 stretch;
}

为什么QSS直接设置会出错？ #

QSS在处理border的渐变时，会将四条直边（top/bottom/left/right）和四个圆角分开渲染，圆角部分会复用相邻直边的渐变参数，当你用动画修改渐变位置时，圆角的渐变无法和直边同步，就会出现镜像、错位的效果——这是Qt QSS渲染引擎的设计缺陷，没有完美的QSS层面修复方案，自定义绘制是最优解。

内容的提问来源于stack exchange，提问作者CPPUIX