En esta página

TreeView QML Type

Ofrece una vista en árbol para mostrar los datos de un QAbstractItemModel. Más...

Import Statement: import QtQuick
Since: Qt 6.3
Inherits:

TableView

Propiedades

Señales

Métodos

Descripción detallada

Un TreeView tiene un ` model ` que define los datos que se van a mostrar y un ` delegate ` que define cómo deben mostrarse dichos datos.

TreeView hereda de TableView. Esto significa que, a pesar de que el modelo tiene una estructura de árbol padre-hijo, TreeView utiliza internamente un modelo proxy que convierte esa estructura en un modelo de tabla plana que puede ser renderizado por TableView. Cada nodo del árbol acaba ocupando una fila en la tabla, donde la primera columna muestra el propio árbol. Al sangrar cada elemento delegado en esa columna según su profundidad padre-hijo en el modelo, el resultado final tendrá el aspecto de un árbol, aunque técnicamente siga siendo solo una lista plana de elementos.

Declarar un TreeView

TreeView es un control vinculado a datos, por lo que no puede mostrar nada sin un modelo de datos. No se pueden declarar nodos de árbol en QML.

Al declarar un TreeView, es necesario especificar:

  • Un modelo de datos. TreeView puede trabajar con modelos de datos que deriven de ` QAbstractItemModel`.
  • Un delegado. Un delegado es una plantilla que especifica cómo se muestran los nodos del árbol en la interfaz de usuario.
TreeView {
    // The model needs to be a QAbstractItemModel
    model: myTreeModel
    // You can set a custom delegate or use a built-in TreeViewDelegate
    delegate: TreeViewDelegate {}
}

Creación de un modelo de datos

Un TreeView solo acepta un modelo que herede de ` QAbstractItemModel`.

Para obtener información sobre cómo crear y utilizar un modelo de árbol personalizado, consulta el ejemplo: Controles deQt Quick: Índice.

Personalizar los nodos del árbol

Para una mayor flexibilidad, el propio TreeView no coloca los elementos del delegado en una estructura de árbol. Esta tarea recae en el delegado. Qt Quick Controls ofrece un TreeViewDelegate ya preparado que se puede utilizar para ello, lo cual tiene la ventaja de que funciona de forma inmediata y representa un árbol que sigue el estilo de la plataforma en la que se ejecuta la aplicación.

Aunque TreeViewDelegate es personalizable, puede haber situaciones en las que se desee representar el árbol de otra forma, o asegurarse de que el delegado sea lo más sencillo posible, quizá por motivos de rendimiento. Crear tu propio delegado desde cero es fácil, ya que TreeView ofrece un conjunto de propiedades que pueden utilizarse para colocar y representar correctamente cada nodo del árbol.

A continuación se muestra un ejemplo de un delegado personalizado con un indicador animado:

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

Las propiedades marcadas como « required » serán rellenadas por TreeView y son similares a las propiedades adjuntas. Al marcarlas como obligatorias, el delegado informa indirectamente a TreeView de que debe encargarse de asignarles valores. Se pueden añadir las siguientes propiedades obligatorias a un delegado:

  • required property TreeView treeView - Apunta al TreeView que contiene el elemento del delegado.
  • required property bool isTreeNode - Es « true » si el elemento delegado representa un nodo del árbol. Solo se utilizará una columna de la vista para dibujar el árbol y, por lo tanto, solo los elementos delegados de esa columna tendrán esta propiedad establecida en « true ». Normalmente, un nodo del árbol debe aparecer sangrado según su « depth » y mostrar un indicador si « hasChildren » es « true ». Los elementos delegados de otras columnas tendrán esta propiedad establecida en « false » y mostrarán datos de las columnas restantes del modelo (y, por lo general, no aparecerán sangrados).
  • required property bool expanded - Es true si el elemento del modelo dibujado por el delegado está expandido en la vista.
  • required property bool hasChildren - Es « true » si el elemento del modelo dibujado por el delegado tiene elementos hijos en el modelo.
  • required property int depth - Contiene la profundidad del elemento del modelo dibujado por el delegado. La profundidad de un elemento del modelo es igual al número de antepasados que tiene en el modelo.

Véase también «Propiedades obligatorias».

Interacción con el usuario final

