QListWedget控件使用指南

QListWedget公共函数

函数签名	功能描述
QListWidget(QWidget *parent = nullptr)	构造函数，创建一个QListWidget对象，可指定父部件（默认为nullptr）。
virtual ~QListWidget()	虚析构函数，释放QListWidget对象及其资源。
void addItem(QListWidgetItem *item)	向列表末尾添加一个已有的QListWidgetItem项。
void addItem(const QString &label)	创建一个新项（QListWidgetItem）并添加至列表末尾，文本内容为label。
void addItems(const QStringList &labels)	批量创建新项并添加至列表末尾，文本内容为labels列表中的每个字符串。
void closePersistentEditor(QListWidgetItem *item)	关闭与指定项关联的持久编辑器（persistent editor）。
int count() const	返回列表中项的总数。
QListWidgetItem *currentItem() const	返回当前选中的项（若未选中则返回nullptr）。
int currentRow() const	返回当前选中项的行号（从0开始计数，无选中项时返回-1）。
void editItem(QListWidgetItem *item)	触发指定项的编辑模式（例如用户双击后的编辑状态）。
QList<QListWidgetItem *> findItems(const QString &text, Qt::MatchFlags flags) const	根据text和匹配标志flags查找匹配的项，返回结果列表。
QModelIndex indexFromItem(const QListWidgetItem *item) const	返回给定项的模型索引（QModelIndex），用于模型/视图操作。
void insertItem(int row, QListWidgetItem *item)	在指定行row插入一个已有的项。
void insertItem(int row, const QString &label)	在指定行row创建一个新项并插入，文本内容为label。
void insertItems(int row, const QStringList &labels)	在指定行row插入多个新项，文本内容为labels列表中的每个字符串。
bool isPersistentEditorOpen(QListWidgetItem *item) const	检查指定项是否已打开持久编辑器，返回true表示已打开。
bool isSortingEnabled() const	返回是否启用了自动排序功能（true表示启用）。
QListWidgetItem *item(int row) const	返回指定行row的项（若行号无效返回nullptr）。
QListWidgetItem *itemAt(const QPoint &p) const	返回位于坐标点p处的项（基于列表视口的坐标系）。
QListWidgetItem *itemAt(int x, int y) const	返回位于坐标(x, y)处的项（基于列表视口的坐标系）。
QListWidgetItem *itemFromIndex(const QModelIndex &index) const	从模型索引index获取对应的项。
QWidget *itemWidget(QListWidgetItem *item) const	返回与指定项关联的自定义部件（若未设置返回nullptr）。
QList<QListWidgetItem *> items(const QMimeData *data) const	从拖放操作的MIME数据data中解析出关联的项列表（用于拖放事件处理）。
void openPersistentEditor(QListWidgetItem *item)	为指定项打开持久编辑器（编辑器将一直显示，直到手动关闭）。
void removeItemWidget(QListWidgetItem *item)	移除与指定项关联的自定义部件。
int row(const QListWidgetItem *item) const	返回指定项的行号（从0开始计数，若项不存在返回-1）。
QList<QListWidgetItem *> selectedItems() const	返回所有当前选中的项的列表。
void setCurrentItem(QListWidgetItem *item)	设置指定项为当前选中项。
void setCurrentItem(QListWidgetItem *item, QItemSelectionModel::SelectionFlags command)	设置指定项为当前选中项，并使用command标志控制选择行为（如选中、切换等）。
void setCurrentRow(int row)	设置指定行row为当前选中行。
void setCurrentRow(int row, QItemSelectionModel::SelectionFlags command)	设置指定行row为当前选中行，并使用command标志控制选择行为。
void setItemWidget(QListWidgetItem *item, QWidget *widget)	为指定项设置自定义部件widget（覆盖项的默认显示方式）。
void setSortingEnabled(bool enable)	启用或禁用自动排序功能（enable为true时，添加项会自动按排序规则插入）。
void sortItems(Qt::SortOrder order = Qt::AscendingOrder)	按指定顺序（升序或降序）对所有项进行排序。
QListWidgetItem *takeItem(int row)	移除并返回指定行row的项（项不会被删除，可重新插入到其他位置）。
QRect visualItemRect(const QListWidgetItem *item) const	返回指定项在列表视口中的可视区域矩形（坐标和尺寸）。

 QListWedget信号

