当前位置：首页 > news >正文

Qt开发：QListWidget的介绍和使用

news 2025/7/6 7:41:01

文章目录

- 一、QListWidget的简介
- 二、QListWidget的基本用法
- 三、QListWidget的数据操作
- - 2.1 插入数据
  - 2.2 查找数据
  - 2.3 选项设置
- 四、QListWidget的信号与槽

一、QListWidget的简介

QListWidget 是 Qt 框架中用于显示和操作条目列表的控件，它是 QListView 的一个子类，提供了更高层级的封装，允许你以面向 item 的方式管理列表内容。

二、QListWidget的基本用法

#include <QListWidget>
#include <QDebug>MainWindow::MainWindow(QWidget *parent): QWidget(parent)
{this->setFixedSize(800, 600);QListWidget* listWidget = new QListWidget(this);// 添加文本项listWidget->addItem("Apple");listWidget->addItem("Banana");// 添加带图标的项QListWidgetItem* item = new QListWidgetItem(QIcon(":/icons/pineapple.png"), "Pineapple");listWidget->addItem(item);// 设置多选模式listWidget->setSelectionMode(QAbstractItemView::MultiSelection);// 响应点击事件connect(listWidget, &QListWidget::itemClicked, this, [](QListWidgetItem* item){qDebug() << "你点击了: " << item->text();});
}

三、QListWidget的数据操作

2.1 插入数据

2.1.1 void QListWidget::addItem(const QString &label)
作用：用于向列表中添加一个文本条目。
参数：label：要显示的文本内容（QString 类型）。

效果：

在列表末尾添加一个新项，内容为 label。
内部自动创建一个 QListWidgetItem 并加入 QListWidget。

示例用法：

QListWidget* listWidget = new QListWidget(this);// 添加几个条目
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("葡萄");

2.1.2 void QListWidget::addItems(const QStringList &labels)
作用：用于批量添加多个条目到列表中，每个条目都是一个文本项。
参数：labels：一个 QStringList 类型的字符串列表，每个字符串会变成一个条目。

示例用法：

QStringList fruits;
fruits << "苹果" << "香蕉" << "葡萄" << "橘子";QListWidget* listWidget = new QListWidget(this);
listWidget->addItems(fruits);

这将向列表中依次添加 4 个条目，文本分别是 “苹果”、“香蕉”、“葡萄” 和 “橘子”。

2.1.3 void QListWidget::addItem(QListWidgetItem *item)
作用：用于向列表中添加一个自定义的条目对象。
参数：item：指向一个 QListWidgetItem 对象的指针，表示你要添加的条目。

效果：

将该条目插入到列表末尾。
QListWidget 会自动接管该对象的所有权，无需手动释放。

示例用法：添加带图标和自定义样式的项

QListWidget* listWidget = new QListWidget(this);// 创建一个自定义的条目
QListWidgetItem* item = new QListWidgetItem(QIcon(":/icons/star.png"), "重要任务");// 设置附加样式
item->setFont(QFont("Microsoft YaHei", 12, QFont::Bold));
item->setForeground(Qt::red);
item->setBackground(Qt::yellow);
item->setToolTip("这是一个高优先级任务");// 添加到列表中
listWidget->addItem(item);

使用 setData() 来绑定自定义数据：
在 Qt 中，setData() 是 QListWidgetItem 的成员函数，用于将自定义数据绑定到某个列表项上，便于后续查找、操作或传递附加信息。

函数原型：

void QListWidgetItem::setData(int role, const QVariant &value);

参数说明：

role：数据的“角色”，例如 Qt::UserRole、Qt::DisplayRole
value：任意类型的数据，必须能被包装成 QVariant（如 int, QString, bool, QPointF, 自定义结构体等）

常用角色：

Qt::UserRole：开发者自定义使用的第一个角色。
Qt::UserRole + 1, +2, …：可自定义多个字段。
Qt::DisplayRole：值为0，控制 item 的主显示文本。
Qt::ToolTipRole：值为3，控制鼠标悬停提示。

示例：绑定一个 ID 到列表项

QListWidget* listWidget = new QListWidget(this);QListWidgetItem* item = new QListWidgetItem("任务一");
item->setData(Qt::UserRole, 101); // 绑定任务 ID
listWidget->addItem(item);// 点击时读取 ID
connect(listWidget, &QListWidget::itemClicked, this, [](QListWidgetItem* item){int taskId = item->data(Qt::UserRole).toInt();qDebug() << "点击任务 ID:" << taskId;
});