De forma predeterminada, TreeView toggles el estado expandido de una fila al pulsar dos veces sobre ella. Dado que esto entra en conflicto con la acción de pulsar dos veces para editar una celda, TreeView establece editTriggers en TableView.EditKeyPressed de forma predeterminada (lo cual difiere de TableView, que utiliza TableView.EditKeyPressed | TableView.DoubleTapped. Si se cambia editTriggers para que también contenga TableView.DoubleTapped, se desactivará la alternancia del estado expandido con un doble toque.

Documentación de propiedades

rootIndex : QModelIndex [since 6.6]

Esta propiedad contiene el índice del modelo del elemento raíz del árbol. Por defecto, coincide con el índice raíz del modelo, pero puedes configurarlo para que sea el índice de un elemento secundario, con el fin de mostrar solo una rama del árbol. Establece el valor en « undefined » para mostrar el modelo completo.

Esta propiedad se introdujo en Qt 6.6.

Documentación de señales

collapsed(row, recursively)

Esta señal se emite cuando se contrae una fila de la tabla de datos ( row ) en la vista. « row » será igual al argumento pasado a la llamada que provocó la contracción (collapse() o collapseRecursively()). Si la fila se contrajo de forma recursiva, « recursively » será true.

Nota: cuando una fila se contrae de forma recursiva, la señal de contracción solo se emitirá para esa fila concreta, y no para sus descendientes.

Nota: El controlador correspondiente es onCollapsed.

Véase también expanded(), expand(), collapse() y toggleExpanded().

expanded(row, depth)

Esta señal se emite cuando se expande un « row » en la vista. « row » y « depth » serán iguales a los argumentos proporcionados a la llamada que provocó la expansión (expand() o expandRecursively()). En el caso de « expand()», « depth » será siempre 1. En el caso de « expandToIndex()», « depth » será la profundidad del índice de destino.

Nota: cuando una fila se expande de forma recursiva, la señal «expanded» solo se emitirá para esa fila concreta, y no para sus descendientes.

Nota: El controlador correspondiente es onExpanded.

Véase también collapsed(), expand(), collapse() y toggleExpanded().

Documentación del método

void collapse(row)

Oculta el nodo del árbol situado en la dirección « row » indicada en la vista.

row Debe tratarse de una fila de la vista (fila de la tabla), y no de una fila del modelo.

Nota: esta función no afectará al modelo, sino únicamente a la representación visual en la vista.

Véase también expand() y isExpanded().

[since 6.4] void collapseRecursively(row = -1)

Plegará el nodo del árbol situado en la row indicada en la vista de forma recursiva hasta llegar a todas las hojas.

Si un modelo tiene más de una raíz, también se puede llamar a esta función con ` row ` igual a ` -1`. Esto ocultará todas las raíces. Por lo tanto, al llamar a `collapseRecursively(-1)`, o simplemente a `collapseRecursively()`, se ocultarán todos los nodos del modelo.

row Debe ser la fila de la vista (fila de la tabla), y no una fila del modelo.

Nota: esta función no afectará al modelo, sino únicamente a la representación visual en la vista.

Este método se introdujo en Qt 6.4.

Véase también expandRecursively(), expand(), collapse(), isExpanded() y depth().

int depth(row)

Devuelve la profundidad (el número de elementos padres hasta la raíz) del row dado.

row Debe tratarse de una fila de la vista (fila de la tabla), y no de una fila del modelo. Si row no se encuentra entre 0 y rows, el valor devuelto será -1.

Véase también modelIndex().

void expand(row)

Expande el nodo del árbol situado en la dirección row en la vista.

row Debe ser la fila de la vista (fila de la tabla), y no una fila del modelo.

Nota: esta función no afectará al modelo, sino únicamente a la representación visual en la vista.

Véase también collapse(), isExpanded() y expandRecursively().

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

Expande el nodo del árbol situado en la ruta dada row en la vista de forma recursiva hasta depth. depth debe ser relativa a la profundidad de row. Si depth es -1, el árbol se expandirá hasta llegar a todas las hojas.

Para un modelo que tenga más de una raíz, también se puede llamar a esta función con row igual a -1. Esto expandirá todas las raíces. Por lo tanto, llamar a expandRecursively(-1, -1), o simplemente a expandRecursively(), expandirá todos los nodos del modelo.

row debe ser la fila de la vista (fila de la tabla), y no una fila del modelo.

Nota: Esta función no intentará fetch more ar datos.

Nota: Esta función no afectará al modelo, sino únicamente a la representación visual en la vista.

Advertencia: Si el modelo contiene un gran número de elementos, esta función tardará algún tiempo en ejecutarse.

Este método se introdujo en Qt 6.4.

Véase también collapseRecursively(), expand(), collapse(), isExpanded() y depth().

[since 6.4] void expandToIndex(QModelIndex index)

Expande el árbol a partir del modelo dado index y, de forma recursiva, hasta llegar a la raíz. El resultado será que el elemento delegado que representa index se haga visible en la vista (a menos que quede fuera del área de visualización). Para garantizar que la fila quede visible en el área de visualización, puedes hacer lo siguiente:

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

Este método se introdujo en Qt 6.4.

Véase también expand() y expandRecursively().

bool isExpanded(row)

Devuelve si el elemento « row » especificado en la vista se muestra expandido.

row Debe tratarse de la fila de la vista (fila de la tabla), y no de una fila del modelo. Si « row » no se encuentra entre « 0 » y « rows », el valor devuelto será « false ».

void toggleExpanded(row)

Activa o desactiva la expansión del nodo del árbol situado en la ruta « row » indicada. Esto resulta muy práctico para hacer lo siguiente:

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

row debería ser la fila de la vista (fila de la tabla), y no una fila del modelo.

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