PyQt6方法Union[QBrush等]类型参数正确传参方式咨询

你看到的Union[QBrush, QColor, GlobalColor, int, QGradient]是静态类型提示标注，不是要求你传入typing.Union类型的对象。
这类标注的含义非常简单：对应位置的参数/属性，支持传入Union括号内任意一种类型的合法实例即可。IDE的参数悬浮提示直接把整个Union类型显示出来没有额外说明，是很多刚接触PyQt6的开发者都会踩的理解误区。
PyQt6里大量出现这类联合类型标注，本质是对Qt C层接口的适配：C层接口支持隐式类型转换、多重重载，Python侧的类型桩文件（.pyi）就把所有兼容的入参类型全部列在Union里，方便IDE做补全和类型检查。你提到的前景、背景相关接口，底层最终都会把传入的合法值统一转换为QBrush实例处理，不需要你手动做类型转换。

以你提到的两个接口为例，所有在Union列表里的类型都可以直接传入：

from PyQt6.QtWidgets import QApplication
from PyQt6.QtGui import QStandardItem, QBrush, QColor, QLinearGradient
from PyQt6.QtCore import Qt, QStyleOptionViewItem
import sys

# PyQt6程序必须先创建QApplication实例
app = QApplication(sys.argv)

1. 调用setForeground方法的几种合法传参 #

item = QStandardItem("测试列表项")

# 传法1：传QColor实例，最常用的纯色传法
item.setForeground(QColor(255, 0, 0, 180)) # 半透明红色

# 传法2：传Qt内置GlobalColor枚举值（对应Union里的GlobalColor/int类型）
item.setForeground(Qt.GlobalColor.darkBlue)

# 传法3：传自定义QBrush实例，适合需要填充样式、纹理的场景
pattern_brush = QBrush(QColor(0, 128, 0), Qt.BrushStyle.Dense4Pattern)
item.setForeground(pattern_brush)

# 传法4：传QGradient子类实例，支持渐变效果（QGradient是抽象基类，实际传它的线性/径向/锥形渐变子类即可）
linear_grad = QLinearGradient(0, 0, 200, 0)
linear_grad.setColorAt(0, Qt.GlobalColor.red)
linear_grad.setColorAt(0.5, Qt.GlobalColor.yellow)
linear_grad.setColorAt(1, Qt.GlobalColor.green)
item.setForeground(linear_grad)

2. 给backgroundBrush属性赋值的规则 #

类属性的类型标注和方法参数规则完全一致，直接赋Union内任意类型的合法值即可：

opt = QStyleOptionViewItem()
# 赋值QColor
opt.backgroundBrush = QColor(245, 245, 245)
# 也可以赋值QBrush、GlobalColor、渐变对象，和上面setForeground的传法完全通用
# opt.backgroundBrush = QBrush(...)
# opt.backgroundBrush = Qt.GlobalColor.white
# opt.backgroundBrush = QLinearGradient(...)

• 完全不需要导入typing.Union构造对象传入，这是对类型提示的典型误解：Union是类型定义语法，只给IDE、类型检查工具做静态校验用，和运行时传参没有任何关系。
• 虽然标注里支持int类型，但绝对不要直接传裸整数。标注里列int本质是因为GlobalColor是IntEnum的子类，类型检查工具会把枚举值识别为int类型，实际开发直接写死数字传参，过两周你自己都记不住数字对应什么颜色，且跨Qt版本的兼容性极差。
• PyQt6运行时自带类型校验，如果传入了Union列表外的类型，会直接抛出TypeError，不需要你手动做类型兼容判断。

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