Back to Qt.io
Contact Us Blog Download Qt

TreeModel QML Type

封装一个简单的树模型。更多

Import Statement: import Qt.labs.qmlmodels
Since: Qt 6.10

属性

方法

  • appendRow(object treeRow)
  • appendRow(QModelIndex parent, object treeRow)
  • clear()
  • variant data(QModelIndex index, string role)
  • object getRow(const QModelIndex &rowIndex)
  • QModelIndex index(list<int> treeIndex, int column)
  • QModelIndex index(int row, int column, object parent)
  • removeRow(QModelIndex rowIndex)
  • bool setData(QModelIndex index, variant value, string role)
  • setRow(QModelIndex rowIndex, object treeRow)

详细说明

TreeModel 类型存储 JavaScript/JSON 对象作为树模型的数据，可与TreeView 一起使用。它旨在支持非常简单的模型，而无需在 C++ 中创建自定义的QAbstractItemModel 子类。

import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels

ApplicationWindow {
    visible: true
    width: 500
    height: 500

    TreeView {
        id: treeView
        anchors.fill: parent

        selectionModel: ItemSelectionModel {}

        model: TreeModel {
            id: treeModel

            TableModelColumn {
                display: "checked"
            }
            TableModelColumn {
                display: "size"
            }
            TableModelColumn {
                display: "type"
            }
            TableModelColumn {
                display: "name"
            }
            TableModelColumn {
                display: "lastModified"
            }

            rows: [{
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Documents",
                    lastModified: "2025-07-01",
                    rows: [{
                            checked: true,
                            size: "24 KB",
                            type: "file",
                            name: "Resume.pdf",
                            lastModified: "2025-06-20",
                        }, {
                            checked: false,
                            size: "2 MB",
                            type: "folder",
                            name: "Reports",
                            lastModified: "2025-06-10",
                            rows: [{
                                    checked: true,
                                    size: "850 KB",
                                    type: "file",
                                    name: "Q2_Report.docx",
                                    lastModified: "2025-06-15",
                                }, {
                                    checked: false,
                                    size: "1.2 MB",
                                    type: "file",
                                    name: "Q3_Plan.xlsx",
                                    lastModified: "2025-06-18",
                                }]
                        }]
                },
                {
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Pictures",
                    lastModified: "2025-05-30",
                    rows: [{
                            checked: true,
                            size: "3.5 MB",
                            type: "file",
                            name: "Vacation.jpg",
                            lastModified: "2025-05-15",
                        }, {
                            checked: false,
                            size: "2.1 MB",
                            type: "file",
                            name: "Family.png",
                            lastModified: "2025-05-20",
                        }]
                }
            ]
        }

        delegate: TreeViewDelegate {}
    }
}

模型的初始数据是通过rows 属性或调用appendRow() 设置的。模型中的每一列都是通过声明TableModelColumn 实例来指定的，每个实例的顺序决定其列索引。一旦模型的Component::completed() 信号发出，列和角色就已建立，并在模型的生命周期内固定不变。

支持的行数据结构

每一行代表树中的一个节点。每个节点都有相同类型的列。TreeModel 设计用于处理 JavaScript/JSON 数据，因此每一行都是一个简单的键值对列表：

                {
                    checked: false,
                    size: "—",
                    type: "folder",
                    name: "Pictures",
                    lastModified: "2025-05-30",
                    rows: [{
                            checked: true,
                            size: "3.5 MB",
                            type: "file",
                            name: "Vacation.jpg",
                            lastModified: "2025-05-15",
                        }, {
                            checked: false,
                            size: "2.1 MB",
                            type: "file",
                            name: "Family.png",
                            lastModified: "2025-05-20",
                        }]
                }

节点可以有子节点，这些子节点将存储在与 "行 "键相关联的数组中。"rows "是为此目的而保留的：只有子节点列表才应与此键相关联。

该模型通过QModelIndices 进行操作。要访问特定行/节点，可以使用getRow() 函数。也可以通过rows 属性直接访问模型的 JavaScript 数据，但这种方式无法修改模型数据。

要添加新行，请使用appendRow() 。要修改现有行，请使用setRow(),removeRow() 和clear() 。

