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 ¤tText) | 当当前选中项的文本发生变化时触发。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();}
}
