TreeModel QML Type

Représente un modèle d'arbre simple. En savoir plus…

• Liste de tous les membres, y compris les membres hérités

Propriétés

• columnCount : int
• rows : var

Méthodes

• 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 insertRow(int rowIndex, object row) (since 6.12)
• void insertRow(int rowIndex, QModelIndex parent, object row) (since 6.12)
• bool moveRows(QModelIndex sourceParent, int sourceRow, int count, QModelIndex destinationParent, int destinationChild) (since 6.12)
• void removeRow(rowIndex)
• bool setData(index, variant value, string role)
• void setRow(rowIndex, var treeRow)

Description détaillée

Le type TreeModel stocke des objets JavaScript/JSON en tant que données pour un modèle arborescent pouvant être utilisé avec TreeView. Il est destiné à prendre en charge des modèles très simples sans nécessiter la création d'une sous-classe personnalisée de QAbstractItemModel en C++.

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 {}
    }
}

Les données initiales du modèle sont définies soit via la propriété ` rows `, soit en appelant la méthode ` appendRow()`. Chaque colonne du modèle est spécifiée en déclarant une instance de ` TableModelColumn `, l'ordre de ces instances déterminant l'index de chaque colonne. Une fois que le signal ` Component::completed()` du modèle a été émis, les colonnes et les rôles sont établis et restent fixes pendant toute la durée de vie du modèle.

Structures de données de ligne prises en charge

Chaque ligne représente un nœud de l’arborescence. Chaque nœud possède le même type de colonnes. Le TreeModel est conçu pour fonctionner avec des données JavaScript/JSON ; chaque ligne est donc une liste de simples paires clé-valeur :

                {
                    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",
                        }]
                }

Un nœud peut avoir des nœuds enfants, qui seront stockés dans un tableau associé à la clé « rows ». La clé « rows » est réservée à cet effet : seule la liste des nœuds enfants doit être associée à cette clé.

Le modèle est manipulé via QModelIndices. Pour accéder à une ligne/un nœud spécifique, la fonction getRow() peut être utilisée. Il est également possible d’accéder directement aux données JavaScript du modèle via la propriété rows, mais il n’est pas possible de modifier les données du modèle de cette manière.

Pour ajouter de nouvelles lignes, utilisez appendRow(). Pour modifier des lignes existantes, utilisez setRow(), removeRow() et clear().

Utilisation de TreeModel avec des sources JSON externes

Bien que le TreeModel soit destiné à définir les données JSON directement dans le fichier QML, vous pouvez utiliser n’importe quel objet JSON avec le modèle tant que sa structure correspond à celle définie par le TreeModel. Si toutes les lignes de l’objet JSON sont conformes aux colonnes définies par le modèle, vous pouvez l’affecter directement via la propriété `rows`.

La source de l’objet JSON peut être un fichier. Par exemple, si le modèle est défini comme suit

    TreeModel {
        id: treeModel
        objectName: "testModel"

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

et que l’objet JSON stocké dans le fichier se présente comme suit

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"
            }
        ]
    }
]

alors cet objet peut être fourni en important le fichier JavaScript en tant que

module

import "TreeData.js" as JsonData

, puis il peut être affecté directement

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

Consultez TableModel pour découvrir un autre exemple dans lequel un objet JSON est analysé et affecté à un tableau JavaScript.

Voir également TableModelColumn et TreeView.

Documentation sur les propriétés

columnCount : int [read-only]

Cette propriété en lecture seule contient le nombre de colonnes du modèle.

Le nombre de colonnes est fixe pendant toute la durée de vie du modèle après la définition de la propriété ` rows ` ou l’appel de la méthode ` appendRow()` pour la première fois.

rows : var

Cette propriété contient les données du modèle sous la forme d'un tableau de lignes.

Voir également getRow(), setRow(), appendRow(), clear() et columnCount.

Documentation des méthodes

void appendRow(var treeRow)

Ajoute treeRow au nœud racine.

Voir également setRow() et removeRow().

void appendRow(parent, var treeRow)

