如何在PySide6中自定义QListWidgetItem类？

你的代码出现空白项的核心原因是对QListWidgetItem的定位错误：QListWidgetItem是数据容器，并非可视化组件，不能直接在其中创建布局和控件。正确的做法是将自定义Widget与QListWidgetItem绑定，通过QListWidget的setItemWidget()方法关联显示。另外你的代码还存在变量名拼写错误（self.imageLabel、self.layerMaskLabel未定义，应对应self.imageLabel1和self.imageLabel2）。

修正后的完整代码 #

import sys
from PySide6.QtWidgets import (QMainWindow, QHBoxLayout, QListWidget, 
                               QListWidgetItem, QLabel, QWidget)
from PySide6.QtGui import QPixmap
from PySide6 import QtWidgets


# 自定义显示用的Widget，包含两张图片布局
class CustomListItemWidget(QWidget):
    def __init__(self, img_path1, img_path2, parent=None):
        super().__init__(parent)
        # 创建图片标签
        self.imageLabel1 = QLabel()
        self.imageLabel2 = QLabel()
        # 设置图片并缩放，避免尺寸过大
        pixmap1 = QPixmap(img_path1).scaled(80, 80)
        pixmap2 = QPixmap(img_path2).scaled(80, 80)
        self.imageLabel1.setPixmap(pixmap1)
        self.imageLabel2.setPixmap(pixmap2)
        # 构建水平布局
        layout = QHBoxLayout(self)
        layout.addWidget(self.imageLabel1)
        layout.addWidget(self.imageLabel2)
        # 设置Widget固定高度，保证Item显示正常
        self.setFixedHeight(100)


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Rescue Creator")
        self.listWidget = QListWidget()

        # 添加第一个自定义项
        item1 = QListWidgetItem(self.listWidget)
        widget1 = CustomListItemWidget("image1.jpg", "image2.jpg")
        self.listWidget.setItemWidget(item1, widget1)
        # 设置Item尺寸适配Widget
        item1.setSizeHint(widget1.sizeHint())

        # 添加第二个自定义项
        item2 = QListWidgetItem(self.listWidget)
        widget2 = CustomListItemWidget("image1.jpg", "image2.jpg")
        self.listWidget.setItemWidget(item2, widget2)
        item2.setSizeHint(widget2.sizeHint())

        self.setCentralWidget(self.listWidget)


if __name__ == "__main__":
    app = QtWidgets.QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

通用实现步骤 #

1. 创建自定义显示Widget：继承QWidget，在其中构建布局和所需控件（如图片、文本、按钮等），根据需求设置控件样式和大小。
2. 创建QListWidgetItem：作为数据载体，添加到QListWidget中。
3. 绑定Widget与Item：调用QListWidget.setItemWidget(item, custom_widget)，将自定义Widget挂载到Item上。
4. 设置Item尺寸：通过item.setSizeHint(widget.sizeHint())让Item适配Widget的大小，避免显示异常。

如果需要给Item存储额外业务数据，有两种方式：

• 直接继承QListWidgetItem，扩展属性存储数据；
• 使用item.setData(Qt.UserRole, 自定义数据)方法存储，后续通过item.data(Qt.UserRole)获取。

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