属性文档

columnCount : int [read-only]

此只读属性保存模型中的列数。

在设置rows 属性或首次调用appendRow() 后，列数在模型生命周期内是固定的。


rows : object

该属性以行数组的形式保存模型数据。

另请参阅 getRow(),setRow(),appendRow(),clear() 和columnCount 。


方法文档

appendRow(object treeRow)

将treeRow 附加到根节点。

另请参阅 setRow() 和removeRow()。


appendRow(QModelIndex parent, object treeRow)

向parent 添加一个新的 treeRow，其中包含treeRow 中的值（单元格）。

treeModel.appendRow(index, {
    checked: false,
    size: "-",
    type: "folder",
    name: "Orders",
    lastModified: "2025-07-02",
    rows: [
        {
            checked: true,
            size: "38 KB",
            type: "file",
            name: "monitors.xlsx",
            lastModified: "2025-07-02"
        },
        {
            checked: true,
            size: "54 KB",
            type: "file",
            name: "notebooks.xlsx",
            lastModified: "2025-07-02"
        }
    ]
});

如果parent 无效，则将treeRow 追加到根节点。

另请参阅 setRow() 和removeRow()。


clear()

删除模型中的所有行。

另请参阅 removeRow()。


variant data(QModelIndex index, string role)

从给定index 的TreeModel 返回属于给定role 的数据。

另请参阅 index() 和setData()。


object getRow(const QModelIndex &rowIndex)

返回模型中rowIndex 处的 treeRow。

注意： 返回的对象不能用于修改模型的内容；请使用 setTreeRow() 代替。

另请参阅 setRow()、appendRow() 和removeRow()。


QModelIndex index(list<int> treeIndex, int column)

返回引用给定treeIndex 和column 的QModelIndex 对象，该对象可传递给data() 函数以获取该单元格的数据，或传递给setData() 以编辑该单元格的内容。

第一个参数treeIndex 表示从根单元到所需行的行号路径，用于在树内导航。最好通过一个例子来解释。

  • 树的根节点比较特殊，因为它可以被一个无效的QModelIndex 引用。
  • 节点 A 是根的第一个子节点，对应的treeIndex 是[0] 。
  • 节点 B 是节点 A 的第一个子节点。由于 A 的treeIndex 是[0] ，因此 B 的treeIndex 将是[0,0] 。
  • 节点 C 是节点 A 的第二个子节点，其treeIndex 是[0,1] 。
  • 节点 D 是 A 的第三个子节点，其treeIndex 是[0,2] 。
  • 节点 E 是根的第二个子节点，其treeIndex 是[1] 。
  • 节点 F 是根节点的第三个子节点，其treeIndex 是[2] 。

有了这个重载，就有可能在没有QModelIndex 的情况下获得一个节点的QModelIndex 。

如果在指定的列表中找不到节点，将返回一个无效的模型索引。请注意，无效的模型索引会引用节点的根节点。

另请参阅 QML 中的 QModelIndex 及相关类和data()。


QModelIndex index(int row, int column, object parent)

parent 返回引用给定row 和column 的QModelIndex 对象，该对象可传递给data() 函数以获取该单元格的数据，或传递给setData() 以编辑该单元格的内容。

另请参阅 QML 中的 QModelIndex 及相关类和data()。


removeRow(QModelIndex rowIndex)

从模型中删除rowIndex 引用的 TreeRow。

treeModel.removeTreeRow(rowIndex)

另请参阅 clear()。


bool setData(QModelIndex index, variant value, string role)

在给定的index 的 TreeRow 中插入或更新由role 命名的数据字段value 。如果成功则返回 true，否则返回 false。

另请参阅 data() 和index()。


setRow(QModelIndex rowIndex, object treeRow)

用treeRow 替换模型中rowIndex 处的 TreeRow。带有子行的行将被拒绝。

treeRow 中的所有列/单元格都必须存在，且顺序正确。该行的子行不受影响。

treeModel.setRow(rowIndex, {
    checked: true,
    size: "-",
    type: "folder",
    name: "Subtitles",
    lastModified: "2025-07-07",
    iconColor: "blue"
});

另请参阅 appendRow() 。


© 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.