信号签名	触发条件与功能描述
void currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)	当当前选中项发生变化时触发。current为新的当前项，previous为之前的当前项（可能为nullptr）。
void currentRowChanged(int currentRow)	当当前选中项的行号发生变化时触发。currentRow为新的行号（无选中项时为-1）。
void currentTextChanged(const QString &currentText)	当当前选中项的文本发生变化时触发。currentText为新的文本内容（无选中项时为空字符串）。
void itemActivated(QListWidgetItem *item)	当用户激活某个项（如双击或按回车键）时触发。item为被激活的项。
void itemChanged(QListWidgetItem *item)	当项的内容（如文本、图标等）被修改时触发。item为被修改的项。
void itemClicked(QListWidgetItem *item)	当用户单击某个项时触发。item为被点击的项。
void itemDoubleClicked(QListWidgetItem *item)	当用户双击某个项时触发。item为被双击的项。
void itemEntered(QListWidgetItem *item)	当鼠标光标进入某个项的可视区域时触发（通常用于悬停效果）。item为对应的项。
void itemPressed(QListWidgetItem *item)	当用户按下鼠标按键（未释放）在某个项上时触发。item为被按下的项。
void itemSelectionChanged()	当选中项的集合发生变化（如选中、取消选中或切换）时触发。此信号无参数。

 QListWidgetItem函数

函数签名	功能描述
QListWidgetItem(QListWidget *parent = nullptr, int type = Type)	构造函数，创建一个空项，可指定父列表控件parent和项类型type（默认为Type）。
QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)	构造函数，创建带有文本text的项，可指定父列表控件和类型。
QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)	构造函数，创建带有图标icon和文本text的项，可指定父列表控件和类型。
QListWidgetItem(const QListWidgetItem &other)	拷贝构造函数，复制另一个项other的属性。
virtual ~QListWidgetItem()	虚析构函数，释放项的资源。
QBrush background() const	返回项的背景画刷（颜色或渐变）。
Qt::CheckState checkState() const	返回项的勾选状态（如未选中、部分选中、完全选中）。
virtual QListWidgetItem *clone() const	虚函数，创建并返回当前项的副本。
virtual QVariant data(int role) const	返回项中指定角色role（如文本、图标、对齐等）对应的数据。
Qt::ItemFlags flags() const	返回项的标志（如是否可选中、可编辑等）。
QFont font() const	返回项的字体。
QBrush foreground() const	返回项的前景画刷（文本颜色）。
QIcon icon() const	返回项的图标。
bool isHidden() const	返回项是否被隐藏。
bool isSelected() const	返回项是否被选中。
QListWidget *listWidget() const	返回项所属的父列表控件（若无则返回nullptr）。
virtual void read(QDataStream &in)	从数据流in中读取项的内容（用于序列化）。
void setBackground(const QBrush &brush)	设置项的背景画刷。
void setCheckState(Qt::CheckState state)	设置项的勾选状态。
virtual void setData(int role, const QVariant &value)	设置项中指定角色role对应的数据为value。
void setFlags(Qt::ItemFlags flags)	设置项的标志（如禁用、可拖拽等）。
void setFont(const QFont &font)	设置项的字体。
void setForeground(const QBrush &brush)	设置项的前景画刷（文本颜色）。
void setHidden(bool hide)	设置是否隐藏项（hide为true时隐藏）。
void setIcon(const QIcon &icon)	设置项的图标。
void setSelected(bool select)	设置项是否被选中。
void setSizeHint(const QSize &size)	设置项的推荐显示尺寸。
void setStatusTip(const QString &statusTip)	设置项的状态栏提示文本（鼠标悬停时显示在状态栏）。
void setText(const QString &text)	设置项的显示文本。
(since 6.4) void setTextAlignment(Qt::Alignment alignment)	(Qt 6.4新增) 设置项的文本对齐方式（如左对齐、居中对齐）。
void setToolTip(const QString &toolTip)	设置项的悬浮提示文本（鼠标悬停时显示）。
void setWhatsThis(const QString &whatsThis)	设置项的“这是什么？”帮助文本（通过帮助按钮触发）。
QSize sizeHint() const	返回项的推荐显示尺寸。
QString statusTip() const	返回项的状态栏提示文本。
QString text() const	返回项的显示文本。
int textAlignment() const	返回项的文本对齐方式（以Qt::Alignment枚举值的整数形式表示）。
QString toolTip() const	返回项的悬浮提示文本。
int type() const	返回项的类型（用于自定义项类型的区分）。
QString whatsThis() const	返回项的“这是什么？”帮助文本。
virtual void write(QDataStream &out) const	将项的内容写入数据流out（用于序列化）。
virtual bool operator<(const QListWidgetItem &other) const	定义项的小于比较规则（默认按文本排序，可重载实现自定义排序逻辑）。
QListWidgetItem &operator=(const QListWidgetItem &other)	赋值运算符，将另一个项other的属性复制到当前项。

 实践