进阶用法：绑定多个字段

QListWidgetItem* item = new QListWidgetItem("设备 A");
item->setData(Qt::UserRole, 42);              // 设备ID
item->setData(Qt::UserRole + 1, "在线");      // 状态
item->setData(Qt::UserRole + 2, QColor("green"));  // 状态颜色
listWidget->addItem(item);

读取方式：

int deviceId = item->data(Qt::UserRole).toInt();
QString status = item->data(Qt::UserRole + 1).toString();
QColor color = item->data(Qt::UserRole + 2).value<QColor>();

自定义结构体绑定：
如果你有一个结构体，也可以用 QVariant 包装它，只要注册了类型：

struct TaskInfo {int id;QString name;
};
Q_DECLARE_METATYPE(TaskInfo)

注册类型：

qRegisterMetaType<TaskInfo>("TaskInfo");

绑定使用：

TaskInfo info = {123, "检查任务"};
QVariant var;
var.setValue(info);QListWidgetItem* item = new QListWidgetItem("任务123");
item->setData(Qt::UserRole, var);

如何注册自定义结构体到 QVariant?

步骤一：定义并声明结构体
1.定义结构体并使用 Q_DECLARE_METATYPE

struct TaskInfo {int id;QString name;
};
Q_DECLARE_METATYPE(TaskInfo)  // 必须放在 struct 定义之后

Q_DECLARE_METATYPE 告诉 Qt 怎么将 TaskInfo 包装进 QVariant。

步骤二：注册类型
2. 在主函数或初始化阶段注册

#include <QMetaType>// 一般在 main() 或 QApplication 初始化前注册
int main(int argc, char *argv[]) {qRegisterMetaType<TaskInfo>("TaskInfo");QApplication app(argc, argv);...
}

如果只打算把它塞进 QVariant（不跨线程、不用信号槽传输），可以省略 qRegisterMetaType，只用 Q_DECLARE_METATYPE。

示例：绑定结构体到 QListWidgetItem

TaskInfo task{101, "图像识别任务"};QVariant v;
v.setValue(task);QListWidgetItem* item = new QListWidgetItem(task.name);
item->setData(Qt::UserRole, v);
listWidget->addItem(item);

读取时还原结构体：

QVariant v = item->data(Qt::UserRole);
TaskInfo task = v.value<TaskInfo>();
qDebug() << "ID:" << task.id << " Name:" << task.name;

2.1.4 void QListWidget::insertItem(int row, QListWidgetItem *item)
作用：用于在指定位置插入一个自定义的条目（QListWidgetItem）。

参数说明：

row：插入位置的行索引（从 0 开始）
item：要插入的条目对象指针（QListWidgetItem*）

使用示例：

QListWidget* listWidget = new QListWidget(this);// 添加几个初始条目
listWidget->addItem("苹果");
listWidget->addItem("香蕉");// 创建要插入的新条目
QListWidgetItem* item = new QListWidgetItem("插入的葡萄");// 插入到索引 1 的位置（即“香蕉”之前）
listWidget->insertItem(1, item);

插入后，列表将变为：
在这里插入图片描述
示例：在当前选中项上方插入

int row = listWidget->currentRow();  // 获取当前选中行
QListWidgetItem* newItem = new QListWidgetItem("新任务");
listWidget->insertItem(row, newItem);

2.1.5 void QListWidget::insertItem(int row, const QString &label)
作用：用于在指定位置插入一个文本条目。

参数说明：

row：插入位置的索引，从 0 开始计数。
label：要插入的条目显示文本（QString 类型）

使用示例：

QListWidget* listWidget = new QListWidget(this);// 添加初始条目
listWidget->addItem("第一项");
listWidget->addItem("第三项");// 在第 1 行插入“第二项”
listWidget->insertItem(1, "第二项");

2.1.6 void QListWidget::insertItems(int row, const QStringList &labels)
作用：用于批量在指定位置插入多个纯文本条目。

参数说明：

row：插入起始位置索引（从 0 开始）
labels：一组要插入的字符串（QStringList）

示例：在指定位置插入多个条目

QListWidget* listWidget = new QListWidget(this);// 初始添加两个条目
listWidget->addItem("星期一");
listWidget->addItem("星期五");// 要插入的新项
QStringList midWeek = { "星期二", "星期三", "星期四" };// 插入到索引 1（即“星期五”之前）
listWidget->insertItems(1, midWeek);

