PyQt5 QListWidget子控件引用及类属性报错问题排查

报错的核心原因是__init__方法内的代码执行顺序错误，和属性是否声明没有关系。
Python类实例的属性是按__init__内代码的执行顺序逐行挂载的，执行到访问self.parameterWidget的逻辑时，该属性的赋值代码还未运行，就会抛出AttributeError。
最高发的触发场景：先创建comboBox实例，紧接着就绑定了currentTextChanged信号，之后才编写创建self.parameterWidget的代码。当给comboBox添加第一个选项时，Qt会自动触发一次currentTextChanged信号，此时绑定的updateSelf方法会立刻执行，而self.parameterWidget还没被创建，直接触发报错。
封装类的方案本身是解决自定义列表项子控件引用问题的正确思路，只要调整执行顺序、按规范写实例方法即可实现需求。

代码顺序规范 #

featureItemInstance类的__init__方法必须严格遵守以下执行顺序，不能颠倒：

• 调用父类构造方法
• 创建所有子控件实例，全部挂载为self.开头的实例属性
• 完成布局配置，将所有子控件添加到对应布局中
• 绑定所有信号槽
• 主动调用updateSelf初始化控件状态

参考实现框架：

from PyQt5.QtWidgets import QWidget, QVBoxLayout, QComboBox, QLabel
class featureItemInstance(QWidget):
    def __init__(self, config: dict, parent=None):
        super().__init__(parent)
        # 存传入的配置字典为实例属性，供updateSelf调用
        self.item_config = config

        # 创建所有子控件，全部挂self属性
        self.comboBox = QComboBox(self)
        self.comboBox.addItems(config.keys())
        self.parameterWidget = QWidget(self)
        self.tagLabel = QLabel(self)

        # 配置布局
        self.main_layout = QVBoxLayout(self)
        self.main_layout.addWidget(self.comboBox)
        self.main_layout.addWidget(self.parameterWidget)
        self.main_layout.addWidget(self.tagLabel)

        # 所有控件创建完成后，再绑定信号
        self.comboBox.currentTextChanged.connect(self.updateSelf)
        # 最后初始化状态
        self.updateSelf()

updateSelf方法实现 #

所有子控件直接通过self.前缀引用即可，每个列表项实例的属性完全独立，不会出现跨控件串扰的问题：

def updateSelf(self, current_text=None):
        # 没传参时主动取当前选中值，兼容初始化调用和信号传参两种场景
        if not current_text:
            current_text = self.comboBox.currentText()
        current_cfg = self.item_config.get(current_text, {})
        
        # 按配置折叠/展开参数区
        self.parameterWidget.setVisible(current_cfg.get("show_param", False))
        # 设置标签文本
        self.tagLabel.setText(current_cfg.get("tag_text", ""))

挂载到QListWidget的注意事项 #

向列表添加自定义项时，需要给QListWidgetItem设置和自定义控件匹配的尺寸，避免控件显示不全：

# 批量添加列表项的逻辑
for feature_cfg in feature_config_list:
    list_item = QListWidgetItem(ui.featureListWidget)
    item_widget = featureItemInstance(feature_cfg)
    # 给列表项设置匹配尺寸
    list_item.setSizeHint(item_widget.sizeHint())
    ui.featureListWidget.setItemWidget(list_item, item_widget)

• 如果需要在comboBox创建后提前添加选项、但暂时不想触发信号，可以在添加选项前调用self.comboBox.blockSignals(True)，等所有控件创建完成、信号绑定前再调用self.comboBox.blockSignals(False)解除阻塞。
• 不要依赖findChild、全局变量等方式查找子控件，通过self.访问实例属性是最稳定的引用方式，不会受控件层级变化影响。

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