PySide6之QListWidget 学习-编程实验室

QListWidget 是 PySide6 中封装了数据模型的便捷列表控件（基于 Model/View 架构，但内置了QListWidgetItem数据项，无需手动创建模型），适用于快速实现简单列表、少量数据展示的场景，相比 QListView 更易上手，开箱即用。

一、核心特性

开箱即用：内置数据模型，直接通过QListWidgetItem管理列表项，无需手动绑定 Model；
轻量简洁：适合少量数据（几十 / 几百项）的列表展示，API 直观；
基础定制：支持文本、图标、复选框、颜色等基础样式定制；
交互支持：单选 / 多选、编辑、拖拽、右键菜单等；
局限性：数据与界面耦合，海量数据性能不如 QListView，定制化能力较弱。

二、基础使用步骤

from PySide6.QtWidgets import ( QApplication, QMainWindow, QListWidget, QListWidgetItem, QVBoxLayout, QWidget, QMenu ) from PySide6.QtCore import Qt, QPoint from PySide6.QtGui import QIcon, QColor, QFont import sys

2. 最简示例（纯文本列表）

import sys from PySide6.QtWidgets import ( QApplication, QListWidget, QListWidgetItem, QVBoxLayout, QWidget ) class MainWindow(QWidget): def __init__(self): super().__init__() self.setWindowTitle("QListWidget 基础示例") self.resize(400, 300) # 1. 创建布局 layout = QVBoxLayout(self) # 2. 创建 QListWidget self.list_widget = QListWidget() layout.addWidget(self.list_widget) # 3. 添加列表项（三种方式） # 方式1：直接添加文本 self.list_widget.addItem("Python") # 方式2：创建 QListWidgetItem 后添加 item2 = QListWidgetItem("PySide6") self.list_widget.addItem(item2) # 方式3：批量添加 self.list_widget.addItems(["QListWidget", "便捷列表控件"]) # 4. 基础配置 self.list_widget.setEditTriggers(QListWidget.EditTrigger.DoubleClicked) # 双击编辑 self.list_widget.setSelectionMode(QListWidget.SelectionMode.SingleSelection) # 单选 # 5. 信号绑定（选中项变化） self.list_widget.currentItemChanged.connect(self.on_current_item_changed) def on_current_item_changed(self, current: QListWidgetItem, previous: QListWidgetItem): """选中项变化触发""" if current: print(f"当前选中：{current.text()}") if __name__ == "__main__": app = QApplication(sys.argv) window = MainWindow() window.show() sys.exit(app.exec())

3. 进阶示例（带图标 / 复选框 / 自定义数据）

python

运行

