class QTreeWidget#

类 QTreeWidget 提供了一个使用预定义树模型的树状视图。)更多...

Inheritance diagram of PySide6.QtWidgets.QTreeWidget

简述#

属性#

方法#

虚方法#

槽函数#

信号#

注意

此文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来告知我们

详细描述#

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

../../_images/windows-treeview.png

QTreeWidget 类是一个便利类，它提供了一种类似于 Qt 3 中 QListView 类使用的经典基于项的接口的标准树控件。该类基于 Qt 的 Model/View 架构，并使用默认模型来保存项，每个项都是一个 QTreeWidgetItem。

不需要 Model/View 框架灵活性的开发人员可以使用此类轻松地创建简单的分层列表。一种更灵活的方法是结合使用 QTreeView 和标准项模型。这允许将数据存储与其表示分离。

在 simplest 形式中，树控件可以这样构建

treeWidget = QTreeWidget()
treeWidget.setColumnCount(1)
*> = QList<QTreeWidgetItem()
for i in range(0, 10):
    items.append(QTreeWidgetItem(QTreeWidget(None), QStringList(QString("item: %1").arg(i))))
treeWidget.insertTopLevelItems(0, items)

在可以添加项到树控件之前，必须使用 setColumnCount() 设置列数。这允许每个项有一个或多个标签或其他装饰。可以通过 columnCount() 函数找到正在使用的列数。

树可以有一个包含每个列的部分的标题。通过 setHeaderLabels() 供应字符串列表来设置每个部分的标签，是最简单的方法，但可以通过使用 QTreeWidgetItem 和使用 setHeaderItem() 函数将自定义标题插入树中。

树中的项目可以根据预定义的排序顺序按列排序。如果启用排序，用户可以通过点击列标题对项目进行排序。可以通过调用setSortingEnabled()来启用或禁用排序。函数isSortingEnabled()指示是否启用了排序。

注意

可以直接使用属性，当使用from __feature__ import true_property时，或者通过访问器函数在其它情况下。

property columnCount: int#

此属性存储在树控件中显示的列数。

默认情况下，此属性值为1。

访问函数
property topLevelItemCount: int#

此属性存储顶级项目数。

默认情况下，此属性值为0。

访问函数
__init__([parent=None])#
参数:

parent – QWidget

使用给定的parent构建一个树控件。

addTopLevelItem(item)#
参数:

item – QTreeWidgetItem

将item附加为控件中的顶级项目。

另请参阅

insertTopLevelItem()

addTopLevelItems(items)#
参数:

items – .list of QTreeWidgetItem

将items列表作为窗口的顶级项添加。

另请参阅

insertTopLevelItems()

clear()#

清除树控件，删除所有项和选择。

注意

由于在删除前每个项都会从树控件中移除，因此从一个项的析构函数中调用treeWidget()时，其返回值将无效。

另请参阅

takeTopLevelItem() topLevelItemCount() columnCount()

closePersistentEditor(item[, column=0])#
参数:

关闭给定列中item的持久编辑器。

如果没有为这种项和列的组合打开持久编辑器，则此函数不会有任何效果。

collapseItem(item)#
参数:

item – QTreeWidgetItem

关闭item。这将导致包含该项子项的树折叠。

columnCount()#
返回类型:

int

另请参阅

setColumnCount()

属性 getter columnCountᅟ .

currentColumn()#
返回类型:

int

返回树控件中的当前列。

currentItem()#
返回类型:

QTreeWidgetItem

返回树部件中的当前项。

currentItemChanged(current, previous)#
参数:

当当前项发生变化时，会发出此信号。通过 current 指定当前项，并将其替换为之前的当前项 previous。

另请参阅

setCurrentItem()

dropMimeData(parent, index, data, action)#
参数:
返回类型:

bool

处理由悬停和放置操作提供的 data，该操作以给定的 action 结束，放置在给定的 parent 项的 index 位置。

默认实现如果悬停被成功处理，即通过解码 MIME 数据并将它插入到模型中，则返回 true；否则返回 false。

另请参阅

supportedDropActions()

editItem(item[, column=0])#
参数:

如果项在指定的 column 中可编辑，则开始编辑该 item。

expandItem(item)#
参数:

item – QTreeWidgetItem

展开 item。这将导致包含该项目子项的树展开。