输出结果：
在这里插入图片描述

2.2 查找数据

2.2.1 QListWidgetItem *QListWidget::currentItem() const
作用：

如果当前列表中有一项被选中，它将返回指向该项的指针。
如果没有项被选中，返回 nullptr。
“当前项”并不一定是“多选”状态下选中的所有项之一，而是焦点所在的那一项。

使用示例：

QListWidget *listWidget = new QListWidget(this);// 添加一些项
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("橘子");// 获取当前项
QListWidgetItem *item = listWidget->currentItem();
if (item) {qDebug() << "当前选中的项是：" << item->text();
} else {qDebug() << "当前没有选中任何项";
}

可以在信号 currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous) 中使用它，
例如：

connect(listWidget, &QListWidget::currentItemChanged,this, [](QListWidgetItem *current, QListWidgetItem *previous){if (current) {qDebug() << "新选中项：" << current->text();}
});

2.2.2 int QListWidget::currentRow() const
作用：
获取当前被选中的项在列表中的行号（从 0 开始计数）。

如果列表中当前有选中的项，它返回该项的索引（行号）。
如果没有任何项被选中，则返回 -1。

使用示例：

QListWidget *listWidget = new QListWidget(this);// 添加一些项
listWidget->addItem("第一行");
listWidget->addItem("第二行");
listWidget->addItem("第三行");// 设置当前选中第二项（行号 1）
listWidget->setCurrentRow(1);// 获取当前选中的行号
int row = listWidget->currentRow();
qDebug() << "当前选中项的行号是：" << row;

结合 currentItem() 一起使用：

QListWidgetItem *item = listWidget->currentItem();
int row = listWidget->currentRow();if (item && row != -1) {qDebug() << "当前项内容：" << item->text();qDebug() << "当前项所在行号：" << row;
}

2.2.3 QListWidgetItem *QListWidget::item(int row) const
作用：

数 row 是项在列表中的索引，从 0 开始。
如果索引有效（0 ≤ row < count），返回对应项的指针。
如果索引越界，返回 nullptr。

使用示例：

QListWidget *listWidget = new QListWidget(this);// 添加项
listWidget->addItem("A");
listWidget->addItem("B");
listWidget->addItem("C");// 获取第 1 行（第二项）
QListWidgetItem *item = listWidget->item(1);
if (item) {qDebug() << "第1行的项是：" << item->text();  // 输出 "B"
} else {qDebug() << "行号无效，未找到项。";
}

常见用途：
遍历所有项：

for (int i = 0; i < listWidget->count(); ++i) {QListWidgetItem *item = listWidget->item(i);qDebug() << "第" << i << "行的内容：" << item->text();
}

设置某一行文本：

QListWidgetItem *item = listWidget->item(2);
if (item)item->setText("新内容");

2.2.4 QListWidgetItem *QListWidget::itemAt(const QPoint &p) const
作用：
返回在 QListWidget 中，指定坐标 p（窗口坐标）下的项（QListWidgetItem*）。

参数 p 是一个 QPoint，表示相对于 QListWidget 视图坐标系统中的一个点（例如鼠标点击的位置）。
如果该位置有对应的项，则返回该项的指针；
如果该位置没有任何项（空白区域），则返回 nullptr。

使用示例：

void MyWidget::mousePressEvent(QMouseEvent *event)
{QPoint pos = event->pos();  // 获取点击的位置QListWidgetItem *item = myListWidget->itemAt(pos);if (item) {qDebug() << "点击了项：" << item->text();} else {qDebug() << "点击的是空白区域";}
}

注意：如果在外部控件中处理鼠标事件，可能需要将坐标从全局或父窗口坐标转换到 QListWidget 的局部坐标，
例如：

QPoint localPos = listWidget->mapFromGlobal(QCursor::pos());
QListWidgetItem *item = listWidget->itemAt(localPos);

2.2.5 QListWidgetItem *QListWidget::itemAt(int x, int y) const
作用：
返回位于 QListWidget 中指定坐标位置 (x, y) 的项指针（QListWidgetItem*）。

x 和 y 是相对于 QListWidget 视图的坐标（通常来源于鼠标事件）。
如果该位置有一项，则返回该项的指针；
如果该位置是空白区域，则返回 nullptr。

使用示例：

