TreeView QML Type

提供树形视图，显示来自QAbstractItemModel... 更多...

Import Statement:	`import QtQuick`
Since:	Qt 6.3
Inherits:	TableView

所有成员（包括继承成员）的列表

属性

rootIndex : QModelIndex (since 6.6)

信号

collapsed(row, recursively)
expanded(row, depth)

方法

collapse(row)
collapseRecursively(row) (since 6.4)
int depth(row)
expand(row)
expandRecursively(row, depth) (since 6.4)
expandToIndex(QModelIndex index) (since 6.4)
bool isExpanded(row)
toggleExpanded(row)

详细说明

TreeView 有一个定义要显示的数据的模型和一个定义如何显示数据的委托。

TreeView 继承于TableView 。这意味着，即使模型具有父子树结构，TreeView 也会在内部使用代理模型，将该结构转换为可由TableView 渲染的平面表格模型。树中的每个节点最终都会占据表格中的一行，其中第一列渲染树本身。通过根据模型中父子关系的深度缩进该列中的每个委托项，即使从技术上讲它仍然只是一个扁平的项目列表，它最终看起来也会像一棵树。

声明树视图

TreeView 是一个数据绑定控件，因此如果没有数据模型，它就无法显示任何内容。你不能在 QML 中声明树节点。

当你声明一个 TreeView 时，你需要指定：

数据模型。TreeView 可以使用从QAbstractItemModel 派生的数据模型。
一个委托。委托是一个模板，用于指定如何在用户界面中显示树节点。

TreeView {
    // The model needs to be a QAbstractItemModel
    model: myTreeModel
    // You can set a custom delegate or use a built-in TreeViewDelegate
    delegate: TreeViewDelegate {}
}

创建数据模型

TreeView 只接受继承自QAbstractItemModel 的模型。

有关如何创建和使用自定义树模型的信息，请参阅示例：Qt Quick Controls - 目录。

自定义树节点

为了获得更好的灵活性，TreeView 本身不会将委托项定位到树形结构中。这一工作由委托人承担。 Qt Quick Controls为此，TreeView 提供了一个现成的TreeViewDelegate ，其优点是开箱即用，并能按照应用程序运行平台的风格渲染树形结构。

即使TreeViewDelegate 是可定制的，但在某些情况下，您可能希望以不同的方式呈现树，或者出于性能考虑，确保委托的最终结果尽可能小。从头开始创建自己的委托非常简单，因为 TreeView 提供了一组属性，可用于正确定位和呈现树中的每个节点。

下面是一个带有动画指示器的自定义委托的示例：

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 800
    height: 600
    visible: true

    TreeView {
        id: treeView
        anchors.fill: parent
        anchors.margins: 10
        clip: true

        selectionModel: ItemSelectionModel {}

        // The model needs to be a QAbstractItemModel
        // model: yourTreeModel

        delegate: Item {
            implicitWidth: padding + label.x + label.implicitWidth + padding
            implicitHeight: label.implicitHeight * 1.5

            readonly property real indentation: 20
            readonly property real padding: 5

            // Assigned to by TreeView:
            required property TreeView treeView
            required property bool isTreeNode
            required property bool expanded
            required property bool hasChildren
            required property int depth
            required property int row
            required property int column
            required property bool current

            // Rotate indicator when expanded by the user
            // (requires TreeView to have a selectionModel)
            property Animation indicatorAnimation: NumberAnimation {
                target: indicator
                property: "rotation"
                from: expanded ? 0 : 90
                to: expanded ? 90 : 0
                duration: 100
                easing.type: Easing.OutQuart
            }
            TableView.onPooled: indicatorAnimation.complete()
            TableView.onReused: if (current) indicatorAnimation.start()
            onExpandedChanged: indicator.rotation = expanded ? 90 : 0

            Rectangle {
                id: background
                anchors.fill: parent
                color: row === treeView.currentRow ? palette.highlight : "black"
                opacity: (treeView.alternatingRows && row % 2 !== 0) ? 0.3 : 0.1
            }

            Label {
                id: indicator
                x: padding + (depth * indentation)
                anchors.verticalCenter: parent.verticalCenter
                visible: isTreeNode && hasChildren
                text: "▶"

                TapHandler {
                    onSingleTapped: {
                        let index = treeView.index(row, column)
                        treeView.selectionModel.setCurrentIndex(index, ItemSelectionModel.NoUpdate)
                        treeView.toggleExpanded(row)
                    }
                }
            }

            Label {
                id: label
                x: padding + (isTreeNode ? (depth + 1) * indentation : 0)
                anchors.verticalCenter: parent.verticalCenter
                width: parent.width - padding - x
                clip: true
                text: model.display
            }
        }
    }
}

标记为required 的属性将由 TreeView 填写，它们类似于附加属性。通过将它们标记为必填属性，委托间接通知 TreeView 应负责为它们赋值。委托可添加以下必填属性：