findItems(text, flags[, column=0])#
参数:

  • text – str

  • flags – MatchFlag 的组合

  • column – int

返回类型:

. QTreeWidgetItem 的列表

返回一个列表，其中包含与给定的 text 匹配的项，使用给定的 flags，在给定的 column 中。

headerItem()#
返回类型:

QTreeWidgetItem

返回用于树小部件标题的项。

另请参阅

setHeaderItem()

indexFromItem(item[, column=0])#
参数:
返回类型:

QModelIndex

返回与给定 item 关联的 QModelIndex，在给定的 column 中。

注意

在 Qt 5.7 之前的版本中，此函数接收非 const 的 item 参数。

另请参阅

itemFromIndex() topLevelItem()

indexOfTopLevelItem(item)#
参数:

item – QTreeWidgetItem

返回类型:

int

返回给定顶级 item 的索引，如果找不到项，则返回 -1。

insertTopLevelItem(index, item)#
参数:

在视图的顶层将 item 插入到 index 位置。

如果项目已经被插入到其他位置，则不会再次插入。

insertTopLevelItems(index, items)#
参数:

  • index – int

  • items – .list of QTreeWidgetItem

在视图的顶层将 items 列表插入到 index 位置。

如果项目已经被插入到其他位置，则不会再次插入。

另请参阅

addTopLevelItems()

invisibleRootItem()#
返回类型:

QTreeWidgetItem

返回树控件的不可见根项目。

不可见根项目通过 QTreeWidgetItem API 访问树控件的顶层项目，使得能够以统一的方式编写函数来处理顶层项目和它们的子项目；例如，递归函数。

isPersistentEditorOpen(item[, column=0])#
参数:
返回类型:

bool

返回是否在列 column 对应的项 item 上打开了持久编辑器。

itemAbove(item)#
参数:

item – QTreeWidgetItem

返回类型:

QTreeWidgetItem

返回给定 item 上方的项。

itemActivated(item, column)#
参数:

当用户通过单击或双击（根据平台，即在 SH_ItemView_ActivateItemOnSingleClick 风格提示）或按特殊键（例如 Enter）激活项时，会发出此信号。

指定的 item 是被点击的项，如果没有点击项，则为 None。column 是被点击的项的列，如果没有点击项，则为 -1。

itemAt(p)#
参数:

p – QPoint

返回类型:

QTreeWidgetItem

返回指向坐标 p 的项的指针。坐标相对于树部件的 viewport()。

另请参阅

visualItemRect()

itemAt(x, y)
参数:

  • x – int

  • y – int

返回类型:

QTreeWidgetItem

这是一个重载的函数。

返回指向坐标（x，y）的项的指针。坐标相对于树部件的 viewport()。

itemBelow(item)#
参数:

item – QTreeWidgetItem

返回类型:

QTreeWidgetItem

返回给定 item 下方视觉上的项。

itemChanged(item, column)#
参数:

当指定的 item 中的 column 内容发生变化时，会发出此信号。

itemClicked(item, column)#
参数:

当用户在部件内部单击时，会发出此信号。

指定的 item 是被点击的项。 column 是被点击的项的列。如果没有点击项，则不会发出信号。

itemCollapsed(item)#
参数:

item – QTreeWidgetItem

当指定的 item 展开因此其子项都不显示时，会发出此信号。

注意

如果在调用 collapseAll() 时项目更改其状态，则不会发出此信号。

另请参阅

isExpanded() itemExpanded() collapseItem()

itemDoubleClicked(item, column)#
参数:

当用户在控件内双击时，会发出此信号。

指定的 item 是被点击的项目，如果没有点击任何项目则是 None。column 是被点击的项所在的列。如果没有双击任何项，则不会发出信号。

itemEntered(item, column)#
参数:

当鼠标光标进入指定 column 上的 item 时，会发出此信号。《a class="reference internal" href="#PySide6.QtWidgets.QTreeWidget" title="PySide6.QtWidgets.QTreeWidget">QTreeWidget 的鼠标跟踪需要启用才能实现此功能。

itemExpanded(item)#
参数:

item – QTreeWidgetItem

当指定的 item 被展开，以便显示其所有子项时，会发出此信号。

itemFromIndex(index)#
参数:

index – QModelIndex

返回类型:

QTreeWidgetItem

返回与给定 index 相关的 QTreeWidgetItem 的指针。

