【PySide6快速入门】QListWidget 列表控件

---

PySide6快速入门：QListWidget 列表控件

前言

在图形用户界面中，列表控件是常用的元素之一。QListWidget 是 PySide6 提供的一个非常方便的控件，它允许开发者在界面上展示一系列可选择或可编辑的项。QListWidget 支持动态添加、删除、编辑列表项，能够适应各种列表展示需求。本文将详细介绍 QListWidget 控件的基本用法，并探讨其常用的函数和功能。

什么是QListWidget？

QListWidget 是 PySide6 中的一个列表控件，允许用户展示一系列的项，可以是简单的文本项，也可以是包含图标、文本等内容的复杂项。它继承自 QListView，但是比 QListView 提供了更简便的 API，适合于不需要自定义模型的情况。

特点：

1. 简单易用： 通过内建的 API，可以快速添加、删除和管理列表项。
2. 支持选择： 支持项的选择，可以选择单个或多个项。
3. 多种展示方式： 支持不同的显示模式，如列表模式、图标模式等。
4. 支持图标和文本： 每个列表项不仅可以显示文本，还可以显示图标、复选框等。
5. 自定义编辑： 支持用户修改项内容，或通过代码动态修改项。

如何使用QListWidget？

1. 基本用法

QListWidget 控件的基本用法非常简单。你可以直接将其添加到布局中，并通过方法添加列表项。

示例代码：

from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout, QListWidgetapp = QApplication([])window = QWidget()
layout = QVBoxLayout()list_widget = QListWidget()  # 创建 QListWidget 控件
list_widget.addItem("Item 1")  # 添加单个项
list_widget.addItem("Item 2")
list_widget.addItem("Item 3")layout.addWidget(list_widget)window.setLayout(layout)
window.show()app.exec()

在这个示例中，我们创建了一个 QListWidget 控件，并添加了三个列表项 "Item 1"、"Item 2" 和 "Item 3"。

2. 添加、删除和修改列表项

你可以使用 addItem()、insertItem() 方法添加新的项，使用 takeItem() 删除指定项，使用 setItemWidget() 修改项的内容。

示例代码：

def add_item():list_widget.addItem("New Item")def remove_item():list_widget.takeItem(0)  # 删除第一个项def modify_item():item = list_widget.item(1)  # 获取第二个项item.setText("Modified Item")  # 修改项的文本# 连接按钮点击事件

3. 设置项的选择模式

你可以设置 QListWidget 控件的选择模式，例如单选、多选或不允许选择。

示例代码：

list_widget.setSelectionMode(QListWidget.SingleSelection)  # 单选模式
list_widget.setSelectionMode(QListWidget.MultiSelection)   # 多选模式

在这个示例中，我们通过 setSelectionMode() 方法设置了列表的选择模式，可以选择单个项或多个项。

4. 响应列表项选择事件

你可以通过信号 itemClicked() 和 itemSelectionChanged() 来响应列表项的选择事件。

示例代码：

def on_item_clicked(item):print(f"Item clicked: {item.text()}")list_widget.itemClicked.connect(on_item_clicked)

在这个示例中，当用户点击列表中的某一项时，会输出该项的文本。

QListWidget 常用函数分类介绍

1. 添加、删除和修改项

• addItem(item)
  添加一个新项到列表末尾。

  • 参数： item：要添加的项，可以是一个文本字符串或 QListWidgetItem 对象。
  • 返回值： 无。

• insertItem(row, item)
  在指定行插入一项。

  • 参数： row：指定插入的行号，item：要插入的项。
  • 返回值： 无。

• takeItem(row)
  删除指定行的项。

  • 参数： row：要删除的项的行号。
  • 返回值： 返回被删除的 QListWidgetItem 对象。

• setItemWidget(item, widget)
  在列表项上设置自定义控件（例如按钮、文本框等）。

  • 参数： item：要设置控件的列表项，widget：要显示的控件（如 QPushButton、QLabel 等）。
  • 返回值： 无。

2. 选择模式和项状态

• setSelectionMode(mode)
  设置选择模式。

  • 参数： mode：选择模式。可以是以下之一：
    • QListWidget.NoSelection：不允许选择任何项。
    • QListWidget.SingleSelection：只允许选择一个项。
    • QListWidget.MultiSelection：允许选择多个项。
    • QListWidget.ExtendedSelection：允许选择多个项，但具有更复杂的选择逻辑。
  • 返回值： 无。

• setItemSelected(item, selected)
  设置指定项的选择状态。

  • 参数： item：要设置选择状态的项，selected：布尔值，True 表示选中，False 表示取消选中。
  • 返回值： 无。

• selectedItems()
  获取所有被选中的项。

  • 返回值： 返回一个包含选中项的列表，每个项是一个 QListWidgetItem 对象。

3. 获取和操作项

• item(row)
  获取指定行的项。

  • 参数： row：指定行号。
  • 返回值： 返回指定行的 QListWidgetItem 对象。

• count()
  获取列表中的项数。

  • 返回值： 返回整数，表示列表中的项数。

4. 排序和显示

• sortItems(order=Qt.AscendingOrder)
  对列表项进行排序。

  • 参数： order：排序顺序，可以是以下之一：
    • Qt.AscendingOrder：升序排列（默认）。
    • Qt.DescendingOrder：降序排列。
  • 返回值： 无。

• clear()
  清除列表中的所有项。

  • 返回值： 无。

• scrollTo(item)
  滚动到指定项。

  • 参数： item：要滚动到的 QListWidgetItem 对象。
  • 返回值： 无。

5. 信号与槽

• itemClicked(item)
  当某项被点击时触发的信号。

  • 返回值： 无。

• itemDoubleClicked(item)
  当某项被双击时触发的信号。

  • 返回值： 无。

• itemSelectionChanged()
  当选中项发生变化时触发的信号。

  • 返回值： 无。

总结

QListWidget 是一个功能强大的控件，适用于显示列表数据。它提供了简单易用的 API，可以方便地添加、删除和修改列表项。通过设置选择模式、排序方式以及项的显示方式，QListWidget 能够满足大多数常见的列表展示需求。此外，它还支持动态更新、项的选择和自定义控件的显示，非常适合用于实现多种功能，如文件选择、任务列表、消息列表等。

掌握 QListWidget 的使用方法，可以帮助你在 PySide6 中快速创建并管理列表式的数据展示，提升应用的交互性和可用性。