void MyWidget::mousePressEvent(QMouseEvent *event)
{int x = event->x();int y = event->y();QListWidgetItem *item = myListWidget->itemAt(x, y);if (item) {qDebug() << "你点击了项：" << item->text();} else {qDebug() << "你点击了空白区域";}
}

2.2.6 QWidget *QListWidget::itemWidget(QListWidgetItem *item) const
作用：
获取与指定 QListWidgetItem 关联的自定义子控件（QWidget*）。

如果该 item 使用了 setItemWidget() 设置了一个控件，该函数返回该控件；
如果该项没有关联控件，则返回 nullptr；
该函数主要用于实现“列表项嵌套控件”的复杂 UI，例如在列表中显示按钮、复选框、进度条等。

使用示例：

// 创建一个 QListWidget 和一个自定义控件
QListWidget *listWidget = new QListWidget(this);
QListWidgetItem *item = new QListWidgetItem(listWidget);QPushButton *button = new QPushButton("点击我");
listWidget->addItem(item);
listWidget->setItemWidget(item, button);// 获取这个控件
QWidget *w = listWidget->itemWidget(item);
if (w) {qDebug() << "找到控件类型：" << w->metaObject()->className(); // 输出 QPushButton
}

典型用途：
实现带复选框的列表项：

QCheckBox *check = new QCheckBox("选项A");
QListWidgetItem *item = new QListWidgetItem(listWidget);
listWidget->addItem(item);
listWidget->setItemWidget(item, check);

获取状态：

QCheckBox *check = qobject_cast<QCheckBox *>(listWidget->itemWidget(item));
if (check && check->isChecked()) {qDebug() << "该项被选中了！";
}

2.2.7 void QListWidget::removeItemWidget(QListWidgetItem *item)
作用：
将绑定在某个 QListWidgetItem 上的子控件（通过 setItemWidget() 设置的 QWidget）从列表项中移除，但不删除该控件。

该函数不会销毁控件，只是将它从 QListWidget 的布局中移除。
如果你需要彻底销毁控件，应该手动调用 delete。

使用示例：

QListWidgetItem *item = new QListWidgetItem(listWidget);
QPushButton *button = new QPushButton("按钮");
listWidget->addItem(item);
listWidget->setItemWidget(item, button);// 移除控件
listWidget->removeItemWidget(item);// 控件仍然存在，可以手动销毁
button->deleteLater();

注意事项：

removeItemWidget() 不会删除 QListWidgetItem；
也不会删除绑定的 QWidget；
被移除的控件不会自动重新显示在 UI 中，除非你手动添加到别处；
控件的父对象仍是 QListWidget，因此在不需要时应调用 delete 或 deleteLater() 销毁。

删除项并清理控件的完整做法：

QWidget *widget = listWidget->itemWidget(item);
listWidget->removeItemWidget(item);
delete widget;  // 或 widget->deleteLater();
delete item;

2.2.8 int QListWidget::row(const QListWidgetItem *item) const
作用：
返回指定 QListWidgetItem* 在 QListWidget 中的行号（索引）。

行号从 0 开始；
如果 item 是当前 QListWidget 中的有效项，则返回其索引；
如果该项不在列表中，返回 -1。

使用示例：

QListWidget *listWidget = new QListWidget(this);// 添加项
QListWidgetItem *item1 = new QListWidgetItem("苹果");
QListWidgetItem *item2 = new QListWidgetItem("香蕉");
listWidget->addItem(item1);
listWidget->addItem(item2);// 获取某项所在行号
int index = listWidget->row(item2);
qDebug() << "香蕉在第几行：" << index;  // 输出 1

注意事项：

参数必须是 listWidget 中已经存在的项；
如果是新创建的项，还未添加进列表，调用 row() 会返回 -1。

2.2.9 QList<QListWidgetItem *> QListWidget::selectedItems() const

作用：
返回当前所有被选中的 QListWidgetItem* 列表。

支持单选和多选模式；
单选时，返回列表最多包含一个元素；
多选时，返回所有选中项；
无选中项时，返回空列表。

使用示例：

QList<QListWidgetItem *> selectedItems = listWidget->selectedItems();if (selectedItems.isEmpty()) {qDebug() << "没有选中任何项";
} else {for (QListWidgetItem *item : selectedItems) {qDebug() << "选中项文本：" << item->text();}
}

多选模式设置示例：

listWidget->setSelectionMode(QAbstractItemView::MultiSelection);

注意事项：

返回的是指向项的指针，不是索引；
若需删除选中项，先使用 takeItem() 移除，再删除指针。

