PyQt5 QTreeWidget 树形控件详解：从基础用法到事件处理与系统模式

陆景行

发布时间：2026-10-13 | 6人浏览过

原创

本文深入解析PyQt5中的QTreeWidget树形结构控件，涵盖其基于Item的交互机制及与QTreeView的区别。通过完整代码实例，演示如何添加节点、设置选中状态与背景颜色，并实现点击事件以获取Key和Value。此外，还介绍了利用QDirModel实现系统文件系统树列表的高级用法，帮助开发者掌握灵活的数据与显示分离技巧。

PyQt5树形结构控件QTreeWidget简介

QTreeWidget 类依据预设模型提供树形显示功能。

QTreeWidget 采用类似 QListView 的方式，提供典型的基于 item 的树形交互接口。该类基于 Qt 的“模型/视图”架构，内置默认模型以支持 QTreeWidgetItem 类实例的显示。

若无需使用灵活的“模型/视图”框架，可直接使用 QTreeWidget 构建具有层级关系的树形结构。当标准 item 模型与 QTreeView 结合使用时，能实现更灵活的数据与显示分离方案。

QTreeWidget类中的常用方法

方法	描述
setColumnWidth(int column,int width)	将指定列的宽度设置为给定的值
	Column：指定的列
	width：指定的宽度
insertTopLevelItems()	在视图的顶层索引中引入项目的列表
expandAll()	展开所有节点的树形节点
invisibleRootItem()	返回树形控件中不可见的根选项（Root Item）
selectionItems()	返回所有选定的非隐藏项目的列表内

QTreeWidgetItem类中常用的方法

方法	描述
addChild()	将子项追加到子列表中
setText()	设置显示的节点文本
Text()	返回显示的节点文本
setCheckState(column.state)	设置指定列的选中状态：
	Qt.Checked:节点选中
	Qt.Unchecked:节点没有选中
setIcon(column,icon)	在指定的列中显示图标

QTreeWidget树形结构控件的实例

树形结构由 QTreeWidget 和 QTreeWidgetItem 类共同实现，其中 QTreeWidgetItem 负责节点的添加，完整代码如下：


import sys
from PyQt5.QtWidgets import *
from PyQt5.QtGui import QIcon, QBrush, QColor
from PyQt5.QtCore import Qt


class TreeWidgetDemo(QMainWindow):
  def __init__(self, parent=None):
    super(TreeWidgetDemo, self).__init__(parent)
    self.setWindowTitle('TreeWidget 例子')

    self.tree=QTreeWidget()
    #设置列数
    self.tree.setColumnCount(2)
    #设置树形控件头部的标题
    self.tree.setHeaderLabels(['Key','Value'])

    #设置根节点
    root=QTreeWidgetItem(self.tree)
    root.setText(0,'Root')
    root.setIcon(0,QIcon('./images/root.png'))

    # todo 优化2 设置根节点的背景颜色
    brush_red=QBrush(Qt.red)
    root.setBackground(0,brush_red)
    brush_blue=QBrush(Qt.blue)
    root.setBackground(1,brush_blue)

    #设置树形控件的列的宽度
    self.tree.setColumnWidth(0,150)

    #设置子节点1
    child1=QTreeWidgetItem()
    child1.setText(0,'child1')
    child1.setText(1,'ios')
    child1.setIcon(0,QIcon('./images/IOS.png'))

    #todo 优化1 设置节点的状态
    child1.setCheckState(0,Qt.Checked)

    root.addChild(child1)


    #设置子节点2
    child2=QTreeWidgetItem(root)
    child2.setText(0,'child2')
    child2.setText(1,'')
    child2.setIcon(0,QIcon('./images/android.png'))

    #设置子节点3
    child3=QTreeWidgetItem(child2)
    child3.setText(0,'child3')
    child3.setText(1,'android')
    child3.setIcon(0,QIcon('./images/music.png'))



    #加载根节点的所有属性与子控件
    self.tree.addTopLevelItem(root)

    #TODO 优化3 给节点添加响应事件
    self.tree.clicked.connect(self.onClicked)


    #节点全部展开
    self.tree.expandAll()
    self.setCentralWidget(self.tree)

  def onClicked(self,qmodeLindex):
    item=self.tree.currentItem()
    print('Key=%s,value=%s'%(item.text(0),item.text(1)))

if __name__ == '__main__':
  app = QApplication(sys.argv)
  tree = TreeWidgetDemo()
  tree.show()
  sys.exit(app.exec_())

初始运行界面如下所示：

优化一：设置节点的状态

此处为 child1 节点添加选中状态设置。

child1.setCheckState(0,Qt.Checked)

优化二：设置节点的背景颜色

此处为根节点设置背景颜色。

brush_red=QBrush(Qt.red)

root.setBackground(0,brush_red)

brush_blue=QBrush(Qt.blue)

root.setBackground(1,brush_blue)

优化三：给节点添加响应事件

点击节点时，控制台将输出当前节点的 key 值与 value 值。

self.tree.clicked.connect(self.onClicked)

def onClicked(self,qmodeLindex):

item=self.tree.currentItem()

print('Key=%s,value=%s'%(item.text(0),item.text(1)))

系统定制模式实例

在上述示例中，QTreeWidgetItem 的节点是逐个添加的，这在构建复杂树形结构时较为不便。通常，对于复杂的树形结构，推荐使用 QTreeView 类而非 QTreeWidget 类。QTreeView 与 QTreeWidget 的主要区别在于，QTreeView 支持使用操作系统提供的定制模型，例如用于显示文件系统磁盘树列表的场景。


import sys
from PyQt5.QtWidgets import *
from PyQt5.QtGui import *

if __name__ == '__main__':
  app=QApplication(sys.argv)

  #window系统提供的模式
  model=QDirModel()
  #创建一个QTreeView的控件
  tree=QTreeView()
  #为控件添加模式
  tree.setModel(model)

  tree.setWindowTitle('QTreeView例子')
  tree.resize(640,480)

  tree.show()
  sys.exit(app.exec_())