QListWidget的函数,信号介绍

前言

Qt版本:6.8.0

该类用于列表模型/视图

QListWidgetItem函数介绍

作用

QListWidget是Qt框架中用于管理可交互列表项的核心组件，主要作用包括：

1. 列表项管理

• 支持动态添加/删除项：addItem(), takeItem()
• 批量操作：addItems()添加多个项
• 排序功能：sortItems()自动排序

2. 交互功能

# 创建列表控件
list_widget = QListWidget()

# 添加图标项
list_widget.addItem(QListWidgetItem(QIcon("icon.png"), "带图标的项"))

# 信号处理
list_widget.itemClicked.connect(handle_click)

3. 显示控制

• 支持多种视图模式：setViewMode(QListView.IconMode)
• 自定义项样式：通过setItemWidget()嵌入自定义控件
• 调整布局：setFlow(QListView.LeftToRight)控制排列方向

4. 数据绑定

• 直接存取项数据：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 &currentText)

• 触发时机：当前选中项的文本发生改变（包括切换选中项或直接修改项文本）
• 参数：
  • 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();
          });
  

信号对比表

使用建议

1. 避免信号循环：在槽函数中修改项数据时，注意不要触发自身信号（例如在 itemChanged 中再次修改项）
2. 性能优化：对高频信号（如 itemEntered）进行防抖处理
3. 多选模式：使用 itemSelectionChanged 配合 selectedItems() 获取所有选中项
4. 数据同步：优先使用 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();
}