Qt开发：QListWidget的介绍和使用

一、QListWidget的简介

  QListWidget 是 Qt 框架中用于显示和操作条目列表的控件，它是 QListView 的一个子类，提供了更高层级的封装，允许你以面向 item 的方式 管理列表内容。

二、QListWidget的基本用法

#include <QListWidget>
#include <QDebug>

MainWindow::MainWindow(QWidget *parent)
    : QWidget(parent)
{
   
   
    this->setFixedSize(800, 600);

    QListWidget* listWidget = new QListWidget(this);

    // 添加文本项
    listWidget->addItem("Apple");
    listWidget->addItem("Banana");

    // 添加带图标的项
    QListWidgetItem* item = new QListWidgetItem(QIcon(":/icons/pineapple.png"), "Pineapple");
    listWidget->addItem(item);

    // 设置多选模式
    listWidget->setSelectionMode(QAbstractItemView::MultiSelection);

    // 响应点击事件
    connect(listWidget, &QListWidget::itemClicked, this, [](QListWidgetItem* item){
   
   
        qDebug() << "你点击了: " << item->text();
    });
}

三、QListWidget的数据操作

2.1 插入数据

2.1.1 void QListWidget::addItem(const QString &label)
作用：用于向列表中添加一个文本条目。
参数：label：要显示的文本内容（QString 类型）。

效果：

• 在列表末尾添加一个新项，内容为 label。
• 内部自动创建一个 QListWidgetItem 并加入 QListWidget。

示例用法：

QListWidget* listWidget = new QListWidget(this);

// 添加几个条目
listWidget->addItem("苹果");
listWidget->addItem("香蕉");
listWidget->addItem("葡萄");

2.1.2 void QListWidget::addItems(const QStringList &labels)
作用：用于批量添加多个条目到列表中，每个条目都是一个文本项。
参数：labels：一个 QStringList 类型的字符串列表，每个字符串会变成一个条目。

示例用法：

QStringList fruits;
fruits << "苹果" << "香蕉" << "葡萄" << "橘子";

QListWidget* listWidget = new QListWidget(this);
listWidget->addItems(fruits);

这将向列表中依次添加 4 个条目，文本分别是 “苹果”、“香蕉”、“葡萄” 和 “橘子”。

2.1.3 void QListWidget::addItem(QListWidgetItem *item)
作用：用于向列表中添加一个自定义的条目对象。
参数：item：指向一个 QListWidgetItem 对象的指针，表示你要添加的条目。

效果：

• 将该条目插入到列表末尾。
• QListWidget 会自动接管该对象的所有权，无需手动释放。

示例用法：添加带图标和自定义样式的项

QListWidget* listWidget = new QListWidget(this);

// 创建一个自定义的条目
QListWidgetItem* item = new QListWidgetItem(QIcon(":/icons/star.png"), "重要任务");

// 设置附加样式
item->setFont(QFont("Microsoft YaHei", 12, QFont::Bold));
item->setForeground(Qt::red);
item->setBackground(Qt::yellow);
item->setToolTip("这是一个高优先级任务");

// 添加到列表中
listWidget->addItem(item);

使用 setData() 来绑定自定义数据：
在 Qt 中，setData() 是 QListWidgetItem 的成员函数，用于将自定义数据绑定到某个列表项上，便于后续查找、操作或传递附加信息。

函数原型：

void QListWidgetItem::setData(int role, const QVariant &value);

参数说明：

• role：数据的“角色”，例如 Qt::UserRole、Qt::DisplayRole
• value：任意类型的数据，必须能被包装成 QVariant（如 int, QString, bool, QPointF, 自定义结构体等）

常用角色：

• Qt::UserRole：开发者自定义使用的第一个角色。
• Qt::UserRole + 1, +2, …：可自定义多个字段。
• Qt::DisplayRole：值为0，控制 item 的主显示文本。
• Qt::ToolTipRole：值为3，控制鼠标悬停提示。

示例：绑定一个 ID 到列表项

QListWidget* listWidget = new QListWidget(this);

QListWidgetItem* item = new QListWidgetItem("任务一");
item->setData(Qt::UserRole, 101); // 绑定任务 ID
listWidget->addItem(item);

// 点击时读取 ID
connect(listWidget, &QListWidget::itemClicked, this, [](QListWidgetItem* item){
   
   
    int taskId = item->data(Qt::UserRole).toInt();
    qDebug() << "点击任务 ID:" << taskId;
});

进阶用法：绑定多个字段

QListWidgetItem* item = new QListWidgetItem("设备 A");
item->setData(Qt::UserRole, 42);              // 设备ID
item->setData(Qt::UserRole + 1, "在线");      // 状态
item->setData(Qt::UserRole + 2, QColor("green"));  // 状态颜色
listWidget->addItem(item);

读取方式：

int deviceId = item->data(Qt::UserRole).toInt();
QString status = item->data(Qt::UserRole + 1).toString();
QColor color = item->data(Qt::UserRole + 2).value<QColor>();

自定义结构体绑定：
如果你有一个结构体，也可以用 QVariant 包装它，只要注册了类型：

struct TaskInfo {
   
   
    int id;
    QString name;
};
Q_DECLARE_METATYPE(TaskInfo)

注册类型：

qRegisterMetaType<TaskInfo>("TaskInfo");

绑定使用：

TaskInfo info = {
   
   123, "检查任务"};
QVariant var;
var.setValue(info);

QListWidgetItem* item = new QListWidgetItem("任务123");
item->setData(Qt::UserRole, var);

如何注册自定义结构体到 QVariant?

步骤一：定义并声明结构体
1.定义结构体并使用 Q_DECLARE_METATYPE

struct TaskInfo {
   
   
    int id;
    QString name;
};
Q_DECLARE_METATYPE(TaskInfo)  // 必须放在 struct 定义之后

Q_DECLARE_METATYPE 告诉 Qt 怎么将 TaskInfo 包装进 QVariant。

步骤二：注册类型
2. 在主函数或初始化阶段注册

#include <QMetaType>

// 一般在 main() 或 QApplication 初始化前注册
int main(int argc, char *argv[]) {
   
   
    qRegisterMetaType<TaskInfo>("TaskInfo");

    QApplication app(argc, argv);
    ...
}

如果只打算把它塞进 QVariant（不跨线程、不用信号槽传输），可以省略 qRegisterMetaType，只用 Q_DECLARE_METATYPE。

示例：绑定结构体到 QListWidgetItem

TaskInfo task{
   
   101, "图像识别任务"};

QVariant v;
v.setValue(task);

QListWidgetItem* item = new QListWidgetItem(task.name);
item->setData(Qt::UserRole, v);
listWidget->addItem(item);

读取时还原结构体：

QVariant v = item->data(Qt::UserRole);
TaskInfo task = v.value<TaskInfo>();
qDebug() << "ID:" << task.id << " Name:" << task.name;

2.1.4 void QListWidget::insertItem(int row, QListWidgetItem *item)
作用：用于在指定位置插入一个自定义的条目（QListWidgetItem）。

参数说明：

• row：插入位置的行索引（从 0 开始）
• item：要插入的条目对象指针（QListWidgetItem*）

使用示例：

QListWidget* listWidget = new QListWidget(this);

// 添加几个初始条目
listWidget->addItem("苹果");
listWidget->addItem("香蕉");

// 创建要插入的新条目
QListWidgetItem* item = new QListWidgetItem("插入的葡