前言
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);
// 创建 QListWidget
QListWidget 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 ? "已选中" : "未选中");
else
info += "无";
info += "\n";
info += "自定义数据: " + item->data(Qt::UserRole).toString() + "\n";
info += "提示: " + item->toolTip() + "\n";
QMessageBox::information(&listWidget, "项信息", info);
});
listWidget.show();
return app.exec();
}