我之前在PyQt4里做自定义形状窗口的时候，也踩过mask()方法失效的坑，特别理解你那种明明按文档写了但只出半透明的郁闷。咱们来一步步搞清楚问题出在哪，以及怎么解决：

一、为什么mask()方法会失效？ #

这几个原因是最常见的：

• QWebView渲染异步性：PyQt4里的WebKit渲染是异步的，如果你在页面还没加载完成时就调用mask()，获取的pixmap要么是空的，要么还没包含网页的透明区域，自然无法生成正确遮罩。
• 半透明与遮罩的冲突：如果你的窗口提前设置了setWindowOpacity()，这个全局半透明属性会覆盖mask()的像素级遮罩效果，导致窗口只会呈现半透明状态，而不是自定义形状。
• 错误的pixmap来源：直接取QWebView的pixmap会包含窗口本身的框架区域，而不是网页实际渲染的内容，应该从viewport()获取网页的渲染结果。
• QWidget背景未透明：普通QWidget默认有不透明背景，即使你加载了带透明的图片，背景也会覆盖透明区域，导致mask()无法识别需要遮罩的部分。

二、PyQt4下的可行解决办法 #

方案1：针对QWebView的自定义形状实现 #

核心思路是等页面加载完成后，从viewport获取正确的渲染内容，再生成遮罩：

from PyQt4.QtGui import *
from PyQt4.QtCore import *
from PyQt4.QtWebKit import *

class TransparentWebWindow(QWebView):
    def __init__(self):
        super(TransparentWebWindow, self).__init__()
        # 设置无边框窗口
        self.setWindowFlags(Qt.FramelessWindowHint)
        # 开启WebView背景透明
        self.page().setBackgroundColor(Qt.transparent)
        # 加载带透明背景的HTML（本地或在线都可以）
        self.load(QUrl("file:///path/to/your/transparent_page.html"))
        # 等页面完全加载后再生成遮罩
        self.loadFinished.connect(self.applyCustomMask)

    def applyCustomMask(self, is_loaded):
        if not is_loaded:
            return
        # 获取网页实际渲染区域的pixmap
        view_pixmap = self.viewport().grab()
        # 把透明像素转换成遮罩用的QBitmap
        mask_bitmap = view_pixmap.createMaskFromColor(Qt.transparent, Qt.MaskOutColor)
        # 应用遮罩
        self.setMask(mask_bitmap)

if __name__ == "__main__":
    app = QApplication([])
    window = TransparentWebWindow()
    window.show()
    app.exec_()

注意：你的HTML页面要设置body { background: transparent; }，确保网页本身是透明的。

方案2：针对普通QWidget的自定义形状实现 #

如果是普通QWidget，要先开启背景透明，再用带alpha通道的图片生成遮罩：

from PyQt4.QtGui import *
from PyQt4.QtCore import *

class CustomShapeWidget(QWidget):
    def __init__(self):
        super(CustomShapeWidget, self).__init__()
        self.setWindowFlags(Qt.FramelessWindowHint)
        # 开启Widget背景透明
        self.setAttribute(Qt.WA_TranslucentBackground)
        # 加载带透明通道的形状图片
        self.shape_pixmap = QPixmap("custom_shape.png")
        self.resize(self.shape_pixmap.size())
        # 生成并应用遮罩
        self.applyCustomMask()

    def applyCustomMask(self):
        # 从图片的透明区域生成遮罩
        mask_bitmap = self.shape_pixmap.createMaskFromColor(Qt.transparent, Qt.MaskOutColor)
        self.setMask(mask_bitmap)

    def paintEvent(self, event):
        # 绘制自定义形状图片
        painter = QPainter(self)
        painter.drawPixmap(0, 0, self.shape_pixmap)

if __name__ == "__main__":
    app = QApplication([])
    window = CustomShapeWidget()
    window.show()
    app.exec_()

三、关键注意事项 #

• 绝对不要同时使用setWindowOpacity()和setMask()：前者是全局半透明，后者是像素级遮罩，两者冲突会直接导致遮罩失效。
• 确保透明区域是真正的alpha透明：不管是HTML还是图片，必须带有有效的alpha通道，纯色的"透明色"（比如白色模拟透明）是无法被createMaskFromColor()识别的。
• QWebView必须等待loadFinished信号：页面没渲染完就生成遮罩，只会得到空的或错误的pixmap。

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