【Qt开发】多元素类控件（一）-＞ QListWidget
目录
1 -> 概述
2 -> 核心属性
3 -> 核心方法
4 -> 核心信号
5 -> 内置的视图与交互功能
6 -> 数据管理与操作
7 -> 信号与槽
8 -> 代码示例
9 -> 总结
1 -> 概述
在构建图形用户界面时，展示和管理列表数据是一项极其常见的任务。无论是文件列表、播放队列、联系人名单，还是一系列可配置的选项，都需要一个直观、交互性强的控件来呈现。Qt 框架中的 QListWidget 正是为满足这一需求而设计的强大工具，它提供了一个高度集成且易于使用的“模型-视图”组件，让开发者能够快速构建出功能丰富的列表界面。
QListWidget 可以理解为是一个增强版的列表框。它的核心单元是“项”，即 QListWidgetItem。每一个项不仅仅是一个简单的文本标签，而是一个可以承载丰富内容的容器。开发者可以为每个项设置文本、图标，甚至可以自定义其字体、颜色和对齐方式。这种灵活性使得 QListWidget 能够展示出远比纯文本列表更加生动和信息丰富的界面。
更重要的是，QListWidget 将数据（项）与显示（视图）紧密地封装在一起，提供了一个经典的“项视图”（Item View）实现。对于许多常见的应用场景，这种高度集成的设计避免了使用更底层、更复杂的“模型/视图”架构（如 QListView 搭配 QStandardItemModel），极大地简化了开发流程。
2 -> 核心属性
| 属性 | 说明 |
| currentRow | 当前被选中的是第几行 |
| count | 一共有多少行 |
| sortingEnabled | 是否允许排序 |
| isWrapping | 是否允许换行 |
| itemAlignment | 元素的对齐方式 |
| selectRectVisible | 被选中的元素矩形是否可见 |
| spacing | 元素之间的间隔 |
3 -> 核心方法
| 方法 | 说明 |
| addItem(const QString& label) addItem(QListWidgetItem* item) | 列表中添加元素 |
| currentItem() | 返回 QListWidgetItem* 表示当前选中的元素 |
| setCurrentItem(QListWidgetItem* item) | 设置选中哪个元素 |
| setCurrentRow(int row) | 设置选中第几行的元素 |
| insertItem(const QString& label, int row) insertItem(QListWidgetItem* item, int row) | 在指定的位置插入元素 |
| item(int row) | 返回 QListWidgetItem* 表示第 row 行的元素 |
| takeItem(int row) | 删除指定行的元素，返回 QListWidgetItem* 表示是哪个元素被删除了 |
4 -> 核心信号
| 方法 | 说明 |
| currentItemChanged(QListWidgetItem* current, QListWidgetItem* old) | 选中不同元素时会触发，参数是当前选中的元素和之前选中的元素 |
| currentRowChanged(int) | 选中不同元素时会触发，参数是当前选中元素的行数 |
| itemClicked(QListWidgetItem* item) | 点击某个元素时触发 |
| itemDoubleClicked(QListWidgetItem* item) | 双击某个元素时触发 |
| itemEntered(QListWIdgetItem* item) | 鼠标进入元素时触发 |
上述介绍中涉及到一个关键的类，QListWIdgetItem
这个类表示 QListWidget 中的一个元素
核心方法如下，本质上就是一个 “文本 + 图标” 构成的
| 方法 | 说明 |
| setFont | 设置字体 |
| setIcon | 设置图标 |
| setHidden | 设置隐藏 |
| setSizeHint | 设置尺寸 |
| setSelected | 设置是否选中 |
| setText | 设置文本 |
| setTextAlignment | 设置文本对齐方式 |
5 -> 内置的视图与交互功能
QListWidget 开箱即用地提供了多种视图模式和用户交互功能，这些都是其吸引力的重要组成部分。
-
视图模式：它主要支持两种显示模式：
-
列表模式：项以垂直滚动的单列形式呈现，这是最经典和常见的样式，适用于大多数清单类场景。
-
图标模式：项以图标加描述文字的形式排列，类似于操作系统中的文件浏览器视图，非常适合用于展示图片缩略图、工具集或文档集合。
-
-
选择模式：控件允许灵活地配置项的选择行为。开发者可以设定用户是只能选择单个项，还是可以通过键盘和鼠标选择多个不连续或连续的项。这种灵活性对于需要批量操作（如删除多个文件、选择多首歌曲）的功能至关重要。
-
编辑触发：
QListWidget支持内联编辑。用户可以通過双击项（或其他预设方式）直接进入编辑状态，修改项的文本内容。这一功能为实现诸如重命名文件、修改任务名称等操作提供了极大的便利。 -
拖放操作：这是
QListWidget的一个高级特性。它内置了对拖放的支持，允许用户在同一个列表控件内、甚至在不同QListWidget之间或与其他支持拖放的控件之间，通过鼠标拖拽来移动或复制项。这对于实现自定义排序、整理分类等交互逻辑来说，是一个强大的工具。
6 -> 数据管理与操作
在底层，QListWidget 管理着一个 QListWidgetItem 的列表。开发者可以通过其提供的接口，轻松地对列表进行动态管理：
-
增：可以在列表的末尾、指定行号或指定项之后插入新的项。
-
删：可以移除单个指定的项，或一次性清空整个列表。
-
改：除了编辑文本，还可以随时修改任何项的图标、状态等属性。
-
查：可以获取当前选中的项、根据文本内容查找项，或遍历整个列表。
这种直观的数据管理方式，使得 QListWidget 非常适用于那些数据量不是极其庞大、且逻辑相对简单的场景。
7 -> 信号与槽
QListWidget 通过 Qt 的信号与槽机制，能够及时地对用户的各类操作做出响应。当用户与列表交互时，控件会发出相应的信号。例如：
-
当用户点击或通过键盘切换选项时，会发出
currentItemChanged信号。 -
当用户双击某个项时，会发出
itemDoubleClicked信号。 -
当用户开始编辑一个项或结束编辑时，也会发出相应的信号。
开发者可以将这些信号连接到自定义的槽函数上，从而执行相应的业务逻辑，如加载项对应的详细信息、启动某项任务或保存编辑后的内容。
8 -> 代码示例
1. 在界面上创建一个ListView，右键 变形为 ListWidget，再创建一个 lineEdit 和两个 PushButton。
2. 编写 widget.cpp，在构造函数中添加初始元素
#include "widget.h"
#include "ui_widget.h"#include <QDebug>Widget::Widget(QWidget *parent): QWidget(parent), ui(new Ui::Widget)
{ui->setupUi(this);ui->listWidget->addItem("MG卡沙");ui->listWidget->addItem("MG卡牛");ui->listWidget->addItem("RG海牛");}Widget::~Widget()
{delete ui;
}
3. 编写 listWidget 的 slot 函数
此处需要判定 current 和 previous 非空，初始情况下是没有元素选中的，这就会导致这两个指针可能为 NULL
void Widget::on_listWidget_currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)
{if (current != nullptr){qDebug() << "当前选中的元素: " << current->text();}if (previous != nullptr){qDebug() << "上次选中的元素: " << previous->text();}
}4. 编写按钮的 slot 函数
void Widget::on_pushButton_insert_clicked()
{const QString& value = ui->lineEdit->text();ui->listWidget->addItem(value);
}void Widget::on_pushButton_delete_clicked()
{int row = ui->listWidget->currentRow();if (row < 0){return;}ui->listWidget->takeItem(row);
}
5. 运行代码，观察效果，可以看到，可以对 ListWidget 内的元素进行添加和删除操作
9 -> 总结
QListWidget 是 Qt 工具箱中一个非常实用且功能全面的控件。它将数据管理、视图渲染和用户交互完美地融合在一个易于使用的类中。对于大多数中小型列表需求，它提供了快速实现的原型能力和丰富的交互特性。通过理解其核心概念、视图模式、交互方式以及与信号槽的配合，开发者可以高效地构建出直观、动态的列表式用户界面，从而极大地提升应用程序的体验。
感谢各位大佬支持！！！
互三啦！！！