删除所有选中项示例：

auto selectedItems = listWidget->selectedItems();
for (auto item : selectedItems) {delete listWidget->takeItem(listWidget->row(item));
}

下面是一个完整的 Qt QListWidget 多选操作示例，演示如何设置多选模式，获取所有选中项，并执行批量删除操作。

#include <QApplication>
#include <QListWidget>
#include <QPushButton>
#include <QVBoxLayout>
#include <QWidget>
#include <QDebug>class MyWidget : public QWidget {Q_OBJECT
public:MyWidget(QWidget *parent = nullptr) : QWidget(parent) {listWidget = new QListWidget(this);deleteButton = new QPushButton("删除选中项", this);// 设置多选模式listWidget->setSelectionMode(QAbstractItemView::MultiSelection);// 添加示例项listWidget->addItem("苹果");listWidget->addItem("香蕉");listWidget->addItem("橘子");listWidget->addItem("葡萄");listWidget->addItem("西瓜");QVBoxLayout *layout = new QVBoxLayout(this);layout->addWidget(listWidget);layout->addWidget(deleteButton);connect(deleteButton, &QPushButton::clicked, this, &MyWidget::deleteSelectedItems);}private slots:void deleteSelectedItems() {// 获取所有选中的项QList<QListWidgetItem *> selectedItems = listWidget->selectedItems();if (selectedItems.isEmpty()) {qDebug() << "没有选中任何项。";return;}// 逐个删除选中项for (QListWidgetItem *item : selectedItems) {// 先从列表中取出，再delete，避免内存泄漏delete listWidget->takeItem(listWidget->row(item));}}private:QListWidget *listWidget;QPushButton *deleteButton;
};int main(int argc, char *argv[]) {QApplication a(argc, argv);MyWidget w;w.show();return a.exec();
}

2.3 选项设置

2.3.1 void QListWidget::setCurrentItem(QListWidgetItem *item)
作用：
设置指定的 QListWidgetItem* 为当前选中项（即焦点所在项）。

使该项变为当前项，列表视图会自动滚动到该项；
会触发 currentItemChanged 信号；
如果传入 nullptr，表示取消当前项的选中。

使用示例：

QListWidget *listWidget = new QListWidget(this);
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("橘子");QListWidgetItem *item = listWidget->item(1); // 获取第二项“香蕉”
listWidget->setCurrentItem(item); // 设置“香蕉”为当前选中项

结合信号使用：

connect(listWidget, &QListWidget::currentItemChanged,this, [](QListWidgetItem *current, QListWidgetItem *previous) {if (current) {qDebug() << "当前选中项变更为：" << current->text();}
});

注意事项：

只设置当前项，不一定改变“选中状态”（selection）——视 selectionMode 而定；
如果需要同时设置当前项并选中它，可以先调用 setCurrentItem()，然后调用 setItemSelected(item, true)。

选中当前项示例：

listWidget->setCurrentItem(item);
listWidget->setItemSelected(item, true);

2.3.2 void QListWidget::setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command)
作用：
将指定的 QListWidgetItem* 设置为当前项，并根据 command 参数来控制选中和焦点的行为。

这个重载函数允许更精细地控制当前项的选择和焦点状态；
command 是 QItemSelectionModel::SelectionFlags 枚举类型，常用值包括：
- QItemSelectionModel::Clear — 清除当前选择；
- QItemSelectionModel::Select — 选择项；
- QItemSelectionModel::Deselect — 取消选择；
- QItemSelectionModel::Toggle — 切换选择状态；
- QItemSelectionModel::Current — 设置当前项（焦点项）。

常用组合示例：
仅设置当前项（焦点项），不改变选中状态：

listWidget->setCurrentItem(item, QItemSelectionModel::Current);

设置当前项并选中它：

listWidget->setCurrentItem(item, QItemSelectionModel::Select | QItemSelectionModel::Current);

取消当前项的选中状态但仍保持当前焦点：

listWidget->setCurrentItem(item, QItemSelectionModel::Deselect | QItemSelectionModel::Current);

使用示例代码：

QListWidget *listWidget = new QListWidget(this);
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("橘子");QListWidgetItem *item = listWidget->item(1); // 第二项“香蕉”// 设置“香蕉”为当前项并选中
listWidget->setCurrentItem(item, QItemSelectionModel::Select | QItemSelectionModel::Current);