required property TreeView treeView - 指向包含委托项的 TreeView。
required property bool isTreeNode - 如果委托项代表树中的一个节点，则为。视图中只有一列将用于绘制树，因此只有该列中的委托项才会将此属性设置为。树中的节点通常应根据其缩进，如果是，则会显示一个指示符。其他列中的委托项将把此属性设置为，并将显示模型中其余列的数据（通常不会缩进）。true true depth hasChildren true false
required property bool expanded - 如果委托绘制的模型项在视图中展开，则。true
required property bool hasChildren - 如果委托绘制的模型项在模型中有子项，则为。true
required property int depth - 包含委托绘制的模型项的深度。模型项的深度与它在模型中的祖先数量相同。

另请参阅必填属性。

终端用户交互

默认情况下，当您双击一行时，TreeViewtoggles 会显示该行的展开状态。由于这与双击编辑单元格有冲突，因此 TreeView 默认将editTriggers 设置为TableView.EditKeyPressed （这与TableView 不同，后者使用TableView.EditKeyPressed | TableView.DoubleTapped 。如果将editTriggers 改为也包含TableView.DoubleTapped ，双击时切换展开状态的功能将被禁用。

属性文档

rootIndex : QModelIndex [since 6.6]

该属性保存树中根项目的模型索引。默认情况下，它与模型中的根索引相同，但您可以将它设置为子索引，以便只显示树的一个分支。将其设置为undefined 可显示整个模型。

此属性在 Qt 6.6 中引入。

信号文档

collapsed(row, recursively)

当row 在视图中折叠时，将发出该信号。row 将等于导致折叠的调用所给的参数（collapse() 或collapseRecursively()）。如果该行是递归折叠的，recursively 将是true 。

注意： 当一行被递归折叠时，折叠信号只会针对这一行，而不会针对它的后代。

注：相应的处理程序是onCollapsed 。

另请参阅 expanded()、expand()、collapse() 和toggleExpanded() 。

expanded(row, depth)

当row 在视图中展开时，就会发出该信号。row 和depth 将等于导致展开的调用所给的参数（expand() 或expandRecursively() ）。在expand() 的情况下，depth 将始终是1 。在expandToIndex() 的情况下，depth 将是目标索引的深度。

注意： 当对某一行进行递归扩展时，只会对该行发出扩展信号，而不会对其子行发出扩展信号。

注：相应的处理程序是onExpanded 。

另请参阅 collapsed(),expand(),collapse() 和toggleExpanded() 。

方法文档

collapse(row)

折叠视图中给定row 处的树节点。

row 应该是视图中的行（表格行），而不是模型中的行。

注意： 此函数不会影响模型，只会影响视图中的可视化表示。

另请参阅 expand() 和isExpanded()。

[since 6.4] collapseRecursively(row = -1)

将视图中row 处的树节点向下递归折叠到所有树叶。

对于有多个根节点的模型，也可以调用row 等于-1 的这个函数。这将折叠所有根节点。因此，调用 collapseRecursively(-1) 或简称 collapseRecursively() 将折叠模型中的所有节点。

row 应该是视图中的行（表格行），而不是模型中的行。

注意： 此函数不会影响模型，只会影响视图中的可视化表示。

此方法在 Qt 6.4 中引入。

另请参阅 expandRecursively()、expand()、collapse()、isExpanded() 和depth()。

int depth(row)

Returns the depth (the number of parents up to the root) of the givenrow.

row 应该是视图中的行（表格行），而不是模型中的行。如果不在和之间，返回值将是。row 0 rows -1

另请参阅 modelIndex() 。

expand(row)

扩展视图中给定row 处的树节点。

row 应是视图中的行（表行），而不是模型中的行。

注意： 此函数不会影响模型，只会影响视图中的可视化表示。

另请参阅 collapse()、isExpanded() 和expandRecursively()。

[since 6.4] expandRecursively(row = -1, depth = -1)

将视图中给定row 处的树节点向下递归扩展到depth 。depth 应与row 的深度相对应。如果depth 是-1 ，树将一直向下扩展到所有叶子。

对于有多个根的模型，也可以在row 等于-1 的情况下调用此函数。这将扩展所有根。因此，调用 expandRecursively(-1,-1)，或简单地调用 expandRecursively() 将展开模型中的所有节点。

row 应该是视图中的行（表格行），而不是模型中的行。

注意： 此函数不会尝试fetch more 数据。

注意： 此函数不会影响模型，只会影响视图中的可视化表示。

警告： 如果模型包含大量项目，此函数将需要一些时间来执行。

此方法在 Qt 6.4 中引入。

另请参阅 collapseRecursively(),expand(),collapse(),isExpanded() 和depth().

[since 6.4] expandToIndex(QModelIndex index)

从给定的模型index 开始展开树，并一直递归到根节点。结果是，代表index 的委托项将在视图中可见（除非它最终位于视口之外）。为确保该行最终在视口中可见，您可以使用以下方法：

expandToIndex(index)
forceLayout()
positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)

此方法在 Qt 6.4 中引入。

另请参阅 expand() 和expandRecursively()。

bool isExpanded(row)

返回视图中给定的row 是否显示为展开。

row 应该是视图中的一行（表格行），而不是模型中的一行。如果不在和之间，返回值将是。row 0 rows false

toggleExpanded(row)

切换位于给定row 的树节点是否应展开。这是为了方便操作：

if (isExpanded(row))
    collapse(row)
else
    expand(row)

row 应是视图中的行（表格行），而不是模型中的行。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.