QT Creator中ListWidget超出容量时无法显示项的问题排查

现象 #

向QListWidget中添加自定义Card部件时：

• 项数（如5个）能完全容纳在ListWidget可视区域内，所有Card正常显示
• 项数超过可视范围（如6个及以上），所有项直接消失，无法滚动查看

相关代码 #

主窗口添加项逻辑 #

for(int i=0; i<6;++i) {
    auto item = new QListWidgetItem();
    auto widget = new Card(doctorName, doctorDepartment, doctorPicture);
    item->setSizeHint(widget->sizeHint());
    ui->listWidget->addItem(item);
    ui->listWidget->setItemWidget(item,widget);
} 
ui->listWidget->setSpacing(5);

Card类实现 #

Card::Card(QString DoctorN, QString DoctorD, QString DoctorP, QWidget *parent):
    QWidget(parent),
    ui(new Ui::Card)
{
    ui->setupUi(this);
    ui->labelBackground->setStyleSheet("image: url(:/backgrounds/Resources/Backgrounds/BCKGR_GreyCard.png);");
    DoctorName=DoctorN;
    DoctorDepartment=DoctorD;
    DoctorPicture=DoctorP;
    ui->labelDepartment->setText(DoctorDepartment);
    ui->labelDoctorName->setText(DoctorName);
    setDoctorPicture();
}

QSize Card::sizeHint() const {
return QSize(432, 114); 
}

ListWidget初始化设置 #

ui->listWidget->setStyleSheet("background-color: rgba(255, 255, 255, 0);"
                              "color: rgba(255, 255, 255, 0);"
                              "border-color: rgba(255, 255, 255, 0);"
                              "image: none;");
ui->listWidget->setGeometry(390,150,501,561);

原因分析 #

1. 总高度超出后的布局计算异常：每个Card高度114，加上5的间距，6个项总高度为6*114 + 5*5 = 709，远大于ListWidget的561高度。QListWidget在处理超出可视范围的自定义Widget时，可能因内部布局计算错误导致所有项渲染失效。
2. 样式表冗余设置干扰：ListWidget的color和border-color设为全透明，虽不直接影响自定义Widget，但可能干扰了控件内部的项状态绘制逻辑，引发滚动时的渲染异常。
3. sizeHint与实际尺寸不匹配：虽然重写了sizeHint，但若Card内部.ui文件的布局没有正确约束控件尺寸，实际渲染尺寸可能和sizeHint返回值不一致，导致ListWidget的项尺寸计算混乱。

解决办法 #

1. 强制启用滚动功能：手动设置滚动模式和滚动条策略，避免自动计算导致的问题：

ui->listWidget->setVerticalScrollMode(QAbstractItemView::ScrollPerItem);
ui->listWidget->setVerticalScrollBarPolicy(Qt::ScrollBarAlwaysOn);

2. 调整spacing设置时机：先设置间距再添加项，避免布局计算延迟：

ui->listWidget->setSpacing(5);
for(int i=0; i<6;++i) {
    auto item = new QListWidgetItem();
    auto widget = new Card(doctorName, doctorDepartment, doctorPicture);
    item->setSizeHint(widget->sizeHint());
    ui->listWidget->addItem(item);
    ui->listWidget->setItemWidget(item,widget);
} 

3. 简化样式表：只保留必要的背景透明设置，移除冗余的透明属性：

ui->listWidget->setStyleSheet("background-color: rgba(255, 255, 255, 0);");

4. 校验Card内部布局：检查Card的.ui文件，确保内部控件有正确的尺寸约束（固定尺寸或合理的拉伸策略），保证sizeHint返回值和实际渲染尺寸一致。

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