Back to Qt.io
Contact Us Blog Download Qt
在本页

TreeModel QML Type

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

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

属性

方法

  • void appendRow(var treeRow)
  • void appendRow(parent, var treeRow)
  • void clear()
  • variant data(index, string role)
  • var getRow(rowIndex)
  • QModelIndex index(list<int> treeIndex, int column)
  • QModelIndex index(int row, int column, var parent)
  • void removeRow(rowIndex)
  • bool setData(index, variant value, string role)
  • void setRow(rowIndex, var 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() 。

将 TreeModel 与外部 JSON 源一起使用

虽然 TreeModel 的预期用途是在 QML 文件中就地定义 JSON 数据，但只要 JSON 对象的结构与 TreeModel 定义的结构相匹配，您就可以在该模型中使用任何 JSON 对象。如果 JSON 对象的所有行都符合模型定义的列，则可通过行属性直接分配。

JSON 对象的来源可以是文件。例如，如果模型定义为

    TreeModel {
        id: treeModel
        objectName: "testModel"

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

而存储在文件中的 JSON 对象看起来像

let folders = [
    {
        "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": "—",
        "type": "folder",
        "name": "Pictures",
        "lastModified": "2025-05-30",
        "rows": [
            {
                "checked": true,
                "size": "3.5 MB",
                "type": "file",
                "name": "Vacation.jpg",
                "lastModified": "2025-05-15"
            }
        ]
    }
]

则可以通过导入 JavaScript 文件作为

模块

import "TreeData.js" as JsonData

然后直接赋值

    Component.onCompleted: treeView.model.rows = JsonData.folders

警告 确保 JSON 数据来自可信来源。由于模型是根据输入内容来填充行的，因此畸形或不可信的 JSON 可能会导致意外行为或性能问题。

另一个将 JSON 对象解析并分配为 JavaScript 数组的示例请参见TableModel 。

另请参阅 TableModelColumn 和TreeView 。

属性文档

columnCount : int [read-only]

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

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

rows : var

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

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

方法文档

void appendRow(var treeRow)

将treeRow 追加到根节点。

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

void appendRow(parent, var treeRow)

将一个新的 treeRow 添加到parent 中，其中包含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 是由QModelIndex 支持的匿名 QML 类型。如果parent 无效，treeRow 将被追加到根节点。

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

void clear()

删除模型中的所有行。

另请参见 removeRow().

variant data(index, string role)

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

index 是由QModelIndex 支持的匿名 QML 类型。

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

var getRow(rowIndex)

返回模型中指定索引处的 treeRow。rowIndex 是由QModelIndex 支持的匿名 QML 类型。

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

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

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

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

返回的对象是由QModelIndex 支持的匿名 QML 类型。

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

显示节点 A 至 F 及索引路径的树形图
  • 树的根节点比较特殊，因为它可以被一个无效的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, var parent)

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

返回的对象是由QModelIndex 支持的匿名 QML 类型。

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

void removeRow(rowIndex)

从模型中删除rowIndex 引用的 TreeRow。rowIndex 是由QModelIndex 支持的匿名 QML 类型。

treeModel.removeTreeRow(rowIndex)

另请参阅 clear() 。

bool setData(index, variant value, string role)

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

index 是由QModelIndex 支持的匿名 QML 类型。

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

void setRow(rowIndex, var treeRow)

用treeRow 替换模型中rowIndex 处的 TreeRow。rowIndex 是一个匿名 QML 类型，由QModelIndex 返回。

带有子行的行将被拒绝。

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

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

另请参阅 appendRow() 。

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