前言
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();
}



















