PySide6之QListWidget 学习

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

一、核心特性

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

选型建议：

• 快速实现简单列表、少量数据 → QListWidget；
• 海量数据、自定义展示、多源数据复用 → QListView + Model。

总结

QListWidget 是 PySide6 中快速实现列表功能的首选控件，适合简单场景：

• 优势：API 简单、上手快、无需理解 Model/View 架构；
• 局限：数据量较大时性能一般，定制化能力弱。

掌握其核心操作（增删改查）、信号绑定、基础样式定制，即可满足大部分简单列表的开发需求；若需更复杂的定制或海量数据展示，建议切换到 QListView + 自定义 Model。