Qt6 - 创建列表框控件

创建列表框控件（QListWidget）

一、控件介绍

列表框控件 QListWidget 是 Qt 提供的一种用于展示“列表形式数据”的控件，它以垂直排列的方式显示多个项目，每个项目通常是一个文本项，但也可以包含图标、复选框甚至自定义部件。
QListWidget 继承自 QListView，并使用内部的模型结构来管理数据，但相比于 QListView 更加简单，内部自动管理项目，不需要开发者自己维护数据模型。

列表框的每一行是一个 QListWidgetItem，它表示一个单独的条目，可设置文本、图标、字体、背景色、前景色等。
QListWidget 非常适用于简单的项目展示、选项选择、数据浏览等需要分行显示内容的场景。

二、控件用途说明

1. 展示多行内容
   列表框非常适合展示多条信息，例如日志输出、文件列表、菜单条目、数据行等。
2. 单选或多选项目
   QListWidget 支持单选、多选、扩展选择等多种模式，可以用于需要选择若干项的场景。
3. 允许动态添加与删除项目
   可以在程序运行过程中用代码动态插入、删除或修改项目，使其适用于实时数据展示。
4. 支持图标显示
   每个项目都能设置图标，适合文件浏览器、音乐列表等需要更丰富展示内容的控件。
5. 支持拖拽排序
   启用拖拽功能后，用户可以通过拖动列表项来自由调整顺序。
6. 支持嵌入自定义控件
   可以往某个行项目内嵌入 QWidget，实现高度自定义的外观，例如开关按钮、图片、复杂布局等。

三、相关内容补充

1. 基本使用方式

创建 QListWidget 并添加到界面布局：

QListWidget* listWidget = new QListWidget(this);
listWidget->addItem("项目 1");
listWidget->addItem("项目 2");
listWidget->addItem("项目 3");

添加图标：

QListWidgetItem* item = new QListWidgetItem(QIcon(":/icons/file.png"), "文件1");
listWidget->addItem(item);

删除项目：

delete listWidget->takeItem(0);

设置多选模式：

listWidget->setSelectionMode(QAbstractItemView::MultiSelection);

2. 使用 QListWidgetItem 控制项目外观

设置字体和颜色：

QListWidgetItem* item = new QListWidgetItem("高亮项目");
item->setFont(QFont("微软雅黑", 12, QFont::Bold));
item->setForeground(Qt::red);
listWidget->addItem(item);

设置背景色：

item->setBackground(Qt::yellow);

3. 设置拖拽排序

listWidget->setDragDropMode(QAbstractItemView::InternalMove);

用户可通过拖拽项目来调整顺序。

4. 响应列表框事件

常用信号包括：

• itemClicked(QListWidgetItem*)
• itemDoubleClicked(QListWidgetItem*)
• currentItemChanged(QListWidgetItem*, QListWidgetItem*)

连接示例：

connect(listWidget, &QListWidget::itemClicked, this, [](QListWidgetItem* item) {
    qDebug() << "点击项目：" << item->text();
});

5. 自定义控件嵌入

将一个 QWidget 作为列表项内容：

QWidget* widget = new QWidget();
QLabel* label = new QLabel("自定义内容");
QPushButton* btn = new QPushButton("按钮");

QHBoxLayout* layout = new QHBoxLayout(widget);
layout->addWidget(label);
layout->addWidget(btn);

QListWidgetItem* item = new QListWidgetItem(listWidget);
listWidget->addItem(item);
listWidget->setItemWidget(item, widget);

这种方式适合复杂界面展示，例如聊天消息气泡、商品项、播放列表等。

6. 与 Model/View 模型的关系

虽然 QListWidget 使用内部模型，不需要手动管理数据，但在需要处理大量数据或复杂数据结构时，可以考虑使用 QListView + QAbstractListModel 来获得更灵活和更高性能的解决方案。

下面我们就创建一个列表框控件

首先定义成员变量

QListWidget* listWidget;

实例化控件并添加列表项

listWidget = new QListWidget(this);
listWidget->setGeometry(10, 380, 150, 200);
listWidget->addItems({ "列表项一", "列表项二", "列表项三", "列表项四", "列表项五" });

这里用到的也是addItems()方法