1. 从一次重绘闪烁说起:代码开发工具里的 QPainter 子控件
在代码开发工具里做 Qt 自绘控件,最容易翻车的不是 QPainter 的 API 记不住,而是 paintEvent 和 update 的分工没理清。我做过一个状态面板,进度每 200 毫秒推进一次,窗口一缩放,状态文字后面就拖出一条残影,第一反应是抗锯齿的玄学问题,最后定位到构造里开了 Qt::WA_OpaquePaintEvent,paintEvent 却没有用背景色铺满整个控件。这个反直觉的点,正是 Qt 自定义控件从“能画出来”到“重绘不闪”的分水岭。下面从 StatusPanel 这个最小控件开始,把接口、绘制顺序和踩坑拆开,适合正在写 Qt 子控件绘图、被闪烁或坐标错位卡住的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具中的基础框架:StatusPanel 的接口、属性与 update 分工
写自绘控件,我习惯先把数据入口定下来,再动 paintEvent。原因很简单:绘制代码一旦和业务数据搅在一起,后面改一个进度值就要翻半屏绘图语句,排查重绘问题时连“谁改了状态”都说不清。StatusPanel 只做三件事:保存进度、保存状态文字、在 paintEvent 里按当前尺寸画出来。接口越窄,后面越容易验证。
2.1 先定接口再画:头文件里只留数据入口
头文件里只暴露两个 setter,成员变量全部私有,默认值直接写在声明处。这样构造完控件就有一个确定状态,不会出现“进度是随机值”的黑匣子。
cpp复制#ifndef STATUSPANEL_H
#define STATUSPANEL_H
#include <QWidget>
#include <QString>
class StatusPanel : public QWidget
{
Q_OBJECT
public:
explicit StatusPanel(QWidget *parent = nullptr);
void setProgress(int value); // 设置进度 0~100
void setStatusText(const QString &text);
protected:
void paintEvent(QPaintEvent *event) override;
private:
int m_progress = 0;
QString m_statusText = QStringLiteral("待机");
};
#endif
这段头文件的关键不在语法,而在职责边界。setProgress 只接收一个 int,范围在实现里用 qBound 收口;setStatusText 接收 QString,绘制时直接用。m_progress 默认 0,m_statusText 默认“待机”,意味着控件刚创建、还没收到任何业务数据时也能画出一个完整面板,不会出现空白或未初始化字符串。paintEvent 放在 protected 里,外部不能直接调用,只能由 Qt 的重绘机制触发,这一点对后面理解 update() 很重要。
接口定完,先别急着写绘制。我一般会问自己两个问题:这个控件是不是完全不透明?数据变化后由谁通知重绘?这两个答案决定了构造里的属性和 setter 里的最后一行。
2.2 构造里的 WA_OpaquePaintEvent:为什么敢让 Qt 不填背景
构造函数里只做了一件事:调用 setAttribute(Qt::WA_OpaquePaintEvent)。这行代码告诉 Qt:“这个控件完全不透明,不需要系统先填充背景色。”好处是减少一次无意义的背景绘制,重绘时不容易闪;代价是 paintEvent 必须自己画满整个控件区域,不能只画边框和文字就收工。
cpp复制#include "statuspanel.h"
#include <QPainter>
#include <QPen>
#include <QBrush>
#include <QFontMetrics>
StatusPanel::StatusPanel(QWidget *parent)
: QWidget(parent)
{
setAttribute(Qt::WA_OpaquePaintEvent);
}
void StatusPanel::setProgress(int value)
{
m_progress = qBound(0, value, 100);
update(); // 只请求重绘,不立刻绘制
}
void StatusPanel::setStatusText(const QString &text)
{
m_statusText = text;
update();
}
setAttribute(Qt::WA_OpaquePaintEvent) 是一个承诺,不是优化开关。承诺的内容是“我 paintEvent 里会把 rect() 铺满”,Qt 才敢跳过默认背景填充。如果控件需要半透明、圆角外要透出父窗口背景,或者你只想画中间一小块,这个属性就不能开,否则残影会教你做人。setProgress 里先用 qBound(0, value, 100) 把输入夹到 0 到 100,再赋值,最后 update()。qBound 的顺序是下界、值、上界,传 120 会变成 100,传 -5 会变成 0,进度条宽度计算就不会出现负值或超出控件。
setStatusText 没有做长度截断。状态文字太长时,drawText 会在给定矩形里按对齐方式绘制,超出部分是否裁切取决于绘制区域和字体,实际使用中要么控制文案长度,要么在绘制时用 QFontMetrics 做省略处理。这里先保持接口简单,把裁切策略留到需要时再加。
2.3 update 与 paintEvent 的分工:改数据不立刻画
update() 不是立刻调用 paintEvent,它只是向 Qt 投递一个重绘请求,真正的绘制发生在事件循环回到重绘时机。这个分工是 Qt 子控件绘图不卡界面的基础:业务代码可以连续调用 setProgress(10)、setProgress(20)、setProgress(30),Qt 会把多次请求合并成一次 paintEvent,而不是每改一次就同步画一遍。
这也解释了一个常见现象:调试时在 setProgress 后面打断点,发现界面还没变,继续跑才刷新。不是 setter 没生效,是绘制还没轮到。paintEvent 里只读成员变量,不修改成员变量,不弹窗,不做耗时计算,这是自绘控件的基本纪律。把“改数据”和“画数据”拆成两条路径,后面排查闪烁时才能明确是数据问题还是绘制问题。
参数上,m_progress 是 int,范围 0 到 100;m_statusText 是 QString,默认“待机”。这两个成员就是 paintEvent 的全部输入。构造里开的 WA_OpaquePaintEvent 是绘制约束,setter 里的 update() 是重绘入口。三者配合起来,控件才有稳定的重绘节奏。
3. 代码开发工具里的 paintEvent 分层:背景、边框、文字与进度条怎么落笔
paintEvent 里最怕两种写法:一种是所有绘制语句平铺,改一个颜色要在一堆 setPen 里找;另一种是先画细节再补背景,结果背景把前面的文字盖掉。StatusPanel 的绘制顺序是固定的五层:背景、边框、标题、状态文字、进度条。顺序不是审美问题,是覆盖关系问题。
3.1 坐标系先对齐:QPainter(this) 的原点到底在哪
QPainter painter(this); 一旦把 this 传进去,坐标系原点就在控件自身的左上角,所有绘制都相对这个原点。也就是说,标题矩形写 QRect(12, 8, width() - 24, 20),x=12 是相对控件左边距 12 像素,不是相对父窗口,也不是相对屏幕。这个观念转过来,子控件绘图就成功了一半。
很多人坐标错位,不是算错数字,是把父窗口坐标带进来了。比如在子控件里用 mapToParent() 算了一个点,又直接塞给 QPainter,画出来的进度条就偏到窗口左上角。paintEvent 里应该只用控件局部坐标:rect() 是控件自身矩形,width() 和 height() 是控件自身宽高,边距用固定数字或成员常量。需要和父窗口交互时,在事件处理里转换,不要带进绘制函数。
还有一个细节:边框用 rect().adjusted(1, 1, -1, -1),把绘制矩形向内收 1 像素。QPen 宽度是 1 时,线条会骑在矩形边界上,不收的话外侧半个像素可能被控件裁掉。这个 1 像素不是随便写的,它和边框笔宽对应。
3.2 五层绘制顺序:从 fillRect 到进度条前景
完整 paintEvent 如下。第一行 fillRect(rect(), QColor("#1E1E2E")) 是 WA_OpaquePaintEvent 的配套动作,先把整个控件铺满,后面画什么都不会透出上一帧。
cpp复制void StatusPanel::paintEvent(QPaintEvent *event)
{
QPainter painter(this);
painter.setRenderHint(QPainter::Antialiasing, true);
// 绘制背景
painter.fillRect(rect(), QColor("#1E1E2E"));
// 绘制边框
QPen borderPen(QColor("#3A3A4A"));
borderPen.setWidth(1);
painter.setPen(borderPen);
painter.drawRect(rect().adjusted(1, 1, -1, -1));
// 绘制标题
painter.setPen(QColor("#E0E0E0"));
QFont titleFont = font();
titleFont.setPointSize(10);
titleFont.setBold(true);
painter.setFont(titleFont);
painter.drawText(QRect(12, 8, width() - 24, 20),
Qt::AlignLeft | Qt::AlignVCenter,
QStringLiteral("运行状态"));
// 绘制状态文字
painter.setPen(QColor("#8A8A9A"));
QFont textFont = font();
textFont.setPointSize(8);
painter.setFont(textFont);
painter.drawText(QRect(12, 32, width() - 24, 16),
Qt::AlignLeft | Qt::AlignVCenter,
m_statusText);
// 进度条背景
QRectF barRect(12, 54, width() - 24, 8);
painter.setPen(Qt::NoPen);
painter.setBrush(QColor("#333340"));
painter.drawRoundedRect(barRect, 4, 4);
// 进度条前景
if (m_progress > 0) {
QRectF valueRect(barRect.left(), barRect.top(),
barRect.width() * m_progress / 100.0,
barRect.height());
painter.setBrush(QColor("#2D89EF"));
painter.drawRoundedRect(valueRect, 4, 4);
}
}
逐层看。背景层用 fillRect(rect(), ...) 覆盖整个控件,颜色是深色底。边框层先 setPen 再 drawRect,笔宽 1,矩形向内收 1 像素。标题层改了 painter 的字体和画笔颜色,drawText 的矩形是 (12, 8, width()-24, 20),水平左对齐、垂直居中。状态文字层把字体降到 8 点,颜色变灰,矩形下移到 y=32,高度 16。进度条背景层用 QRectF(12, 54, width()-24, 8),先 setPen(Qt::NoPen) 去掉描边,再设画刷颜色,最后 drawRoundedRect 画圆角矩形。前景层只在 m_progress > 0 时画,宽度按比例算,颜色换成蓝色。
注意进度条前景的宽度用了 100.0 而不是 100。如果写成 barRect.width() * m_progress / 100,整数除法在进度很小的时候会把宽度截成 0,1% 的进度条直接看不见。用浮点除数,结果再交给 QRectF,宽度才能保留小数。
3.3 进度条参数表:qBound、浮点宽度与圆角半径
把绘制里用到的参数拉成一张表,改样式时不容易漏。
| 元素 | 位置/尺寸 | 颜色 | 关键参数 |
|---|---|---|---|
| 背景 | rect() 全控件 |
#1E1E2E |
必须铺满,配合 WA_OpaquePaintEvent |
| 边框 | rect().adjusted(1,1,-1,-1) |
#3A3A4A |
笔宽 1,内收 1 像素 |
| 标题 | QRect(12, 8, width()-24, 20) |
#E0E0E0 |
10 点、加粗、左对齐垂直居中 |
| 状态文字 | QRect(12, 32, width()-24, 16) |
#8A8A9A |
8 点、左对齐垂直居中 |
| 进度条背景 | QRectF(12, 54, width()-24, 8) |
#333340 |
圆角半径 4,无描边 |
| 进度条前景 | 高度同背景,宽度按比例 | #2D89EF |
qBound(0,value,100),除以 100.0 |
圆角半径 4 和进度条高度 8 是配套的:半径取高度的一半,两端正好是半圆。半径大于高度一半时,Qt 会按可用尺寸调整,视觉上不再是预期的小圆角。进度值在 setter 里已经用 qBound 夹住,paintEvent 里只判断 m_progress > 0,不用再防负数。状态文字和标题的左右边距都是 12,和进度条左边对齐,视觉上是一条竖线。宽度统一用 width() - 24,控件变窄时文字区域跟着缩,不会画出边界。
4. 代码开发工具中的避坑排查:闪烁、残影、坐标错位与进度不动
自绘控件的故障,现象看着玄学,原因大多落在三个地方:重绘入口、绘制约束、坐标和数值。下面五条是我在 StatusPanel 上真实遇到或排查过的坑,按“现象 → 原因 → 解决”记下来。
4.1 闪烁与残影:开了 WA_OpaquePaintEvent 却没铺满
现象:窗口缩放或进度快速更新时,状态文字后面偶尔出现上一帧的拖影,进度条旧位置留下一条蓝色残边。原因:构造里开了 Qt::WA_OpaquePaintEvent,Qt 认为控件完全不透明,跳过了默认背景填充;但 paintEvent 里如果只画了边框、文字和进度条,没有用背景色铺满 rect(),上一帧没被覆盖的像素就留在那里。解决:paintEvent 第一行固定写 painter.fillRect(rect(), QColor("#1E1E2E")),把整个控件区域盖住,再画其他层。如果控件本身需要半透明或圆角外透出父背景,就不要开这个属性,让 Qt 走默认背景填充。这个坑我踩过一次,后来把“开 WA_OpaquePaintEvent 必配 fillRect(rect())”当成硬规则。
4.2 进度不动:setter 里少了 update
现象:调用 setProgress(50) 后界面没反应,拖动一下窗口或者切到别的页面再切回来,进度条突然跳到 50。原因:setter 只改了 m_progress,没有调用 update()。paintEvent 不会因为成员变量变化自动触发,必须有人向 Qt 请求重绘。解决:每个会改变绘制结果的 setter 末尾都加 update()。update() 是异步请求,连续多次调用会合并,不会每改一次就同步画一遍,所以不用担心性能。排查时先看 setter 有没有 update(),再看控件是否被其他全屏控件遮住、是否在非主线程里改 UI。StatusPanel 的两个 setter 都带 update(),这是最低要求。
4.3 坐标错位:把父窗口坐标带进子控件
现象:StatusPanel 放进主窗口后,进度条偏到窗口左上角,或者标题跑到控件外面。原因:paintEvent 里混用了父窗口坐标。QPainter painter(this) 的原点在控件左上角,但代码里如果用了 mapToParent() 的结果,或者拿父窗口的 rect() 来算位置,坐标系就错位了。解决:paintEvent 内只用控件局部坐标,位置基于 rect()、width()、height(),边距用固定数字。需要和父窗口换算时,在事件处理或布局代码里做,不要带进绘制函数。边框用 rect().adjusted(1,1,-1,-1) 也是局部坐标,不要改成父窗口矩形。
4.4 进度条消失与越界:整数除法和 qBound
现象一:进度设成 1 或 2 时,进度条前景完全看不见,设成 50 才出现。原因:宽度计算用了整数除法,barRect.width() * m_progress / 100 在进度很小时结果被截成 0。解决:除数写成 100.0,让表达式按浮点计算,再交给 QRectF。现象二:进度传 120 时前景条画出右边界,传 -5 时宽度变成负数。原因:setter 没有夹取范围。解决:m_progress = qBound(0, value, 100);,把输入收口在 setter 里,paintEvent 不用重复判断上下界。这两个问题都出在数值入口,绘制层反而不用改。
4.5 排查顺序:先看重绘入口再看绘制参数
遇到自绘控件不刷新或闪烁,我一般按这个顺序查:先确认 setter 有没有调用 update(),再看 paintEvent 有没有被触发,最后看绘制参数。如果界面在拖动窗口后才更新,八成是少了 update();如果更新时出现拖影,先检查 WA_OpaquePaintEvent 和 fillRect(rect()) 是否配套;如果位置不对,先检查坐标是不是混用了父窗口;如果进度条宽度异常,先看除数是 100 还是 100.0,再看 setter 有没有 qBound。这个顺序能避免一上来就怀疑抗锯齿,把简单问题复杂化。
5. 代码开发工具里的验证与进阶:把 StatusPanel 变成可复用控件
StatusPanel 写完后,别只看默认的 0% 状态。我一般会写一个最小的调用片段,把边界值跑一遍,确认 setter、重绘和绘制参数都对得上。
cpp复制StatusPanel *panel = new StatusPanel(parent);
panel->setStatusText(QStringLiteral("同步中"));
panel->setProgress(1); // 看 1% 时前景条是否可见
panel->setProgress(50); // 看半程宽度
panel->setProgress(100); // 看右边界是否贴合
panel->setProgress(120); // 看 qBound 是否夹到 100
panel->setProgress(-5); // 看是否夹到 0
这段调用的重点是输入顺序:先设文字再设进度,观察每次 update() 后界面是否只刷新一次;1% 用来验证浮点宽度,50% 看比例,100% 看右边界,120 和 -5 看 qBound 是否生效。验证时把窗口拉宽拉窄,看标题、状态文字和进度条是否还保持 12 像素左边距,文字有没有被裁掉。如果都稳定,这个控件就可以从演示代码里拿出来复用。
复用的时候,我习惯把 12、8、20、54、8、4 这些数字和颜色从 paintEvent 里提出来,变成成员常量或样式参数。不是为了过度设计,而是下次改主题时不用在绘制语句里逐行找。WA_OpaquePaintEvent 和 fillRect(rect()) 仍然成对保留,setter 里的 update() 也不省。从那以后我每次给自绘控件加 WA_OpaquePaintEvent,都先强制自己在 paintEvent 第一行写 fillRect(rect(), ...),再写别的,这个习惯比事后调闪烁省太多时间。希望帮到你。
