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

Qt QListWidget 总结

article 2025/2/23 12:05:25

Qt QListWidget 总结

1. 概述

QListWidget 是 Qt 中用于显示和管理列表项的控件，继承自 QListView，但提供更简单的项（Item-Based）接口。
适用于简单列表场景（如文件列表、选项菜单），支持文本、图标、自定义控件等。
与 QListView 的区别：QListWidget 直接操作项，而 QListView 基于模型/视图架构，适合复杂数据。

2. 核心功能

项管理：添加、删除、插入、遍历列表项（QListWidgetItem）。
交互：支持单选、多选、拖放、排序、编辑。
样式：可自定义项的外观（字体、颜色、图标）或嵌入完整控件。
信号：响应项点击、双击、选择变化等事件。

3. 常用方法

添加项：

listWidget->addItem("Item 1"); // 添加文本项
listWidget->addItem(new QListWidgetItem(QIcon("icon.png"), "Item 2")); // 带图标
listWidget->addItems(QStringList() << "Item 3" << "Item 4"); // 批量添加

插入/删除项：

listWidget->insertItem(0, "Inserted Item"); // 插入到索引0
QListWidgetItem* item = listWidget->takeItem(1); // 移除索引1的项（需手动删除）
listWidget->clear(); // 清空所有项

获取项：

QListWidgetItem* current = listWidget->currentItem(); // 当前选中项
QList<QListWidgetItem*> selected = listWidget->selectedItems(); // 所有选中项
QListWidgetItem* item = listWidget->item(2); // 获取索引2的项

项属性：

item->setText("New Text");
item->setCheckState(Qt::Checked); // 设置为可勾选
item->setFlags(item->flags() | Qt::ItemIsEditable); // 允许编辑

4. 关键信号

itemClicked(QListWidgetItem*)：单击项时触发。
itemDoubleClicked(QListWidgetItem*)：双击项时触发。
currentItemChanged(QListWidgetItem*, QListWidgetItem*)：当前项变化时触发。
itemSelectionChanged()：选中项变化时触发。

5. 高级功能

自定义项控件：

QWidget* customWidget = new QWidget();
// 添加按钮、标签等到 customWidget...
QListWidgetItem* item = new QListWidgetItem();
listWidget->addItem(item);
listWidget->setItemWidget(item, customWidget); // 将控件嵌入项

排序与搜索：

listWidget->setSortingEnabled(true); // 启用排序（点击标题排序）
listWidget->sortItems(Qt::AscendingOrder); // 程序触发排序
auto items = listWidget->findItems("Key", Qt::MatchContains); // 模糊搜索

拖放支持：

listWidget->setDragEnabled(true);
listWidget->setAcceptDrops(true);
listWidget->setDropIndicatorShown(true);

样式美化：

listWidget->setStyleSheet(
    "QListWidget { background: #f0f0f0; }"
    "QListWidget::item { color: blue; }"
    "QListWidget::item:selected { background: yellow; }"
);

6. 性能与注意

内存管理：项默认由 QListWidget 管理，无需手动释放。若动态创建项后未添加到列表，需手动删除。
大数据量优化：项过多时性能下降，建议改用 QListView + QAbstractItemModel 实现虚拟滚动。
自定义控件谨慎使用：大量复杂控件作为项可能导致界面卡顿。

7. 示例代码

// 创建列表并添加项
QListWidget* listWidget = new QListWidget();
listWidget->addItems(QStringList() << "Apple" << "Banana" << "Orange");

// 响应项双击
connect(listWidget, &QListWidget::itemDoubleClicked, [](QListWidgetItem* item) {
    qDebug() << "Double-clicked:" << item->text();
});

// 启用多选和排序
listWidget->setSelectionMode(QAbstractItemView::ExtendedSelection);
listWidget->setSortingEnabled(true);