另请参阅

indexFromItem()

itemPressed(item, column)#
参数:

当用户在窗口内部按下鼠标按钮时，会发出该信号。

指定的 item 是被点击的项，如果没有点击项，则为 None。column 是被点击的项的列，如果没有点击项，则为 -1。

itemSelectionChanged()#

当树形窗口中的选择发生变化时，会发出该信号。当前选择可以通过selectedItems()函数找到。

itemWidget(item, column)#
参数:
返回类型:

QWidget

返回由item和给定的column指定的单元格中显示的窗口。

另请参阅

setItemWidget()

mimeData(items)#
参数:

items – .list of QTreeWidgetItem

返回类型:

QMimeData

返回一个包含指定items序列化描述的对象。描述项目时所使用的格式从mimeTypes()函数中获取。

如果项目列表为空，则返回None而不是序列化的空列表。

mimeTypes()#
返回类型:

字符串列表

返回可用于描述树形窗口项目列表的MIME类型列表。

另请参阅

mimeData()

openPersistentEditor(item[, column=0])#
参数:

在给定的column中为item打开一个持久编辑器。

removeItemWidget(item, column)#
参数:

移除在给定的item和给定的column中设置的窗口。

scrollToItem(item[, hint=QAbstractItemView.ScrollHint.EnsureVisible])#
参数:

确保 item 可见，如果需要，则使用指定的 hint 滚动视图。

selectedItems()#
返回类型:

. QTreeWidgetItem 的列表

返回所有已选非隐藏项目的列表。

另请参阅

itemSelectionChanged()

setColumnCount(columns)#
参数:

columns - int

另请参阅

columnCount()

属性 columnCount 的设置器。

setCurrentItem(item)#
参数:

item – QTreeWidgetItem

在树控件中设置当前 item。

除非选择模式为 NoSelection ，否则项目也会被选中。

setCurrentItem(item, column, command)
参数:

设置树控件中的当前 item 和当前列到 column，使用给定的 command。

另请参阅

currentItem()

setCurrentItem(item, column)
参数:

将树小部件中的当前item和当前列设置为column。

另请参阅

currentItem()

setHeaderItem(item)#
参数:

item – QTreeWidgetItem

为树小部件设置标题item。标题中每列的标签由该项中的相应标签提供。

树小部件将拥有该项的所有权。

setHeaderLabel(label)#
参数:

label - 字符串

与setHeaderLabels（QStringList（label）））相同。

setHeaderLabels
参数:

labels - 字符串列表

为labels列表中的每个项在标题中添加列，并设置每列的标签。

请注意，setHeaderLabels()不会删除现有列。

setItemWidgetitem(widget, column, widget)#
参数:

将给定的widget设置为在给定的item和column指定的单元格中显示。

给定的widget的autoFillBackground属性必须设置为true，否则小部件的背景将是透明的，将同时显示模型数据和树小部件项。

此函数应仅用于用树小部件项代替显示静态内容。如果您想显示自定义动态内容或实现自定义编辑小部件，请使用QTreeView并继承QStyledItemDelegate替换。

该函数不能在设置项层次结构之前调用，也就是说，在设置 widget 之前，必须将用于承载 widget 的 QTreeWidgetItem 添加到视图中。

注意

树将接管小部件的所有权。

另请参阅

itemWidget() 委托类

sortColumn(#
返回类型:

int

返回用于对小部件内容进行排序的列。

另请参阅

sortItems()

sortItems(column, order)#
参数:

根据给定列中的值，以指定的 order 对小部件中的项目进行排序。

另请参阅

sortColumn()

supportedDropActions(#
返回类型:

DropAction 的组合

返回此视图支持的拖放操作。

另请参阅

拖放操作

takeTopLevelItem(index)#
参数:

index – int

返回类型:

QTreeWidgetItem

在树中移除给定 index 的顶级项并返回它，否则返回 None；

topLevelItem(index)#
参数:

index – int

返回类型:

QTreeWidgetItem

返回给定 index 的顶级项，如果项不存在，返回 None。

topLevelItemCount(#
返回类型:

int

属性 topLevelItemCountᅟ 的获取器。

visualItemRect(item)#
参数:

item – QTreeWidgetItem

返回类型:

QRect

返回在 item 位置的项目所占视口的矩形。

另请参阅

itemAt()