QListWidget的函数,信号介绍
前言
Qt版本:6.8.0
该类用于列表模型/视图
QListWidgetItem函数介绍
作用
QListWidget是Qt框架中用于管理可交互列表项的核心组件，主要作用包括：
- 列表项管理
- 支持动态添加/删除项：
addItem(),takeItem() - 批量操作：
addItems()添加多个项 - 排序功能：
sortItems()自动排序
- 交互功能
# 创建列表控件
list_widget = QListWidget()# 添加图标项
list_widget.addItem(QListWidgetItem(QIcon("icon.png"), "带图标的项"))# 信号处理
list_widget.itemClicked.connect(handle_click)
- 显示控制
- 支持多种视图模式：
setViewMode(QListView.IconMode) - 自定义项样式：通过
setItemWidget()嵌入自定义控件 - 调整布局：
setFlow(QListView.LeftToRight)控制排列方向
- 数据绑定
- 直接存取项数据：
item.text() - 关联数据结构：
setCurrentRow()同步选择状态
典型应用场景：
- 文件选择列表
- 配置选项面板
- 聊天消息记录
- 可拖拽排序的任务列表
与QListView的区别在于：QListWidget提供了更简便的item-based API，适合快速开发；而QListView需要配合Model/View架构，适合处理复杂数据关系。
公共函数
构造函数与析构函数
QListWidget(QWidget *parent = nullptr)
- 功能：创建列表控件
- 参数：
parent：父窗口指针（可选）
- 示例：
QListWidget *listWidget = new QListWidget(this); // 创建列表控件
virtual ~QListWidget()
- 功能：析构函数，释放资源
基础操作函数
void addItem(QListWidgetItem *item)
- 功能：添加自定义项到列表末尾
- 参数：
item：要添加的列表项指针
- 示例：
QListWidgetItem *item = new QListWidgetItem("New Item"); listWidget->addItem(item); // 添加项到列表末尾
void addItem(const QString &label)
- 功能：直接通过文本添加项到列表末尾
- 参数：
label：项显示的文本
- 示例：
listWidget->addItem("Simple Item"); // 直接添加文本项
void addItems(const QStringList &labels)
- 功能：批量添加多个文本项到列表末尾
- 参数：
labels：字符串列表
- 示例：
QStringList items = {"Item1", "Item2", "Item3"}; listWidget->addItems(items); // 批量添加
编辑与查找
void closePersistentEditor(QListWidgetItem *item)
- 功能：关闭项的持久编辑器
- 参数：
item：需要关闭编辑器的项
- 示例：
listWidget->closePersistentEditor(item); // 关闭指定项的编辑器
int count() const
- 功能：返回列表项的个数
- 返回值：整数型数量
- 示例：
int total = listWidget->count(); // 获取总项数
QListWidgetItem *currentItem() const
- 功能：返回当前选中的项
- 返回值：项指针（未选中时返回
nullptr） - 示例：
QListWidgetItem *current = listWidget->currentItem(); if (current) qDebug() << "当前选中项：" << current->text();
int currentRow() const
- 功能：返回当前选中项的行号（从 0 开始）
- 返回值：行号（未选中返回 -1）
- 示例：
int row = listWidget->currentRow(); // 获取当前行号
项管理
void editItem(QListWidgetItem *item)
- 功能：启动指定项的编辑模式
- 参数：
item：要编辑的项
- 示例：
listWidget->editItem(item); // 进入编辑模式
QList<QListWidgetItem *> findItems(const QString &text, Qt::MatchFlags flags) const
- 功能：根据匹配规则查找项
- 参数：
text：要匹配的文本flags：匹配规则（如Qt::MatchExactly）
- 返回值：符合条件的项列表
- 示例：
auto items = listWidget->findItems("Test", Qt::MatchContains); // 查找包含"Test"的项
QModelIndex indexFromItem(const QListWidgetItem *item) const
- 功能：获取项的模型索引
- 参数：
item：目标项
- 返回值：对应的
QModelIndex - 示例：
QModelIndex index = listWidget->indexFromItem(item); // 获取索引
插入与移除
void insertItem(int row, QListWidgetItem *item)
- 功能：在指定行插入自定义项
- 参数：
row：插入位置（0-based）item：要插入的项
- 示例：
QListWidgetItem *newItem = new QListWidgetItem("Inserted"); listWidget->insertItem(2, newItem); // 插入到第三行
void insertItem(int row, const QString &label)
- 功能：在指定行插入文本项
- 参数：
row：插入位置label：项文本
- 示例：
listWidget->insertItem(0, "First Item"); // 插入到第一行
void insertItems(int row, const QStringList &labels)
- 功能：在指定行批量插入多个文本项
- 参数：
row：起始行号labels：要插入的文本列表
- 示例：
listWidget->insertItems(1, {"A", "B", "C"}); // 从第二行开始插入
状态检查
bool isPersistentEditorOpen(QListWidgetItem *item) const
- 功能：检查项是否处于持久编辑状态
- 返回值：
true表示编辑器已打开 - 示例：
if (listWidget->isPersistentEditorOpen(item)) {// 处理编辑器已打开的情况 }
bool isSortingEnabled() const
- 功能：检查是否启用了自动排序
- 返回值：
true表示启用排序 - 示例：
bool sorted = listWidget->isSortingEnabled();
项操作
QListWidgetItem *item(int row) const
- 功能：获取指定行的项
- 参数：
row：行号
- 返回值：项指针（无效行返回
nullptr） - 示例：
QListWidgetItem *item = listWidget->item(3); // 获取第四行的项
QListWidgetItem *itemAt(const QPoint &p) const
- 功能：获取指定坐标处的项（相对列表控件）
- 参数：
p：坐标点
- 返回值：项指针（无项返回
nullptr） - 示例：
QListWidgetItem *item = listWidget->itemAt(QPoint(50, 100)); // 获取(50,100)处的项
QListWidgetItem *itemFromIndex(const QModelIndex &index) const
- 功能：从模型索引获取项
- 参数：
index：模型索引
- 返回值：对应的项指针
- 示例：
QListWidgetItem *item = listWidget->itemFromIndex(index);
部件管理
QWidget *itemWidget(QListWidgetItem *item) const
- 功能：获取项上设置的部件
- 参数：
item：目标项
- 返回值：部件指针（未设置返回
nullptr） - 示例：
QWidget *widget = listWidget->itemWidget(item); // 获取自定义部件
void openPersistentEditor(QListWidgetItem *item)
- 功能：为项打开持久编辑器（始终可编辑）
- 示例：
listWidget->openPersistentEditor(item); // 启用持久编辑
void removeItemWidget(QListWidgetItem *item)
- 功能：移除项上的自定义部件
- 示例：
listWidget->removeItemWidget(item); // 移除部件
布局与选择
int row(const QListWidgetItem *item) const
- 功能：返回项的行号
- 参数：
item：目标项
- 返回值：行号（无效项返回 -1）
- 示例：
int row = listWidget->row(item); // 获取项的行号
QList<QListWidgetItem *> selectedItems() const
- 功能：返回所有选中的项
- 返回值：选中项列表
- 示例：
auto selected = listWidget->selectedItems(); // 获取所有选中项
设置当前项
void setCurrentItem(QListWidgetItem *item)
- 功能：设置当前选中项
- 参数：
item：目标项
- 示例：
listWidget->setCurrentItem(item); // 选中指定项
void setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command)
- 功能：带选择模式的设置当前项
- 参数：
item：目标项command：选择模式（如QItemSelectionModel::Select）
- 示例：
listWidget->setCurrentItem(item, QItemSelectionModel::Toggle); // 切换选中状态
排序与清理
void setSortingEnabled(bool enable)
- 功能：启用/禁用自动排序
- 参数：
enable：true启用排序
- 示例：
listWidget->setSortingEnabled(true); // 启用自动排序
void sortItems(Qt::SortOrder order = Qt::AscendingOrder)
- 功能：手动排序所有项
- 参数：
order：排序顺序（升序/降序）
- 示例：
listWidget->sortItems(Qt::DescendingOrder); // 降序排列
其他功能
QListWidgetItem *takeItem(int row)
- 功能：移除并返回指定行的项
- 参数：
row：行号
- 返回值：被移除的项指针（需手动管理内存）
- 示例：
QListWidgetItem *removed = listWidget->takeItem(2); // 移除第三行项 delete removed; // 手动释放内存
QRect visualItemRect(const QListWidgetItem *item) const
- 功能：返回项在视图中的可视区域
- 示例：
QRect rect = listWidget->visualItemRect(item); // 获取项的位置和大小
重写的函数
virtual void setSelectionModel(QItemSelectionModel *selectionModel) override
- 功能：设置自定义选择模型（高级用法）
- 参数：
selectionModel：自定义选择模型
- 注意：通常不需要直接使用
公共槽函数
void clear()
- 功能：清空所有项
- 示例：
listWidget->clear(); // 清空列表
void scrollToItem(const QListWidgetItem *item, QAbstractItemView::ScrollHint hint = EnsureVisible)
- 功能：滚动到指定项
- 参数：
item：目标项hint：滚动策略（如PositionAtTop）
- 示例：
listWidget->scrollToItem(item, QAbstractItemView::PositionAtCenter); // 滚动到项并居中
信号
1. void currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)
- 触发时机：当前选中的项发生改变时（例如点击新项、通过代码设置选中项）
- 参数：
current：新选中的项指针（未选中时为nullptr）previous：之前选中的项指针（首次选中时为nullptr）
- 典型用途：跟踪焦点项变化，更新界面状态
- 示例：
connect(listWidget, &QListWidget::currentItemChanged, [](QListWidgetItem *current, QListWidgetItem *prev) {if (current) qDebug() << "选中了：" << current->text();if (prev) qDebug() << "取消选中：" << prev->text(); });
2. void currentRowChanged(int currentRow)
- 触发时机：当前选中项的行号发生变化时
- 参数：
currentRow：新选中项的行号（从 0 开始，未选中时为 -1）
- 典型用途：通过行号操作数据
- 示例：
connect(listWidget, &QListWidget::currentRowChanged, [](int row) {qDebug() << "当前行号：" << row;});
3. void currentTextChanged(const QString ¤tText)
- 触发时机：当前选中项的文本发生改变（包括切换选中项或直接修改项文本）
- 参数：
currentText：新选中项的文本内容（未选中时为空字符串）
- 典型用途：实时监控选中项的文本变化
- 示例：
connect(listWidget, &QListWidget::currentTextChanged, [](const QString &text) {qDebug() << "当前文本：" << text;});
4. void itemActivated(QListWidgetItem *item)
- 触发时机：用户通过 双击 或 回车键 激活项时
- 参数：
item：被激活的项指针
- 典型用途：实现双击打开/执行操作
- 示例：
connect(listWidget, &QListWidget::itemActivated, [](QListWidgetItem *item) {qDebug() << "激活项：" << item->text();});
5. void itemChanged(QListWidgetItem *item)
- 触发时机：项的 数据 发生改变（如文本、图标、复选框状态等）
- 参数：
item：被修改的项指针
- 典型用途：同步数据到模型或数据库
- 示例：
connect(listWidget, &QListWidget::itemChanged, [](QListWidgetItem *item) {qDebug() << "项被修改：" << item->text();});
6. void itemClicked(QListWidgetItem *item)
- 触发时机：用户 单击 项时（即使项已被选中）
- 参数：
item：被点击的项指针
- 典型用途：实现点击交互逻辑
- 示例：
connect(listWidget, &QListWidget::itemClicked, [](QListWidgetItem *item) {qDebug() << "单击了：" << item->text();});
7. void itemDoubleClicked(QListWidgetItem *item)
- 触发时机：用户 双击 项时
- 参数：
item：被双击的项指针
- 典型用途：快速执行操作（如打开文件）
- 示例：
connect(listWidget, &QListWidget::itemDoubleClicked, [](QListWidgetItem *item) {openFile(item->text()); // 自定义函数});
8. void itemEntered(QListWidgetItem *item)
- 触发时机：鼠标 悬停进入 项的区域时
- 参数：
item：被悬停的项指针
- 典型用途：显示工具提示或高亮效果
- 示例：
connect(listWidget, &QListWidget::itemEntered, [](QListWidgetItem *item) {QToolTip::showText(QCursor::pos(), item->text());});
9. void itemPressed(QListWidgetItem *item)
- 触发时机：用户 按下鼠标按钮 在项上时（在释放前触发）
- 参数：
item：被按下的项指针
- 典型用途：实现拖拽操作的起点判断
- 示例：
connect(listWidget, &QListWidget::itemPressed, [](QListWidgetItem *item) {qDebug() << "按下项：" << item->text();});
10. void itemSelectionChanged()
- 触发时机：选中项集合发生改变时（适用于多选模式）
- 参数：无
- 典型用途：处理多选操作后的批量处理
- 示例：
connect(listWidget, &QListWidget::itemSelectionChanged, [=]() {auto selected = listWidget->selectedItems();qDebug() << "已选中项数：" << selected.size();});
信号对比表
| 信号名称 | 触发动作 | 传递参数 | 适用场景 |
|---|---|---|---|
currentItemChanged | 选中项改变 | 新旧项指针 | 焦点跟踪 |
currentRowChanged | 选中行改变 | 行号 | 行号相关操作 |
currentTextChanged | 选中项文本变化 | 新文本 | 文本监控 |
itemActivated | 双击/回车激活 | 被激活的项 | 执行默认操作 |
itemChanged | 项数据修改 | 被修改的项 | 数据同步 |
itemClicked | 单击项 | 被点击的项 | 简单交互 |
itemDoubleClicked | 双击项 | 被双击的项 | 快速操作 |
itemEntered | 鼠标悬停进入项区域 | 被悬停的项 | 提示信息 |
itemPressed | 按下鼠标按钮 | 被按下的项 | 拖拽起点判断 |
itemSelectionChanged | 选中项集合变化（多选模式） | 无 | 批量操作 |
使用建议
- 避免信号循环：在槽函数中修改项数据时，注意不要触发自身信号（例如在
itemChanged中再次修改项） - 性能优化：对高频信号（如
itemEntered）进行防抖处理 - 多选模式：使用
itemSelectionChanged配合selectedItems()获取所有选中项 - 数据同步：优先使用
itemChanged而非currentTextChanged跟踪数据变化，后者仅监控当前项
其他函数
示例
#include <QApplication>
#include <QListWidget>
#include <QListWidgetItem>
#include <QIcon>
#include <QMessageBox>int main(int argc, char *argv[])
{QApplication app(argc, argv);// 创建 QListWidgetQListWidget listWidget;listWidget.setWindowTitle("QListWidgetItem 示例");listWidget.resize(400, 300);// 1. 添加普通文本项QListWidgetItem *item1 = new QListWidgetItem("普通文本项");listWidget.addItem(item1);// 2. 添加带图标和文本的项QIcon icon(":/icon.png"); // 请确保有合适的图标资源QListWidgetItem *item2 = new QListWidgetItem(icon, "带图标的项");listWidget.addItem(item2);// 3. 添加带复选框的项QListWidgetItem *item3 = new QListWidgetItem("带复选框的项");item3->setFlags(item3->flags() | Qt::ItemIsUserCheckable);item3->setCheckState(Qt::Unchecked);listWidget.addItem(item3);// 4. 添加带自定义数据、颜色和提示的项QListWidgetItem *item4 = new QListWidgetItem("自定义项");item4->setData(Qt::UserRole, 12345); // 存储自定义数据item4->setBackground(Qt::yellow);item4->setForeground(Qt::blue);item4->setToolTip("这是一个带有自定义数据和颜色的项");listWidget.addItem(item4);// 5. 添加只读项QListWidgetItem *item5 = new QListWidgetItem("只读项");item5->setFlags(item5->flags() & ~Qt::ItemIsEditable);listWidget.addItem(item5);// 6. 响应点击，显示项的详细信息QObject::connect(&listWidget, &QListWidget::itemClicked, [&](QListWidgetItem *item){QString info;info += "文本: " + item->text() + "\n";info += "是否选中: " + QString(item->isSelected() ? "是" : "否") + "\n";info += "复选框状态: ";if (item->flags() & Qt::ItemIsUserCheckable)info += (item->checkState() == Qt::Checked ? "已选中" : "未选中");elseinfo += "无";info += "\n";info += "自定义数据: " + item->data(Qt::UserRole).toString() + "\n";info += "提示: " + item->toolTip() + "\n";QMessageBox::information(&listWidget, "项信息", info);});listWidget.show();return app.exec();
}