详细介绍：Qt C++ 自定义控件实战：QSS 美化 + 事件重写核心技巧

在Qt开发中，原生控件往往无法满足个性化的UI设计需求，而自定义控件是解决这一问题的核心手段。自定义控件的实现离不开两大核心技术：QSS（Qt Style Sheet）美化 负责视觉呈现，事件重写 负责交互逻辑。本文将通过一个实战案例（自定义圆形进度按钮），系统讲解QSS美化和事件重写的核心技巧，帮助你掌握Qt自定义控件的开发精髓。

一、前置基础：核心概念与环境准备

1.1 自定义控件的核心价值

Qt原生控件（如QPushButton、QProgressBar）的样式和交互逻辑固定，无法满足个性化需求（如圆形按钮、渐变进度条、自定义点击反馈）。自定义控件通过继承Qt基础控件（QWidget/QPushButton等），结合QSS美化和事件重写，实现视觉和交互的完全定制，是Qt界面开发的必备技能。

1.2 核心技术原理

• QSS：类似CSS的样式表语言，用于定义控件的外观（颜色、圆角、阴影、渐变等），支持选择器、伪状态、子控件样式，可全局/局部加载，动态修改。
• 事件重写：Qt采用事件驱动模型，控件的交互（点击、鼠标悬浮、绘制）本质是事件处理。通过重写Qt控件的虚事件函数（如paintEvent、mousePressEvent），可自定义事件处理逻辑，实现个性化交互。

1.3 环境准备

• Qt版本：推荐Qt 6.5+（兼容Qt 5.15+）
• 开发工具：Qt Creator 12.0+
• 项目类型：Qt Widgets Application（基于C++）

二、实战案例：自定义圆形进度按钮

我们将开发一个“圆形进度按钮”控件，具备以下特性：

1. 视觉：圆形外观、渐变背景、进度条环形显示、文字居中；
2. 交互：鼠标悬浮/按下时样式变化、点击触发进度更新、进度完成后状态切换；
3. 可复用：封装进度属性、信号槽，支持外部控制进度。

2.1 控件框架搭建

首先创建自定义控件类CustomProgressButton，继承自QWidget（选择QWidget而非QPushButton，是为了完全自定义绘制逻辑）。

步骤1：创建头文件（CustomProgressButton.h）

#ifndef CUSTOMPROGRESSBUTTON_H
#define CUSTOMPROGRESSBUTTON_H
#include <QWidget>
  #include <QPaintEvent>
    #include <QMouseEvent>
      #include <QPropertyAnimation>
        class CustomProgressButton : public QWidget
        {
        
        Q_OBJECT
        // 注册进度属性，支持QSS动态绑定和属性动画
        Q_PROPERTY(int progress READ progress WRITE setProgress NOTIFY progressChanged)
        // 注册按钮状态属性（正常/悬浮/按下/完成）
        Q_PROPERTY(ButtonState buttonState READ buttonState WRITE setButtonState NOTIFY buttonStateChanged)
        public:
        // 按钮状态枚举
        enum ButtonState {
        
        Normal,     // 正常状态
        Hover,      // 悬浮状态
        Pressed,    // 按下状态
        Completed   // 完成状态
        };
        Q_ENUM(ButtonState) // 注册枚举，支持QSS伪状态匹配
        explicit CustomProgressButton(QWidget *parent = nullptr);
        // 进度值读写接口
        int progress() const;
        void setProgress(int progress);
        // 按钮状态读写接口
        ButtonState buttonState() const;
        void setButtonState(ButtonState state);
        signals:
        void progressChanged(int progress);       // 进度变化信号
        void buttonStateChanged(ButtonState state);// 状态变化信号
        void clicked();                           // 点击信号
        protected:
        // 重写核心事件函数
        void paintEvent(QPaintEvent *event) override;    // 绘制事件（核心）
        void mousePressEvent(QMouseEvent *event) override;// 鼠标按下事件
        void mouseReleaseEvent(QMouseEvent *event) override;// 鼠标释放事件
        void enterEvent(QEnterEvent *event) override;    // 鼠标进入事件
        void leaveEvent(QEvent *event) override;         // 鼠标离开事件
        private:
        int m_progress;          // 进度值（0-100）
        ButtonState m_buttonState; // 按钮状态
        bool m_isPressed;        // 鼠标按下标记
        };
        #endif // CUSTOMPROGRESSBUTTON_H

步骤2：创建源文件（CustomProgressButton.cpp）

先实现构造函数和属性读写接口，初始化基础参数：

#include "CustomProgressButton.h"
#include <QPainter>
  #include <QLinearGradient>
    #include <QRadialGradient>
      CustomProgressButton::CustomProgressButton(QWidget *parent)
      : QWidget(parent)
      , m_progress(0)
      , m_buttonState(Normal)
      , m_isPressed(false)
      {
      
      // 设置控件固定大小（可改为自适应，此