2.3.3 void QListWidget::setCurrentRow(int row)

作用：
设置 QListWidget 中指定行号（row）的项为“当前项”。

会触发 currentItemChanged() 信号；
会自动滚动视图，使该项可见；
并将焦点移动到该项；
如果 row 超出范围（小于 0 或大于等于 count），不会改变当前项。

使用示例：

QListWidget *listWidget = new QListWidget(this);
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("橘子");// 设置第二项为当前项（行号 1）
listWidget->setCurrentRow(1);

结合信号槽使用：

connect(listWidget, &QListWidget::currentItemChanged,this, [](QListWidgetItem *current, QListWidgetItem *previous) {if (current)qDebug() << "当前项变为：" << current->text();
});

注意事项：

setCurrentRow() 只设置当前项（有焦点的项），并不影响其他选中项；
若在多选模式下使用，仅更改焦点，不会影响多选状态；
如果需要选中该项，可结合使用 setItemSelected() 或使用另一个重载版本 setCurrentRow(int, QItemSelectionModel::SelectionFlags)。

2.3.4 void QListWidget::setCurrentRow(int row, QItemSelectionModel::SelectionFlags command)

作用：
设置 QListWidget 中指定行号 row 对应的项为“当前项”，并根据 command 参数控制其选中状态或行为。这个函数相比 setCurrentRow(int row) 更加灵活，允许通过 QItemSelectionModel::SelectionFlags 控制选择行为，例如是否选中该行、是否取消其他选中项、是否切换状态等。

常用的 SelectionFlags：
来自枚举 QItemSelectionModel::SelectionFlags，常用值如下：
在这里插入图片描述
使用示例
示例 1：设置某行为当前项并选中

listWidget->setCurrentRow(2, QItemSelectionModel::Select | QItemSelectionModel::Current);

示例 2：设置某行为当前项，但取消选中状态

listWidget->setCurrentRow(1, QItemSelectionModel::Deselect | QItemSelectionModel::Current);

示例 3：只设置当前项（不选中）

listWidget->setCurrentRow(0, QItemSelectionModel::Current);

示例 4：清除所有选中项并设置新当前项

listWidget->setCurrentRow(3, QItemSelectionModel::Clear | QItemSelectionModel::Select | QItemSelectionModel::Current);

2.3.5 void QListWidget::setItemWidget(QListWidgetItem *item, QWidget *widget)

作用：
将一个 QWidget* 控件嵌入到指定的 QListWidgetItem 项上，使该项显示为该控件。

这使你可以在 QListWidget 的每一项中使用如按钮、复选框、进度条等自定义控件；
替代了 QListWidgetItem::setText() 的默认文本显示方式；
一个项只能绑定一个控件；若再次设置会替换原控件。

基本使用示例：

QListWidget *listWidget = new QListWidget(this);// 创建列表项
QListWidgetItem *item = new QListWidgetItem(listWidget);
listWidget->addItem(item);// 创建控件（如按钮）并设置到该项上
QPushButton *button = new QPushButton("点击我");
listWidget->setItemWidget(item, button);

更多控件示例：
显示复选框

QCheckBox *checkBox = new QCheckBox("选项A");
QListWidgetItem *item = new QListWidgetItem(listWidget);
listWidget->addItem(item);
listWidget->setItemWidget(item, checkBox);

显示进度条

QProgressBar *progress = new QProgressBar();
progress->setValue(70);
QListWidgetItem *item = new QListWidgetItem(listWidget);
listWidget->addItem(item);
listWidget->setItemWidget(item, progress);

注意事项：

设置后，item->text() 不会显示在界面中，控件会完全替代默认显示；
控件将作为 listWidget 的子控件管理，一般不需要手动销毁；
如需移除控件，请使用 removeItemWidget()，如果不再使用应手动 delete 控件。

2.3.6 QListWidgetItem *takeItem(int row)

作用：
用于从列表中移除并返回指定行的 QListWidgetItem 指针，但不删除它。你可以随后对这个 item 做进一步处理，比如修改、重新插入或手动删除。

参数：row：要移除的 item 的索引（从 0 开始）

返回值：

返回指向被移除的 QListWidgetItem 的指针；
如果 row 无效（超出范围），返回 nullptr。

常见用途：

移除某项后，保存或修改再重新插入；
手动删除 item（注意：你拿到的是堆对象，需要 delete）；
移动 item（先 takeItem，再 insertItem）。

示例：移除并删除某一项

