PyQt5中带复选框的多列勾选列表最佳组件及配置方法

在PyQt5里，要实现带复选框的多列勾选列表，我首推QTableWidget——它本身就是为多列数据展示设计的，而且能非常方便地集成复选框实现多选功能，不用自己造太多轮子，日常项目里我用它解决这类需求的频率超高。

核心配置步骤 #

下面是具体的实现和配置方法，我拆成了几个关键步骤，配合代码示例更容易理解：

1. 基础初始化与表头设置 #

先创建QTableWidget实例，设置好列数和对应的列名（也就是你说的不同属性的名称）：

import sys
from PyQt5.QtWidgets import (QApplication, QMainWindow, QTableWidget, 
                             QTableWidgetItem, QWidget, QVBoxLayout)
from PyQt5.QtCore import Qt

class MultiColumnCheckList(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("带复选框的多列列表")
        self.resize(600, 400)

        # 创建主组件和布局
        central_widget = QWidget()
        self.setCentralWidget(central_widget)
        layout = QVBoxLayout(central_widget)

        # 初始化QTableWidget
        self.table_widget = QTableWidget()
        layout.addWidget(self.table_widget)

        # 设置列数和表头
        self.table_widget.setColumnCount(3)  # 假设我们有3个属性列
        self.table_widget.setHorizontalHeaderLabels(["选择", "名称", "类型"])
        # 让表头自适应宽度
        self.table_widget.horizontalHeader().setStretchLastSection(True)

2. 添加带复选框的行与数据 #

接下来给每一行的第一列添加复选框，同时填充其他列的属性数据：

def populate_data(self):
        # 模拟数据，格式为(名称, 类型)
        data_list = [
            ("文件A", "文档"),
            ("图片B", "媒体"),
            ("文件夹C", "目录"),
            ("程序D", "应用")
        ]

        self.table_widget.setRowCount(len(data_list))
        for row_idx, (name, type_) in enumerate(data_list):
            # 第一列：创建带复选框的item
            check_item = QTableWidgetItem()
            check_item.setCheckState(Qt.Unchecked)  # 默认未勾选
            # 设置item为可勾选但不可编辑（避免双击修改文本）
            check_item.setFlags(Qt.ItemIsUserCheckable | Qt.ItemIsEnabled)
            self.table_widget.setItem(row_idx, 0, check_item)

            # 第二列：名称
            name_item = QTableWidgetItem(name)
            name_item.setFlags(Qt.ItemIsEnabled)  # 不可编辑
            self.table_widget.setItem(row_idx, 1, name_item)

            # 第三列：类型
            type_item = QTableWidgetItem(type_)
            type_item.setFlags(Qt.ItemIsEnabled)
            self.table_widget.setItem(row_idx, 2, type_item)

3. 获取选中的条目 #

如果需要获取用户勾选的行，可以写一个方法来遍历所有行，检查复选框状态：

def get_selected_items(self):
        selected = []
        for row_idx in range(self.table_widget.rowCount()):
            check_item = self.table_widget.item(row_idx, 0)
            if check_item.checkState() == Qt.Checked:
                name = self.table_widget.item(row_idx, 1).text()
                type_ = self.table_widget.item(row_idx, 2).text()
                selected.append((name, type_))
        return selected

# 运行示例
if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MultiColumnCheckList()
    window.populate_data()
    window.show()
    # 可以添加按钮触发get_selected_items来测试选中结果
    sys.exit(app.exec_())

额外优化建议 #

• 如果不想让用户编辑其他列的内容，就像示例里那样给非复选框列设置Qt.ItemIsEnabled标记，只保留启用状态，禁止编辑。
• 可以给复选框列设置固定宽度，比如self.table_widget.setColumnWidth(0, 60)，让布局更美观。
• 如果需要全选/反选功能，可以加个按钮，遍历所有行的复选框来切换状态，实现起来也很简单。

内容的提问来源于stack exchange，提问作者Ali Sajjad Rizavi