Qt 高级开发 029： QListWidget从基础条目到自定义微信式列表实战详析

前言

QT 框架之中，ItemView 控件家族为界面列表开发立下基石，ListWidget 作为日常开发高频控件，分列列表样式、图标样式两大形态。小至软件配置面板，大至 IM 聊天联系人列表，皆可依托该控件落地实现。本文由浅入深，由原生图文条目搭建起步，逐层拆解资源导入、布局排版、中文编码排坑、自定义列表项四大实操要点，附核心源码，兼顾原理与落地，助力开发者快速掌握 ListWidget 全套开发逻辑。

一、ListWidget 两种显示形态，适配多场景开发需求

控件分内外两式，一为列表排布，一为图标陈列，各司其职，适配万千 UI 场景。
其一列表模式：对标微信会话列表、系统软件设置菜单栏，竖向罗列文字与配套图标，条理分明，是配置界面首选布局；
其二图标模式：多用于视频会议桌面共享模块，元素以大图标的形式平铺排布，视觉直观，方便快速选择功能窗口。

常规软件配置页面多采用「左 ListWidget + 右侧 TabWidget」组合架构，左侧点击条目，右侧切换对应配置面板，此架构也是迅雷、多款桌面工具配置页通用方案，依托 QT 布局系统便可从零搭建。

二、原生图文 List 条目快速实现：资源配置 + 代码添加条目

2.1 工程与资源文件筹备

先立新工程，定名2-1_2item_project_01，创建带 UI 窗体的空项目，准备配套图标素材。
QT 中图片资源不可直接拖拽使用，需依托 qrc 资源文件统一管理，步骤井然：

1. 右键项目→新建文件→QT Resource File，命名resource.qrc；

2. 文件加载入 Pro 工程后，右键 qrc 文件，选择添加现有文件，全选本地图标批量导入；

原理：qrc 编译后嵌入程序二进制，脱离本地文件路径也可正常加载图片，规避路径失效、资源丢失问题。

2.2 UI 挂载控件与前置编译

打开 UI 设计器，在控件检索栏检索ListWidget拖拽至画布，默认对象名listWidget。
关键实操规范：控件添加后先行编译运行，UI 文件自动生成ui_xxx.h，后续代码可通过 UI 指针直接访问控件对象，免去头文件手动引入报错隐患。

2.3 核心代码：创建图文列表项

QListWidgetItem为列表最小单元，构造函数支持QIcon 图标 + QString 文字双参数重载，依托此构造即可快速生成带图标配置项，核心 C++ 代码如下：

#include<QIcon>#include<QListWidgetItem>voidMainWindow::initListWidgetItem(){// 资源路径固定格式 :/资源目录/图片名，qrc内置资源统一前缀冒号斜杠QString iconPath1=":/res/case.png";QString iconPath2=":/res/env.png";QString iconPath3=":/res/adeter.png";QString iconPath4=":/res/vrm.png";QString iconPath5=":/res/help.png";// 逐个构建列表条目QListWidgetItem*item1=newQListWidgetItem(QIcon(iconPath1),tr("工具选项"));QListWidgetItem*item2=newQListWidgetItem(QIcon(iconPath2),tr("环境"));QListWidgetItem*item3=newQListWidgetItem(QIcon(iconPath3),tr("文本编辑器"));QListWidgetItem*item4=newQListWidgetItem(QIcon(iconPath4),tr("VRM配置"));QListWidgetItem*item5=newQListWidgetItem(QIcon(iconPath5),tr("帮助"));// 将条目挂载至ListWidgetui->listWidget->addItem(item1);ui->listWidget->addItem(item2);ui->listWidget->addItem(item3);ui->listWidget->addItem(item4);ui->listWidget->addItem(item5);}

2.4 中文乱码疑难解析与解决方案

实操中常遇局部中文乱码之困，部分汉字正常展示、部分变为方框乱码，究其根源，源自源码文件编码、QT 运行编码不统一：

1. 源码默认 GBK 编码，QT 内部默认 UTF-8 解析，编码错位致使字符解析异常；

2. 优化方案：代码使用tr()包裹中文字符，在 pro 文件添加编码配置：

# pro文件添加代码，全局指定源码UTF-8编码 CODECFORSRC = UTF-8

改用 UTF-8 保存源码后，绝大多数中文乱码问题迎刃而解。

三、组合页面布局雕琢：左列表 + 右侧分页配置面板

配置页面经典架构：左侧 ListWidget，右侧 TabWidget 分区配置，窗体顶部 Label 标题，底部功能按钮。布局之妙，贵在 Widget 容器嵌套、横竖布局相辅相成。

3.1 布局设计思路

1. 拆分页面为三大模块：顶部标题区、中间主体分区（左列表 + 右分页）、底部按钮区；

2. 零散控件装入独立 Widget 容器，依托 QHBoxLayout 水平布局、QVBoxLayout 竖直布局约束排布；