int row = 2;
QListWidgetItem *item = listWidget->takeItem(row);
if (item) {delete item;  // 必须手动释放内存！
}

示例：将一项从位置 A 移到位置 B

int from = 2;
int to = 0;
QListWidgetItem *item = listWidget->takeItem(from);
if (item) {listWidget->insertItem(to, item);
}

注意事项：

内存释放 takeItem() 不删除 item，你必须手动 delete
信号响应 takeItem() 不会触发 itemChanged 之类信号
重新插入可以 insertItem() 插回

四、QListWidget的信号与槽

4.1 void currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)

作用：用于通知当前选中项发生变化时的事件。

参数说明：
- List item

触发时机：

用户用鼠标或键盘改变了选中项；
程序调用了 setCurrentItem() 或 setCurrentRow()；
初次选中项或取消选中时，previous 或 current 为 nullptr。

示例：连接信号槽
示例 1：lambda 写法（推荐）

connect(listWidget, &QListWidget::currentItemChanged,this, [](QListWidgetItem *current, QListWidgetItem *previous) {if (current) {qDebug() << "当前项文本:" << current->text();}if (previous) {qDebug() << "前一项文本:" << previous->text();}
});

示例 2：使用自定义槽函数

// 声明槽函数
void onCurrentItemChanged(QListWidgetItem *current, QListWidgetItem *previous);// 连接信号
connect(listWidget, &QListWidget::currentItemChanged,this, &YourClass::onCurrentItemChanged);// 实现槽函数
void YourClass::onCurrentItemChanged(QListWidgetItem *current, QListWidgetItem *previous) {if (current)qDebug() << "当前项：" << current->text();if (previous)qDebug() << "之前项：" << previous->text();
}

4.2 void currentRowChanged(int currentRow)

作用：用于在当前选中行发生变化时通知你当前选中的行号。

参数说明：
在这里插入图片描述
触发时机：

用户点击不同的项；
使用键盘上下箭头切换项；
程序调用 setCurrentRow() 或 setCurrentItem()；

示例：使用 lambda 响应行号变化

connect(listWidget, &QListWidget::currentRowChanged,this, [](int row) {qDebug() << "当前选中行：" << row;
});

示例：使用槽函数

// 连接信号
connect(listWidget, &QListWidget::currentRowChanged,this, &YourClass::onCurrentRowChanged);// 槽函数定义
void YourClass::onCurrentRowChanged(int row) {qDebug() << "当前选中行号：" << row;QListWidgetItem* item = listWidget->item(row);if (item)qDebug() << "对应文本：" << item->text();
}

4.3 void itemActivated(QListWidgetItem *item)
作用：当用户激活某个条目时发出，常用于响应用户双击某项或按下回车键激活当前项。

触发方式：
在这里插入图片描述
示例：连接 itemActivated 信号
使用 lambda：

connect(listWidget, &QListWidget::itemActivated,this, [](QListWidgetItem *item) {if (item)qDebug() << "激活项文本：" << item->text();
});

使用自定义槽函数：

connect(listWidget, &QListWidget::itemActivated,this, &YourClass::onItemActivated);void YourClass::onItemActivated(QListWidgetItem *item) {if (item)qDebug() << "用户激活了：" << item->text();
}

常见用途：

打开对应的详细界面（如文件管理器中打开文件）；
响应确认操作（如双击打开图片）；
与 QStackedWidget 联动切换内容页面；
启动编辑、显示弹窗、触发某项动作等。

对比其他信号：
在这里插入图片描述
4.4 void itemChanged(QListWidgetItem *item)

作用：用于在某个条目的数据内容发生变化时发出，尤其适用于文本修改或勾选状态改变等情况。

触发条件：
在这里插入图片描述
前提条件：必须启用可更改标志
为使条目可编辑或勾选，你必须设置适当的 Qt::ItemFlags，例如：

QListWidgetItem* item = new QListWidgetItem("默认文本");
item->setFlags(item->flags() | Qt::ItemIsEditable | Qt::ItemIsUserCheckable);
listWidget->addItem(item);

示例：响应 item 内容变更

connect(listWidget, &QListWidget::itemChanged,this, [](QListWidgetItem *item) {qDebug() << "项内容发生改变：" << item->text();
});

在这里插入图片描述
输出结果：

示例：检测复选框状态改变
在这里插入图片描述
输出结果：

注意事项：

