简介：这份资源面向Qt初学者与界面开发爱好者，围绕paintEvent事件处理机制，提供一个可运行的自定义电池进度条控件实例，用于解决图形界面中电量状态可视化与动态反馈的问题。压缩包共8个文件，约7KB，以3个cpp源文件与2个h头文件为核心实现绘制与动画逻辑，另含pro工程文件、ui界面文件及user配置，结构精简便于直接编译学习。资源已有501人学习下载，具备一定的参考热度。内容涵盖QPainter绘制电池外壳与电量填充、按电量比例切换正常与警示颜色、借助QPropertyAnimation实现电量变化动画，并涉及绘制性能优化与布局管理等要点，绘制逻辑与动画逻辑分离、辅助功能封装为独立方法，适合读者理解Qt绘图与状态反馈的完整实现思路。
1. 电池进度条：一个被低估的 Qt 自绘练手项目
设备管理类界面里，电池电量条几乎是绕不开的控件。很多人第一反应是找个现成控件库，或者拿 QProgressBar 改样式表凑合，结果一遇到分段电量、低电量变色、充电动画就卡壳。这个项目走的是另一条路：继承 QWidget，重写 paintEvent，用 QPainter 一笔一笔把电池外壳、电量填充、正极触点画出来。它适合刚学完 Qt 信号槽、想真正搞懂自绘机制的开发者，也适合需要在嵌入式或桌面端做定制电量指示的工程场景。代码量不大，但把坐标计算、抗锯齿、比例映射、状态切换这几件事串成了一条完整链路，跑通之后你对 Qt 绘制体系的理解会上一个台阶。
2. 项目结构与绘制链路：从 QWidget 到一帧电池图
2.1 目录组织与类职责划分
这个项目是典型的 Qt Widgets 单窗口工程，用 qmake 或 CMake 都能组织。核心文件就几个，但职责边界清晰，二次开发时不容易改乱。
batterywidget/ ├── batterywidget.pro # qmake 工程文件 ├── CMakeLists.txt # CMake 构建脚本（二选一） ├── main.cpp # 程序入口，创建主窗口 ├── mainwindow.h / .cpp # 主窗口，放电池控件和滑块 ├── batterywidget.h / .cpp # 核心自绘控件 └── resources/ └── style.qss # 可选，窗口整体样式BatteryWidget继承自QWidget，对外暴露三个关键接口：setValue(int)设置电量百分比，setCharging(bool)切换充电状态，setLowThreshold(int)配置低电量阈值。内部维护m_value、m_charging、m_lowThreshold三个成员变量，任何 setter 改动后调用update()触发重绘。主窗口只负责把滑块信号接到setValue，把复选框接到setCharging，控件本身不关心数据从哪来，这种解耦是后面能复用的前提。
工程文件里QT += widgets是必须的，如果要用动画还得加core。我一般会在.pro里显式写CONFIG += c++11，避免不同编译器默认标准不一致导致 lambda 写法翻车。
2.2 paintEvent 的完整绘制顺序
paintEvent是整个项目的灵魂，它决定了每一帧长什么样。绘制顺序不能乱，否则会出现填充盖住边框、触点被裁掉这类问题。合理的顺序是：先算几何区域，再画外壳，再画电量填充，最后画正极触点和文字。
void BatteryWidget::paintEvent(QPaintEvent *event) { Q_UNUSED(event); QPainter painter(this); // 抗锯齿必须开，否则圆角和斜线会有明显锯齿 painter.setRenderHint(QPainter::Antialiasing, true); // 1. 计算电池主体区域，右侧留出触点宽度 const int tipWidth = width() * 0.08; QRectF bodyRect(2, 2, width() - tipWidth - 6, height() - 4); QRectF tipRect(bodyRect.right() + 2, height() * 0.3, tipWidth, height() * 0.4); // 2. 画外壳：圆角矩形，只描边不填充 QPen borderPen(borderColor(), 2); painter.setPen(borderPen); painter.setBrush(Qt::NoBrush); painter.drawRoundedRect(bodyRect, 6, 6); // 3. 画电量填充：按比例裁剪内部区域 QRectF inner = bodyRect.adjusted(4, 4, -4, -4); qreal ratio = qBound(0.0, m_value / 100.0, 1.0); QRectF fillRect(inner.left(), inner.bottom() - inner.height() * ratio, inner.width(), inner.height() * ratio); painter.setPen(Qt::NoPen); painter.setBrush(fillColor()); painter.drawRoundedRect(fillRect, 3, 3); // 4. 画正极触点 painter.setBrush(borderColor()); painter.drawRoundedRect(tipRect, 2, 2); // 5. 居中绘制百分比文字 painter.setPen(textColor()); QFont font = painter.font(); font.setPixelSize(qMax(10, height() / 3)); font.setBold(true); painter.setFont(font); painter.drawText(bodyRect, Qt::AlignCenter, QString::number(m_value) + "%"); }这段代码有几个参数值得说清楚。tipWidth取宽度的 8%，是为了让触点在不同尺寸下保持视觉比例，写死像素值在缩放时会失真。bodyRect四周留 2 像素边距，防止描边被控件边界裁掉。inner用adjusted(4,4,-4,-4)内缩，保证填充和外壳之间有一圈留白，看起来才有"电量在壳里"的层次感。qBound把比例钳在 0 到 1 之间，防止外部传入越界值导致填充矩形高度为负——这是血泪经验，负数高度在某些平台上会画出诡异图形。
填充矩形的起点是inner.bottom() - inner.height() * ratio，也就是从底部往上长，符合电池电量从下往上增加的直觉。如果做成从上往下，用户第一眼会觉得电量在漏。
2.3 颜色状态机与低电量告警
颜色不是写死的，而是根据电量和充电状态动态决定。这部分逻辑单独抽成fillColor()和borderColor()两个私有函数，paintEvent里只调用不判断，保持绘制流程干净。
QColor BatteryWidget::fillColor() const { if (m_charging) { return QColor(76, 175, 80); // 充电中：绿色 } if (m_value <= m_lowThreshold) { return QColor(244, 67, 54); // 低电量：红色 } if (m_value <= 30) { return QColor(255, 152, 0); // 偏低：橙色 } return QColor(33, 150, 243); // 正常：蓝色 } QColor BatteryWidget::borderColor() const { // 低电量时边框同步变红，强化告警感知 return (m_value <= m_lowThreshold && !m_charging) ? QColor(244, 67, 54) : QColor(97, 97, 97); }阈值判断的顺序很重要：充电状态优先级最高，插着电就不该显示红色告警；低电量阈值默认 20，可以通过setLowThreshold改，比如医疗设备场景可能设到 30。颜色值用的是 Material Design 常见色值，视觉上不刺眼，嵌到深色或浅色主题里都不违和。
这里有个容易忽略的点：m_lowThreshold要在构造函数里初始化，否则未定义值参与比较，低电量告警可能永远不触发或者一上来就触发。我一般会在头文件里直接给默认值int m_lowThreshold = 20;，比在构造函数里赋值更不容易漏。
2.4 主窗口接线与交互验证
控件画得再好，没有数据驱动也看不出效果。主窗口里放一个QSlider和一个QCheckBox，把信号接到控件的 setter 上，就能实时验证绘制逻辑。
MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { auto *central = new QWidget(this); auto *layout = new QVBoxLayout(central); m_battery = new BatteryWidget(central); m_battery->setMinimumSize(120, 60); m_battery->setValue(75); auto *slider = new QSlider(Qt::Horizontal, central); slider->setRange(0, 100); slider->setValue(75); auto *chargeBox = new QCheckBox("充电中", central); layout->addWidget(m_battery); layout->addWidget(slider); layout->addWidget(chargeBox); setCentralWidget(central); // 滑块拖动实时驱动重绘 connect(slider, &QSlider::valueChanged, m_battery, &BatteryWidget::setValue); connect(chargeBox, &QCheckBox::toggled, m_battery, &BatteryWidget::setCharging); }setMinimumSize(120, 60)是给控件一个合理的最小尺寸，太小的话文字和触点会挤在一起。滑块范围 0 到 100 直接对应百分比，省去换算。valueChanged信号在拖动时高频触发，每次都会走一遍update()和paintEvent，正好用来观察绘制性能——如果拖动时明显卡顿，说明paintEvent里有耗时操作，需要优化。
编译运行用 qmake 的话：
qmake batterywidget.pro make -j4 ./batterywidget用 CMake 则是：
cmake -B build -DCMAKE_PREFIX_PATH=/path/to/qt cmake --build build ./build/batterywidgetCMAKE_PREFIX_PATH指向 Qt 安装目录，找不到 Qt 时 CMake 会报Could not find a package configuration file provided by "Qt6"，把路径配对基本就能过。
3. 避坑与排查：自绘控件最容易翻车的几个点
3.1 填充溢出外壳
现象是电量 100% 时填充色盖住了圆角边框，或者 0% 时还残留一条色带。原因通常是填充矩形直接用了bodyRect而不是内缩后的inner，或者比例计算没做钳制。解决方式是统一用inner作为填充基准，比例用qBound(0.0, value/100.0, 1.0)包一层，并且在setValue里也做一次范围限制，双保险。
3.2 高 DPI 下文字模糊
现象是在 4K 屏或缩放 150% 的环境里，百分比文字发虚、边框变粗。原因是绘制坐标用了整数像素，没有考虑设备像素比。解决方式是在paintEvent开头取devicePixelRatioF()，或者更简单——所有几何计算用QRectF浮点矩形，QPainter会自动按设备像素比渲染。另外字体大小用setPixelSize而不是setPointSize，像素尺寸在高 DPI 下更可控。
3.3 频繁 update 导致闪烁
现象是拖动滑块时控件闪烁，或者 CPU 占用偏高。原因可能是控件没有设置Qt::WA_OpaquePaintEvent属性，Qt 每次重绘前会先填充背景。解决方式是在构造函数里setAttribute(Qt::WA_OpaquePaintEvent, true)，前提是paintEvent里确实把整个区域都画满了。如果还有闪烁，检查是否在paintEvent里创建了重量级对象，比如每次 new 一个 QFont，应该把字体缓存成成员变量。
3.4 充电状态切换不刷新
现象是勾选"充电中"后颜色没变。原因多半是setCharging里忘了调update()，或者只改了成员变量没触发重绘。解决方式是所有 setter 末尾统一加update()，并且判断值是否真的变化，避免无意义重绘：
void BatteryWidget::setCharging(bool charging) { if (m_charging == charging) return; m_charging = charging; update(); }3.5 控件缩放后触点比例失调
现象是把窗口拉大后，正极触点变得又宽又扁。原因是触点宽度用了固定像素值。解决方式是像 2.2 节那样按width()的百分比计算，高度按height()的百分比计算，保证任意尺寸下视觉比例一致。如果对比例要求更严格，可以监听resizeEvent做额外约束，但大多数场景百分比方案够用。
4. 二次开发：把电池条改成通用分段指示器
这个控件的骨架其实不限于电池。把"填充比例"抽象出来，就能改造成信号强度条、存储占用条、任务进度条。我的做法是抽一个SegmentIndicator基类，把paintEvent里的几何计算和填充逻辑放进去，子类只重写fillColor()和drawDecoration()。电池的正极触点就是drawDecoration()的一个实现，信号强度条可以在这里画几根竖线。
改造时验证方法很直接：写一个测试窗口，用定时器每 100ms 随机改一次 value，跑十分钟看有没有内存增长和绘制异常。我一般还会把paintEvent的耗时用QElapsedTimer打出来，超过 2ms 就说明有优化空间，正常应该在 0.5ms 以内。
另一个实用技巧是把颜色配置外置成 QSS 或 JSON，而不是写死在fillColor()里。这样换主题不用重新编译，嵌入式项目里尤其有用——现场调色是常态，能改配置文件就别动代码。
| 改造方向 | 改动点 | 注意事项 |
|---|---|---|
| 分段电量 | 填充改为按段绘制 | 段间距要计入内缩 |
| 横向进度 | 填充方向改为从左到右 | 起点用 inner.left() |
| 动画过渡 | 用 QPropertyAnimation 驱动 value | 动画期间禁用外部 setValue |
| 主题切换 | 颜色抽到配置 | 切换后调 update() |
从那以后我每次写自绘控件，都强制先在纸上把绘制顺序和几何区域画一遍，再动手写paintEvent，省下的调试时间远比画图那几分钟多。希望帮到你。
本文还有配套的精品资源，点击获取
