PyQt5：在Button上方绘图且保留按钮交互功能的实现方案

方案1：自定义按钮类（推荐） #

直接继承QPushButton，重写paintEvent，按「背景→高亮矩形→文字」的顺序绘制，确保文字不被遮挡，同时完全保留按钮原生交互逻辑。

代码示例 #

from PyQt5.QtWidgets import QPushButton, QApplication, QStyleOptionButton
from PyQt5.QtGui import QPainter, QColor
from PyQt5.QtCore import Qt

class RangeButton(QPushButton):
    def __init__(self, text, parent=None):
        super().__init__(text, parent)
        self.weight = 0.0  # 0.0-1.0的权重值
        self.is_highlighted = False

    def set_highlight(self, highlighted, weight=1.0):
        self.is_highlighted = highlighted
        self.weight = max(0.0, min(1.0, weight))
        self.update()  # 触发重绘

    def paintEvent(self, event):
        painter = QPainter(self)
        opt = QStyleOptionButton()
        self.initStyleOption(opt)

        # 1. 绘制按钮基础背景（包含hover、按下等状态样式）
        self.style().drawPrimitive(QStyle.PE_PanelButtonBevel, opt, painter, self)

        # 2. 绘制高亮矩形（根据权重调整透明度）
        if self.is_highlighted:
            # 权重越高，高亮越明显（透明度范围0.2-0.7，避免完全遮挡）
            opacity = 0.2 + self.weight * 0.5
            painter.setOpacity(opacity)
            # 可根据需求修改高亮颜色，比如支持不同颜色的权重映射
            painter.fillRect(self.rect(), QColor(60, 180, 255))

        # 3. 绘制按钮文字（确保文字在最上层，不被遮挡）
        self.style().drawControl(QStyle.CE_PushButtonLabel, opt, painter, self)

if __name__ == "__main__":
    app = QApplication([])
    btn = RangeButton("K♥")
    # 点击按钮切换高亮状态，模拟权重设置
    def toggle_highlight():
        current_state = not btn.is_highlighted
        btn.set_highlight(current_state, weight=0.6 if current_state else 0)
    
    btn.clicked.connect(toggle_highlight)
    btn.show()
    app.exec_()

优势 #

• 完全保留按钮原生交互（点击、hover、按下状态均正常）
• 文字始终在最上层，无遮挡
• 逻辑集中在按钮类内部，方便批量创建和管理范围按钮

方案2：独立覆盖层（无需修改按钮类） #

如果不想改动已有QPushButton的代码，可以用一个独立的QWidget作为高亮覆盖层，设置其鼠标事件透明，让点击穿透到下方按钮。

代码示例 #

from PyQt5.QtWidgets import QWidget, QPushButton, QVBoxLayout, QApplication
from PyQt5.QtGui import QPainter, QColor
from PyQt5.QtCore import Qt

class HighlightOverlay(QWidget):
    def __init__(self, target_btn, parent=None):
        super().__init__(parent)
        self.target_btn = target_btn
        self.weight = 0.0
        self.is_highlighted = False
        
        # 关键：设置鼠标事件透明，点击会穿透到下方按钮
        self.setAttribute(Qt.WA_TransparentForMouseEvents)
        # 绑定按钮的位置/大小变化，确保覆盖层始终对齐按钮
        self._sync_with_button()
        target_btn.geometryChanged.connect(self._sync_with_button)

    def _sync_with_button(self):
        # 让覆盖层和按钮位置、大小完全一致
        self.setGeometry(self.target_btn.geometry())

    def set_highlight(self, highlighted, weight=1.0):
        self.is_highlighted = highlighted
        self.weight = max(0.0, min(1.0, weight))
        self.update()

    def paintEvent(self, event):
        if not self.is_highlighted:
            return
        painter = QPainter(self)
        opacity = 0.2 + self.weight * 0.5
        painter.setOpacity(opacity)
        painter.fillRect(self.rect(), QColor(255, 120, 60))

if __name__ == "__main__":
    app = QApplication([])
    container = QWidget()
    layout = QVBoxLayout(container)
    
    # 普通QPushButton
    btn = QPushButton("Q♦")
    layout.addWidget(btn)
    
    # 创建覆盖层并绑定按钮
    overlay = HighlightOverlay(btn, container)
    
    def toggle_highlight():
        current_state = not overlay.is_highlighted
        overlay.set_highlight(current_state, weight=0.7 if current_state else 0)
    
    btn.clicked.connect(toggle_highlight)
    container.show()
    app.exec_()

优势 #

• 无需修改原有按钮代码，适配已有的UI结构
• 覆盖层与按钮完全解耦，可灵活添加/移除

关键注意点 #

1. 权重实现：通过调整透明度或颜色深浅映射权重值，比如权重1.0对应最高透明度，0.0对应无高亮
2. 交互保留：方案2中必须设置WA_TransparentForMouseEvents，否则覆盖层会拦截鼠标事件
3. 文字不遮挡：方案1中通过先画背景、再画高亮、最后画文字的顺序，确保文字在最上层；方案2中因为覆盖层是半透明，文字也能清晰显示

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