class AdvancedListWidget(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle("QListWidget 进阶示例") self.resize(400, 300) central_widget = QWidget() self.setCentralWidget(central_widget) layout = QVBoxLayout(central_widget) # 1. 创建 QListWidget self.list_widget = QListWidget() layout.addWidget(self.list_widget) # 2. 添加带自定义样式的项 items = [ ("Python", True, "python.png"), # 文本、复选框状态、图标路径 ("PySide6", False, "qt.png"), ("QListWidget", True, "list.png") ] for text, checked, icon_path in items: item = QListWidgetItem(text) # 启用复选框 item.setCheckState(Qt.CheckState.Checked if checked else Qt.CheckState.Unchecked) # 设置图标（替换为实际路径） item.setIcon(QIcon(icon_path)) # 自定义数据（通过角色存储） item.setData(Qt.ItemDataRole.UserRole, f"备注：{text}") # 设置前景色（文字颜色） item.setForeground(QColor(255, 0, 0) if checked else QColor(0, 0, 0)) # 设置背景色 item.setBackground(QColor(240, 240, 240)) # 添加到列表 self.list_widget.addItem(item) # 3. 信号绑定（双击项） self.list_widget.itemDoubleClicked.connect(self.on_item_double_clicked) def on_item_double_clicked(self, item: QListWidgetItem): """双击项触发""" # 获取项的属性 text = item.text() check_state = item.checkState() custom_data = item.data(Qt.ItemDataRole.UserRole) print(f"双击：{text} | 复选框：{check_state} | 自定义数据：{custom_data}") # 修改项文本 item.setText(f"[{text}]") if __name__ == "__main__": app = QApplication(sys.argv) window = AdvancedListWidget() window.show() sys.exit(app.exec())

三、关键配置与属性

1. 选择模式（与 QListView 一致）

模式	说明
`QListWidget.NoSelection`	不可选
`QListWidget.SingleSelection`	单选（默认）
`QListWidget.MultiSelection`	多选（点击切换选中状态）
`QListWidget.ExtendedSelection`	扩展多选（Ctrl/Shift 辅助）
`QListWidget.ContiguousSelection`	连续多选（拖拽选择）

self.list_widget.setSelectionMode(QListWidget.SelectionMode.ExtendedSelection) # 设置选择行为（选中整行/仅文本） self.list_widget.setSelectionBehavior(QListWidget.SelectionBehavior.SelectRows)

2. 编辑触发方式

# 禁止编辑（默认） self.list_widget.setEditTriggers(QListWidget.EditTrigger.NoEditTriggers) # 双击编辑 self.list_widget.setEditTriggers(QListWidget.EditTrigger.DoubleClicked) # 点击编辑 self.list_widget.setEditTriggers(QListWidget.EditTrigger.SelectedClicked) # 任意按键触发编辑 self.list_widget.setEditTriggers(QListWidget.EditTrigger.AnyKeyPressed) # 组合触发 self.list_widget.setEditTriggers( QListWidget.EditTrigger.DoubleClicked | QListWidget.EditTrigger.AnyKeyPressed )

3. 外观与布局

# 列表项间距 self.list_widget.setSpacing(8) # 边距 self.list_widget.setContentsMargins(10, 10, 10, 10) # 设置字体 font = QFont() font.setPointSize(12) font.setBold(True) self.list_widget.setFont(font) # 隐藏滚动条 self.list_widget.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff) # 设置图标大小 self.list_widget.setIconSize(QSize(32, 32)) # 启用交替行背景色 self.list_widget.setAlternatingRowColors(True)

4. 显示模式

QListWidget 也支持列表 / 图标模式（继承自 QListView）：

# 列表模式（默认） self.list_widget.setViewMode(QListWidget.ViewMode.ListMode) # 图标模式 self.list_widget.setViewMode(QListWidget.ViewMode.IconMode)

四、常用操作（增删改查）

1. 添加项

# 单个文本项 self.list_widget.addItem("新项") # 单个自定义项 item = QListWidgetItem("自定义项") item.setIcon(QIcon("icon.png")) self.list_widget.addItem(item) # 批量添加 self.list_widget.addItems(["项1", "项2", "项3"]) # 插入项（指定位置） self.list_widget.insertItem(0, "插入到第0行")

2. 修改项

# 获取指定位置的项 item = self.list_widget.item(0) # 第0行 # 修改文本 item.setText("修改后的文本") # 修改图标 item.setIcon(QIcon("new_icon.png")) # 修改复选框状态 item.setCheckState(Qt.CheckState.Checked) # 修改字体 item.setFont(QFont("Arial", 14))

3. 删除项

# 删除指定位置的项 self.list_widget.takeItem(0) # 删除第0行（返回被删除的 item，可手动释放） # 删除选中项 selected_items = self.list_widget.selectedItems() for item in selected_items: row = self.list_widget.row(item) self.list_widget.takeItem(row) # 清空所有项 self.list_widget.clear()

4. 查询项

# 获取指定位置的项 item = self.list_widget.item(2) if item: print(f"第2行文本：{item.text()}") # 获取所有项 count = self.list_widget.count() for i in range(count): item = self.list_widget.item(i) print(f"第{i}行：{item.text()}") # 获取选中项 selected_items = self.list_widget.selectedItems() for item in selected_items: print(f"选中项：{item.text()}") # 获取当前选中的项（单个） current_item = self.list_widget.currentItem() if current_item: print(f"当前项：{current_item.text()}") # 查找文本匹配的项 matching_items = self.list_widget.findItems("Python", Qt.MatchFlag.MatchContains) for item in matching_items: print(f"匹配项：{item.text()}")

五、常用信号

信号	说明
`currentItemChanged(QListWidgetItem, QListWidgetItem)`	当前选中项变化（当前项 / 前一项）
`itemClicked(QListWidgetItem)`	点击项时触发
`itemDoubleClicked(QListWidgetItem)`	双击项时触发
`itemPressed(QListWidgetItem)`	按下鼠标时触发
`itemActivated(QListWidgetItem)`	激活项（回车 / 双击）时触发
`itemChanged(QListWidgetItem)`	项内容变化时触发（如编辑文本、复选框状态）

# 项内容变化信号 self.list_widget.itemChanged.connect(lambda item: print(f"项变化：{item.text()}"))

六、高级功能

1. 右键菜单

右键菜单的详细知识见：https://blog.csdn.net/xulibo5828/article/details/145934195

def __init__(self): # ... 其他初始化代码 ... # 绑定右键菜单 self.list_widget.setContextMenuPolicy(Qt.ContextMenuPolicy.CustomContextMenu) self.list_widget.customContextMenuRequested.connect(self.show_context_menu) def show_context_menu(self, pos: QPoint): """显示右键菜单""" menu = QMenu() # 获取右键点击的项 item = self.list_widget.itemAt(pos) if item: # 为选中项添加菜单 menu.addAction("删除", lambda: self.list_widget.takeItem(self.list_widget.row(item))) menu.addAction("切换复选框", lambda: item.setCheckState( Qt.CheckState.Unchecked if item.checkState() == Qt.CheckState.Checked else Qt.CheckState.Checked )) # 通用菜单 menu.addAction("添加项", lambda: self.list_widget.addItem("新项")) menu.addAction("清空", self.list_widget.clear) # 显示菜单（转换为全局坐标） menu.exec(self.list_widget.mapToGlobal(pos))

2. 拖拽功能

启用项的拖拽（默认禁用）：

# 启用拖拽（项可被拖拽） self.list_widget.setDragEnabled(True) # 启用放置（可接收拖拽的项） self.list_widget.setAcceptDrops(True) # 设置拖拽模式（内部移动/外部复制） self.list_widget.setDragDropMode(QListWidget.DragDropMode.InternalMove) # 设置拖拽行为 self.list_widget.setDefaultDropAction(Qt.DropAction.MoveAction)

3. 排序

# 升序排序 self.list_widget.sortItems(Qt.SortOrder.AscendingOrder) # 降序排序 self.list_widget.sortItems(Qt.SortOrder.DescendingOrder)

七、QListWidget vs QListView

QlistView的学习见：https://blog.csdn.net/xulibo5828/article/details/156539871

维度	QListWidget	QListView
架构	封装了 Model（QListModel），直接操作 Item	纯 View，需手动绑定 Model
上手难度	低（API 直观，开箱即用）	中（需理解 Model/View 架构）
数据量	适合少量数据（<1000 项）	适合海量数据（性能优化更好）
定制性	低（仅支持基础样式，无法深度定制）	高（自定义 Model/Delegate）
灵活性	低（数据与界面耦合）	高（数据与界面解耦，可复用 Model）