Ajoute un nouvel élément `treeRow` à ` parent`, avec les valeurs (cellules) contenues dans ` 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 Il s’agit d’un type QML anonyme basé sur QModelIndex. Si parent n’est pas valide, treeRow est ajouté au nœud racine.

Voir également setRow() et removeRow().

void clear()

Supprime toutes les lignes du modèle.

Voir aussi removeRow().

variant data(index, string role)

Renvoie les données de l'TreeModel à l'index indiquée, appartenant à l'role indiquée.

index Il s'agit d'un type QML anonyme basé sur QModelIndex.

Voir également index() et setData().

var getRow(rowIndex)

Renvoie l'élément `treeRow` situé à l'index spécifié dans le modèle. ` rowIndex ` est un type QML anonyme implémenté par ` QModelIndex`.

Voir également setRow(), appendRow() et removeRow().

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

Renvoie un objet faisant référence aux éléments treeIndex et column fournis, qui peuvent être transmis à la fonction data() pour récupérer les données de cette cellule, ou à la fonction setData() pour modifier le contenu de cette cellule.

L'objet renvoyé est d'un type QML anonyme basé sur QModelIndex.

Le premier paramètre, treeIndex, représente un chemin composé de numéros de lignes partant de la racine jusqu’à la ligne souhaitée et sert à la navigation au sein de l’arborescence. Un exemple permettra de mieux comprendre ce principe.

La racine de l’arborescence est particulière, car elle peut être référencée par un ` QModelIndex` non valide. Le nœud A est le premier enfant de la racine et l’ treeIndex correspondant est [0]. Le nœud B est le premier enfant du nœud A. Étant donné que l’ treeIndex de A est [0], l’ treeIndex de B sera [0,0]. Le nœud C est le deuxième enfant du nœud A et son treeIndex est [0,1]. Le nœud D est le troisième enfant de A et son treeIndex est [0,2]. Le nœud E est le deuxième enfant de la racine et son treeIndex est [1]. Le nœud F est le troisième enfant de la racine et son treeIndex est [2].

Grâce à cette surcharge, il est possible d’obtenir un « QModelIndex » vers un nœud sans disposer d’un « QModelIndex » vers son nœud parent.

Si aucun nœud n’est trouvé dans la liste spécifiée, un index de modèle invalide est renvoyé. Veuillez noter qu’un index de modèle invalide fait référence à la racine des nœuds.

Voir également QModelIndex et les classes associées dans QML, ainsi que la méthode data().

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

Renvoie un objet faisant référence aux propriétés ` row ` et ` column ` d'une cellule donnée de type ` parent `. Cet objet peut être transmis à la fonction ` data()` pour récupérer les données de cette cellule, ou à la fonction ` setData()` pour modifier son contenu.

L'objet renvoyé est d'un type QML anonyme implémenté par QModelIndex.

Voir également QModelIndex et les classes associées dans QML, ainsi que la fonction data().

[since 6.12] void insertRow(int rowIndex, object row)

Insère une nouvelle ligne dans l'élément racine à la position rowIndex, avec les valeurs (cellules) contenues dans row.

Cette méthode a été introduite dans Qt 6.12.

Voir également appendRow(), setRow() et removeRow().

[since 6.12] void insertRow(int rowIndex, QModelIndex parent, object row)

Insère une nouvelle ligne dans l'parent à la position rowIndex, avec les valeurs (cellules) contenues dans row.

model.insertRow(2, parentIndex, {
    checkable: true, checked: false,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

Cette méthode a été introduite dans Qt 6.12.

Voir également appendRow(), setRow() et removeRow().

[since 6.12] bool moveRows(QModelIndex sourceParent, int sourceRow, int count, QModelIndex destinationParent, int destinationChild)

Déplace les lignes de l'count, à partir de sourceRow, de sourceParent vers destinationParent, en les insérant avant destinationChild.

L'destinationChild fait référence à la position dans destinationParent avant le déplacement (index pré-suppression), conformément à QAbstractItemModel::beginMoveRows().

Les plages source et de destination doivent exister, et sourceParent et destinationParent ne doivent pas se chevaucher de telle sorte qu’un élément parent soit déplacé sous son propre enfant.

Renvoie true si les lignes ont été déplacées avec succès ; sinon, renvoie false.

Cette méthode a été introduite dans Qt 6.12.

Voir également appendRow(), insertRow() et removeRow().

void removeRow(rowIndex)

Supprime du modèle l'élément `TreeRow` référencé par ` rowIndex `. ` rowIndex ` est un type QML anonyme implémenté par ` QModelIndex`.

treeModel.removeTreeRow(rowIndex)

Voir également clear().

bool setData(index, variant value, string role)

Insère ou met à jour le champ de données désigné par role dans la ligne TreeRow située à l'index indiquée, avec value. Renvoie « true » en cas de succès, « false » dans le cas contraire.

index Il s'agit d'un type QML anonyme basé sur QModelIndex.

Voir également data() et index().

void setRow(rowIndex, var treeRow)

Remplace l'élément `TreeRow` situé à l'adresse rowIndex dans le modèle par treeRow. ` rowIndex ` est un type QML anonyme implémenté par QModelIndex.

Une ligne comportant des lignes enfants sera rejetée.

Toutes les colonnes/cellules doivent être présentes dans treeRow, et dans le bon ordre. Les lignes enfants de la ligne ne sont pas affectées.

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

Voir également appendRow().