即使程序修改数据也会触发信号；
如果不希望程序内设置数据时触发信号，可在修改前使用 blockSignals(true) 临时关闭。

listWidget->blockSignals(true);
item->setText("程序修改的文本");
listWidget->blockSignals(false);

4.5 void itemClicked(QListWidgetItem *item)

作用：当用户点击列表中的某一项时发出。这是一个非常常用的信号，用于处理用户点击操作的逻辑响应。

参数说明：
在这里插入图片描述

触发条件：

用户用鼠标左键点击某个列表项时触发；
程序调用 setCurrentItem() 不会触发；
只响应用户行为，不响应程序设置。

示例：使用 lambda 响应点击

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

示例：自定义槽函数响应

connect(listWidget, &QListWidget::itemClicked,this, &YourClass::onItemClicked);void YourClass::onItemClicked(QListWidgetItem *item) {qDebug() << "被点击的项文本：" << item->text();
}

4.6 void itemDoubleClicked(QListWidgetItem *item)

作用：用于在用户双击某个列表项时发出，常用于打开详情、进入编辑模式、或执行确认操作等。

触发条件：
在这里插入图片描述
参数说明：

示例：使用 lambda 处理双击

connect(listWidget, &QListWidget::itemDoubleClicked,this, [](QListWidgetItem *item) {if (item)qDebug() << "用户双击了项：" << item->text();
});

示例：自定义槽函数处理双击行为

connect(listWidget, &QListWidget::itemDoubleClicked,this, &YourClass::onItemDoubleClicked);void YourClass::onItemDoubleClicked(QListWidgetItem *item) {if (item)qDebug() << "双击触发操作：" << item->text();
}

4.7 void itemEntered(QListWidgetItem *item)

作用：当鼠标光标进入某一项区域时发出，可用于实现鼠标悬浮提示、预览、动态样式等效果。

使用前提：
要使用 itemEntered 信号，必须启用列表控件的“鼠标追踪模式”：

listWidget->setMouseTracking(true);

否则你将不会收到任何鼠标进入的事件。

触发条件：
在这里插入图片描述
示例：连接信号处理悬浮提示

listWidget->setMouseTracking(true);  // 必须启用鼠标追踪connect(listWidget, &QListWidget::itemEntered,this, [](QListWidgetItem *item) {if (item)qDebug() << "鼠标进入项：" << item->text();
});

示例：悬浮显示 tooltip 提示

connect(listWidget, &QListWidget::itemEntered,this, [](QListWidgetItem *item) {if (item)QToolTip::showText(QCursor::pos(), "提示：" + item->text());
});

常见用途：

鼠标悬浮项高亮显示；
动态显示 tooltip、缩略图、预览信息；
进入某项区域触发临时动作或动画；
联动其他控件响应悬停项。

4.8 void itemPressed(QListWidgetItem *item)

作用：当用户按下鼠标按钮（通常是左键）在某个列表项上时触发，也就是说这个信号在鼠标按下瞬间发出，而不是释放或点击完成

触发条件：

参数说明：

示例：使用 lambda 连接信号

connect(listWidget, &QListWidget::itemPressed,this, [](QListWidgetItem *item) {if (item)qDebug() << "鼠标按下项：" << item->text();
});

示例：使用自定义槽函数

connect(listWidget, &QListWidget::itemPressed,this, &YourClass::onItemPressed);void YourClass::onItemPressed(QListWidgetItem *item) {if (item)qDebug() << "按下了项：" << item->text();
}

常见用途：

实现拖拽开始的检测（配合 mouseMoveEvent）；
右键菜单弹出前的准备工作；
点击按下时做一些视觉反馈（比如按下阴影效果）；
处理复杂点击行为（例如区分按下和释放事件）。

4.9 void itemSelectionChanged()

作用：当列表中选中项的集合发生变化时触发。无论是单选还是多选模式，只要选中项发生增减或变化，这个信号都会被发出。

触发条件：

用户用鼠标或键盘改变选中项（单选或多选）；
程序调用诸如 setCurrentItem(), setItemSelected(), clearSelection() 等函数改变选中状态；
只要选中项集合变化就会触发。

示例：响应选中项集合变化

connect(listWidget, &QListWidget::itemSelectionChanged,this, [=]() {QList<QListWidgetItem*> selectedItems = listWidget->selectedItems();qDebug() << "当前选中项数量：" << selectedItems.size();for (auto item : selectedItems) {qDebug() << "选中项文本：" << item->text();}
});