ui效果如下

有一个显示控件：qlistwidget，初始化的时候用他的additem函数添加三个项

ui->listWidget->addItem("c++");
ui->listWidget->addItem("java");
ui->listWidget->addItem("好好学习");

 在ui界面点击提交会把lineediter里面的文本添加为listwidget的项，注意，在ui里面添加的槽不需要用connect连接，已经连接过了，如果再用会连续触发两次。

void MainWindow::on_btnclicked_clicked()
{//获取lineediter里面的文本QString str=ui->lineEdit->text();//如果内容为空，不执行if(str.isEmpty()){return;}ui->listWidget->addItem(str);
}

删除按钮同理，用takeitem删除选中项

void MainWindow::on_btndel_clicked()
{int row =ui->listWidget->currentRow();if(row<0){qDebug()<<"没有选中任何项";return;}qDebug()<<"第"<<row<<"行已被删除";ui->listWidget->takeItem(row);
}

完整代码如下： 

#include "mainwindow.h"
#include "ui_mainwindow.h"
#include<QString>
#include<QDebug>MainWindow::MainWindow(QWidget *parent): QMainWindow(parent), ui(new Ui::MainWindow)
{ui->setupUi(this);ui->listWidget->addItem("c++");ui->listWidget->addItem("java");ui->listWidget->addItem("好好学习");//连接槽函数,这里连接槽函数是不对的，在ui界面点击转到槽是默认有链接的，用connect会重复出发信号导致出错//connect(ui->btnclicked,&QPushButton::clicked,this,&MainWindow::on_btnclicked_clicked);// connect(ui->btndel,&QPushButton::clicked,this,&MainWindow::on_btndel_clicked);
}MainWindow::~MainWindow()
{delete ui;
}void MainWindow::on_btndel_clicked()
{int row =ui->listWidget->currentRow();if(row<0){qDebug()<<"没有选中任何项";return;}qDebug()<<"第"<<row<<"行已被删除";ui->listWidget->takeItem(row);
}//将plainedit里面的文本加进listwidget
void MainWindow::on_btnclicked_clicked()
{//获取lineediter里面的文本QString str=ui->lineEdit->text();//如果内容为空，不执行if(str.isEmpty()){return;}ui->listWidget->addItem(str);
}//当前项变化
void MainWindow::on_listWidget_currentItemChanged(QListWidgetItem *current, QListWidgetItem *previous)
{if(current!=nullptr){qDebug()<<"当前项为："<<current->text();}if(previous!=nullptr){qDebug()<<"之前项为："<<previous->text();}
}