前言
Qt版本:6.8.0
該類用于列表模型/視圖
QListWidgetItem函數介紹
作用
QListWidget是Qt框架中用于管理可交互列表項的核心組件,主要作用包括:
- 列表項管理
- 支持動態添加/刪除項:
addItem()
,takeItem()
- 批量操作:
addItems()
添加多個項 - 排序功能:
sortItems()
自動排序
- 交互功能
# 創建列表控件
list_widget = QListWidget()# 添加圖標項
list_widget.addItem(QListWidgetItem(QIcon("icon.png"), "帶圖標的項"))# 信號處理
list_widget.itemClicked.connect(handle_click)
- 顯示控制
- 支持多種視圖模式:
setViewMode(QListView.IconMode)
- 自定義項樣式:通過
setItemWidget()
嵌入自定義控件 - 調整布局:
setFlow(QListView.LeftToRight)
控制排列方向
- 數據綁定
- 直接存取項數據:
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 ¤tText)
- 觸發時機:當前選中項的文本發生改變(包括切換選中項或直接修改項文本)
- 參數:
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();});
信號對比表
信號名稱 | 觸發動作 | 傳遞參數 | 適用場景 |
---|---|---|---|
currentItemChanged | 選中項改變 | 新舊項指針 | 焦點跟蹤 |
currentRowChanged | 選中行改變 | 行號 | 行號相關操作 |
currentTextChanged | 選中項文本變化 | 新文本 | 文本監控 |
itemActivated | 雙擊/回車激活 | 被激活的項 | 執行默認操作 |
itemChanged | 項數據修改 | 被修改的項 | 數據同步 |
itemClicked | 單擊項 | 被點擊的項 | 簡單交互 |
itemDoubleClicked | 雙擊項 | 被雙擊的項 | 快速操作 |
itemEntered | 鼠標懸停進入項區域 | 被懸停的項 | 提示信息 |
itemPressed | 按下鼠標按鈕 | 被按下的項 | 拖拽起點判斷 |
itemSelectionChanged | 選中項集合變化(多選模式) | 無 | 批量操作 |
使用建議
- 避免信號循環:在槽函數中修改項數據時,注意不要觸發自身信號(例如在
itemChanged
中再次修改項) - 性能優化:對高頻信號(如
itemEntered
)進行防抖處理 - 多選模式:使用
itemSelectionChanged
配合selectedItems()
獲取所有選中項 - 數據同步:優先使用
itemChanged
而非currentTextChanged
跟蹤數據變化,后者僅監控當前項
其他函數
示例
#include <QApplication>
#include <QListWidget>
#include <QListWidgetItem>
#include <QIcon>
#include <QMessageBox>int main(int argc, char *argv[])
{QApplication app(argc, argv);// 創建 QListWidgetQListWidget 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 ? "已選中" : "未選中");elseinfo += "無";info += "\n";info += "自定義數據: " + item->data(Qt::UserRole).toString() + "\n";info += "提示: " + item->toolTip() + "\n";QMessageBox::information(&listWidget, "項信息", info);});listWidget.show();return app.exec();
}