PySide6 QCheckBox stateChanged传递int而非CheckState的问题咨询

在Ubuntu和Windows系统中，通过PIP安装的PySide6 6.4.1版本里，QCheckBox的stateChanged()信号在复选框状态改变时触发事件，但传递的state参数是int类型，而非官方文档所述的Qt.CheckState枚举类型。

测试代码：

from PySide6.QtWidgets import QApplication, QWidget, QCheckBox
from PySide6.QtCore import Qt
import sys

class Window(QWidget):
    def __init__(self):
        super().__init__()

        self.setGeometry(300, 300, 250, 150)
        self.setWindowTitle('QCheckBox')

        checkbox = QCheckBox('Show title', self)
        checkbox.move(20, 20)
        checkbox.toggle()
        checkbox.setTristate(True)
        checkbox.stateChanged.connect(self.onCheckboxChange)

    def onCheckboxChange(self, state):
        # state是int类型，而非Qt.Checked或Qt.Unchecked枚举
        # 与文档描述不符

        print('Qt.Checked type: {}'.format(type(Qt.Checked)))
        print('Event: {}, type: {}'.format(state, type(state)))

        # 因为类型不匹配，标题总是被设为UNKNOWN
        if state == Qt.Unchecked:
            self.setWindowTitle('Unchecked')
        elif state == Qt.PartiallyChecked:
            self.setWindowTitle('PartiallyChecked')
        elif state == Qt.Checked:
            self.setWindowTitle('Checked')
        else:
            self.setWindowTitle('UNKNOWN')

def main():
    app = QApplication(sys.argv)
    window = Window()
    window.show()
    sys.exit(app.exec())

if __name__ == '__main__':
    main()

运行输出：

# 取消勾选复选框时：
Qt.Checked type: <enum 'CheckState'>
Event: 0, type: <class 'int'>    <= 预期应为Qt.Unchecked

# 半选复选框时：
Qt.Checked type: <enum 'CheckState'>
Event: 1, type: <class 'int'>    <= 预期应为Qt.PartiallyChecked

# 勾选复选框时：
Qt.Checked type: <enum 'CheckState'>
Event: 2, type: <class 'int'>    <= 预期应为Qt.Checked

尝试用int(Qt.Checked)将枚举转为int时，触发错误：TypeError: int() argument must be a string, a bytes-like object or a real number, not 'CheckState'。

请问该现象是否为预期行为？

这是PySide6绑定的正常行为，并非bug，原因如下：

• PySide6在传递信号中的枚举类型时，会自动转为对应整数值，这是Qt Python绑定的设计逻辑，和PyQt行为一致。
• 官方文档描述的是C++层面的参数类型，Python绑定做了适配，传递的是枚举对应的数值。

解决方法：

• 直接比较int值和枚举的value属性：比如state == Qt.Unchecked.value，就能正确匹配状态。
• 将传入的int转换为Qt.CheckState枚举：check_state = Qt.CheckState(state)，之后再和枚举成员比较。

修改后的槽函数示例：

def onCheckboxChange(self, state):
    check_state = Qt.CheckState(state)
    print('Qt.Checked type: {}'.format(type(Qt.Checked)))
    print('Event: {}, type: {} | 转换后的枚举: {}'.format(state, type(state), check_state))

    if check_state == Qt.Unchecked:
        self.setWindowTitle('Unchecked')
    elif check_state == Qt.PartiallyChecked:
        self.setWindowTitle('PartiallyChecked')
    elif check_state == Qt.Checked:
        self.setWindowTitle('Checked')
    else:
        self.setWindowTitle('UNKNOWN')

这样就能正常匹配复选框的三种状态，不会出现标题设为UNKNOWN的问题。

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