3. 利用布局弹簧 (QSpacerItem)填充空白，分隔控件间距，控件通过固定最大 / 最小宽高锁定尺寸，避免窗体缩放时布局错乱。

3.2 关键布局优化细节

1. 布局边距优化：默认布局自带内外边距，通过setContentsMargins(0,0,0,0)清除留白，控件无缝对齐；

// 去除布局四边默认间隙QVBoxLayout*vLayout=newQVBoxLayout;vLayout->setContentsMargins(0,0,0,0);

2. 控件尺寸约束：通过setMinimumWidth/setMaximumWidth锁定左侧 List 宽度（如固定 120~200px），保障布局视觉统一；

3. 底部按钮模块限定固定高度，最小高度与最大高度统一设为 50px，防止布局压缩导致按钮消失。

完成布局后，搭配QStackedWidget栈控件，实现左侧列表点击、右侧页面动态切换，ListWidget绑定itemClicked信号，依据条目索引切换栈页面，实现配置页联动。

四、高阶实战：自定义 Widget 列表，复刻微信联系人条目

原生QListWidgetItem仅支持单图标 + 单行文字，难以实现微信联系人「左侧头像、右上昵称、右下消息时间、底部消息预览」多元素复合布局，此时便需自定义 Widget 条目，借setItemWidget将自定义窗体嵌入列表项。

4.1 新建自定义条目 UI 窗体

创建UserItemWidget 类并配套 ui 文件，页面元素拆分：

• 左侧 QLabel：承载用户头像，固定尺寸 100*100；

• 右上 QLabel：展示用户昵称；

• 右侧 QLabel：展示最新消息时间；

• 下方 QLabel：展示消息预览正文。

布局排布：头像与右侧信息区做水平布局；昵称与时间同行加横向弹簧右推时间；昵称行与消息内容做竖直布局，最终整体封装至 Widget。

4.2 UserItem 类简易封装

// UserItem.h#ifndefUSERITEM_H#defineUSERITEM_H#include<QWidget>namespaceUi{classUserItem;}classUserItem:publicQWidget{Q_OBJECTpublic:explicitUserItem(QWidget*parent=nullptr);// 对外接口，动态设置头像、昵称、时间、消息voidsetUserInfo(QString iconPath,QString name,QString time,QString msg);~UserItem();private:Ui::UserItem*ui;};#endif// USERITEM_H

// UserItem.cpp#include"UserItem.h"#include"ui_UserItem.h"#include<QPixmap>UserItem::UserItem(QWidget*parent):QWidget(parent),ui(newUi::UserItem){ui->setupUi(this);// 固定条目整体尺寸，与前期UI测量423*147保持一致this->setFixedSize(423,147);}voidUserItem::setUserInfo(QString iconPath,QString name,QString time,QString msg){ui->labHead->setPixmap(QPixmap(iconPath).scaled(100,100,Qt::KeepAspectRatio));ui->labName->setText(name);ui->labTime->setText(time);ui->labMsg->setText(msg);}UserItem::~UserItem(){deleteui;}

4.3 将自定义控件挂载至 ListWidget

依托QListWidget::setItemWidget(QListWidgetItem* item,QWidget* widget)接口绑定自定义条目，完整调用代码：

#include"UserItem.h"voidMainWindow::addCustomListItem(){// 创建空列表条目QListWidgetItem*pItem=newQListWidgetItem;// 创建自定义用户条目控件UserItem*userWidget=newUserItem;// 填充用户数据userWidget->setUserInfo(":/res/head1.png","张三","15:32","今晚聚餐吗？");// 设置条目高度与自定义窗体匹配pItem->setSizeHint(QSize(423,147));// 关键API：绑定控件与列表项ui->listWidget->setItemWidget(pItem,userWidget);// 插入列表ui->listWidget->addItem(pItem);}

4.4 细节优化补充

1. ListWidget 宽度不足会挤压自定义条目，按需调整控件宽度至 450px 左右；

2. 批量添加多条联系人时，循环创建 Item 与 UserItem 对象即可快速生成完整聊天列表；

3. 进阶拓展：可自定义条目点击变色、右键菜单、条目置顶拖拽，完善 IM 列表全功能。

五、文末小结

观 ListWidget 之用法，由简入繁，始则原生图文条目，次则整页布局搭建，终至自定义复合条目。基础条目依托系统自带 Item 快速开发，适配配置类简单列表；复杂 IM 列表依靠 Widget 封装 + setItemWidget 落地，灵活度拉满。QT 布局系统虽参数繁杂，熟稔边距、弹簧、尺寸约束三者，无论产品需求何等样式，皆可按设计稿还原界面。后续可延伸学习 QListView+Model 架构，实现百万级海量列表高性能渲染，突破 ListWidget 数据量大后的性能瓶颈。