PyQt5中如何在QFrame组件内正确调用paintEvent绘制环形进度条

你遇到的两个问题分别对应PyQt5自定义绘制的两个典型误用：

• 直接在MainWindow的paintEvent中实现环形进度条绘制逻辑：Qt所有paintEvent内的绘制操作默认以当前接收事件的组件左上角为坐标原点，哪怕你手动调用days组件的paintEvent，当前激活的绘制设备依然是主窗口，绘制内容必然会落在主窗口区域，不会出现在QFrame内部。另外手动调用组件的paintEvent本身就是错误用法，该方法由Qt事件循环自动调度，手动触发不会绑定正确的绘制上下文。
• 封装CircularProgress继承QWidget后设置父组件报错：这类报错基本来自三个实现疏漏：构造函数未正确传递父对象给QWidget父类、paintEvent中QPainter未绑定当前组件实例、未给组件设置合理的初始尺寸导致布局异常。

1. 正确封装环形进度条组件 #

progress.py 实现参考，所有绘制逻辑收敛在组件自身的paintEvent内：

from PyQt5.QtWidgets import QWidget
from PyQt5.QtGui import QPainter, QPen, QColor
from PyQt5.QtCore import Qt, QRectF

class CircularProgress(QWidget):
    def __init__(self, parent=None):
        # 必须将parent传递给父类构造，否则父组件关联失效
        super().__init__(parent)
        self.progress = 0
        # 设置默认最小尺寸，避免被布局压缩到不可见
        self.setMinimumSize(120, 120)

    def set_progress(self, value):
        self.progress = max(0, min(100, value))
        # 值更新后触发重绘，不需要手动调paintEvent
        self.update()

    def paintEvent(self, event):
        painter = QPainter(self)
        # 开抗锯齿
        painter.setRenderHint(QPainter.Antialiasing)
        
        # 绘制背景环
        pen_bg = QPen(QColor("#e0e0e0"), 8)
        painter.setPen(pen_bg)
        rect = QRectF(10, 10, self.width()-20, self.height()-20)
        painter.drawEllipse(rect)

        # 绘制进度环
        pen_prog = QPen(QColor("#2196f3"), 8)
        pen_prog.setCapStyle(Qt.RoundCap)
        painter.setPen(pen_prog)
        # 环形进度从90度位置开始（对应12点钟方向），角度转16进制整数是Qt固定要求
        span_angle = int(-self.progress * 360 * 16 / 100)
        painter.drawArc(rect, 90*16, span_angle)

        painter.end()

2. 主窗口中嵌入组件的正确写法 #

不要硬编码组件位置，给目标days QFrame设置布局后再加入进度条组件，main.py 相关代码参考：

from PyQt5.QtWidgets import QMainWindow, QFrame, QVBoxLayout
from progress import CircularProgress

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.resize(800, 600)

        # 假设这是你已有的days QFrame组件
        self.days_frame = QFrame(self)
        self.days_frame.setFrameShape(QFrame.StyledPanel)
        self.days_frame.setGeometry(50, 50, 200, 200)

        # 给QFrame设置布局，这步不能少
        layout = QVBoxLayout(self.days_frame)
        layout.setContentsMargins(0,0,0,0)
        # 实例化进度条，父组件自动关联为days_frame
        self.progress_bar = CircularProgress(self.days_frame)
        layout.addWidget(self.progress_bar)

        # 测试设置进度
        self.progress_bar.set_progress(65)

• 所有自定义绘制逻辑必须写在对应组件自身的paintEvent方法内，永远不要手动调用任何组件的paintEvent，需要刷新显示统一调用update()方法
• 自定义QWidget子类的构造函数必须接收parent参数并传递给父类构造方法，否则父组件关联逻辑失效
• 嵌入子组件时优先使用布局管理，不要用固定坐标硬编码位置，避免窗口缩放、样式变化导致组件显示异常

常见报错排查：如果遇到QWidget::paintEngine: Should no longer be called报错，优先检查是否在paintEvent方法外部创建了绑定组件的QPainter实例，或者是否手动调用了组件的paintEvent方法。

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