Ejemplo de modelo de árbol editable
Este ejemplo muestra cómo implementar un modelo de árbol sencillo basado en elementos que se puede utilizar con otras clases del marco de trabajo «modelo/vista».

El modelo admite elementos editables, encabezados personalizados y la posibilidad de insertar y eliminar filas y columnas. Gracias a estas características, también es posible insertar nuevos elementos secundarios, tal y como se muestra en el código de ejemplo adjunto.
Descripción general
Tal y como se describe en la Referencia sobre subclasificación de modelos, los modelos deben proporcionar implementaciones para el conjunto estándar de funciones de modelo: flags(), data(), headerData(), columnCount() y rowCount(). Además, los modelos jerárquicos, como este, deben proporcionar implementaciones de index() y parent().
Un modelo editable debe proporcionar implementaciones de setData() y setHeaderData(), y debe devolver una combinación adecuada de indicadores desde su función flags().
Dado que este ejemplo permite modificar las dimensiones del modelo, también debemos implementar insertRows(), insertColumns(), removeRows() y removeColumns().
Diseño
Al igual que en el ejemplo del modelo de árbol simple, el modelo actúa simplemente como un envoltorio alrededor de una colección de instancias de una clase TreeItem. Cada TreeItem está diseñado para contener los datos de una fila de elementos en una vista de árbol, por lo que contiene una lista de valores correspondientes a los datos que se muestran en cada columna.
Dado que QTreeView proporciona una vista orientada a filas sobre un modelo, resulta natural optar por un diseño orientado a filas para las estructuras de datos que suministrarán datos a través de un modelo a este tipo de vista. Aunque esto hace que el modelo de árbol sea menos flexible y, posiblemente, menos útil para su uso con vistas más sofisticadas, reduce la complejidad del diseño y facilita la implementación.
![]() | Relaciones entre elementos internos Al diseñar una estructura de datos para su uso con un modelo personalizado, resulta útil exponer el elemento padre de cada elemento mediante una función como `TreeItem::parent()`, ya que facilitará la escritura de la propia función ` parent()` del modelo. Del mismo modo, una función como ` TreeItem::child()` resulta útil a la hora de implementar la función ` index()` del modelo. Como resultado, cada ` El diagrama muestra cómo las instancias de ` En el ejemplo mostrado, se pueden obtener dos elementos de nivel superior, A y B, a partir del elemento raíz llamando a su función child(), y cada uno de estos elementos devuelve el nodo raíz desde sus funciones parent(), aunque esto solo se muestra para el elemento A. |
Cada objeto ` TreeItem ` almacena los datos de cada columna de la fila que representa en su miembro privado ` itemData ` (una lista de objetos ` QVariant `). Dado que existe una correspondencia uno a uno entre cada columna de la vista y cada entrada de la lista, proporcionamos una sencilla función `data()` para leer las entradas de la lista ` itemData ` y una función `setData()` para permitir su modificación. Al igual que con otras funciones del elemento, esto simplifica la implementación de las funciones data() y setData() del modelo.
Colocamos un elemento en la raíz del árbol de elementos. Este elemento raíz se corresponde con el índice nulo del modelo, QModelIndex(), que se utiliza para representar el padre de un elemento de nivel superior al gestionar los índices del modelo. Aunque el elemento raíz no tiene una representación visible en ninguna de las vistas estándar, utilizamos su lista interna de objetos QVariant para almacenar una lista de cadenas que se pasarán a las vistas para utilizarlas como títulos de encabezado horizontal.
![]() | Acceso a los datos a través del modelo En el caso que se muestra en el diagrama, la información representada por a puede obtenerse utilizando la API estándar de modelo/vista: Dado que cada elemento contiene datos correspondientes a cada columna de una fila determinada, puede haber muchos índices de modelo que apunten al mismo objeto ` Se accedería al mismo objeto « |
En la clase de modelo, ` TreeModel`, relacionamos los objetos ` TreeItem ` con los índices del modelo pasando un puntero para cada elemento al crear su índice de modelo correspondiente con ` QAbstractItemModel::createIndex()` en nuestras implementaciones de `index()` y `parent()`. Podemos recuperar los punteros almacenados de esta forma llamando a la función internalPointer() en el índice de modelo correspondiente; creamos nuestra propia función getItem() para que realice esta tarea por nosotros y la llamamos desde nuestras implementaciones de data() y parent().
Almacenar punteros a elementos resulta práctico cuando controlamos cómo se crean y se destruyen, ya que podemos dar por hecho que una dirección obtenida mediante ` internalPointer()` es un puntero válido. Sin embargo, algunos modelos necesitan gestionar elementos que se obtienen de otros componentes del sistema y, en muchos casos, no es posible controlar por completo cómo se crean o se destruyen dichos elementos. En tales situaciones, un enfoque basado exclusivamente en punteros debe complementarse con medidas de seguridad para garantizar que el modelo no intente acceder a elementos que hayan sido eliminados.
| Almacenamiento de información en la estructura de datos subyacente Varios datos se almacenan como objetos de tipo « QVariant » en el miembro « El diagrama muestra cómo los datos, representados por las etiquetas a, b y c en los dos diagramas anteriores, se almacenan en los elementos A, B y C de la estructura de datos subyacente. Tenga en cuenta que los datos de una misma fila del modelo se obtienen todos del mismo elemento. Cada elemento de una lista se corresponde con un dato expuesto por cada columna de una fila determinada del modelo. | ![]() |
Dado que la implementación de « TreeModel » se ha diseñado para su uso con « QTreeView », hemos añadido una restricción sobre la forma en que utiliza las instancias de « TreeItem »: cada elemento debe exponer el mismo número de columnas de datos. Esto hace que la visualización del modelo sea coherente, lo que nos permite utilizar el elemento raíz para determinar el número de columnas de cualquier fila dada, y solo añade el requisito de que creemos elementos que contengan datos suficientes para el número total de columnas. Como resultado, insertar y eliminar columnas son operaciones que requieren mucho tiempo, ya que necesitamos recorrer todo el árbol para modificar cada elemento.
Un enfoque alternativo sería diseñar la clase « TreeModel » de modo que trunque o amplíe la lista de datos en las instancias individuales de « TreeItem » a medida que se modifican los elementos de datos. Sin embargo, este enfoque de redimensionamiento «perezoso» solo nos permitiría insertar y eliminar columnas al final de cada fila y no permitiría insertar o eliminar columnas en posiciones arbitrarias dentro de cada fila.
![]() | Relacionar elementos mediante índices de modelo Al igual que en el ejemplo del modelo de árbol simple, el ` En el diagrama, mostramos cómo la implementación de la función `parent()` del modelo obtiene el índice de modelo correspondiente al padre de un elemento proporcionado por el llamante, utilizando los elementos mostrados en un diagrama anterior. Se obtiene un puntero al elemento C a partir del índice de modelo correspondiente mediante la función ` QModelIndex::internalPointer()`. El puntero se almacenó internamente en el índice cuando se creó. Dado que el elemento hijo contiene un puntero a su padre, utilizamos su función `parent()` para obtener un puntero al elemento B. El índice del modelo padre se crea mediante la función ` QAbstractItemModel::createIndex()`, pasando el puntero al elemento B como puntero interno. |
Definición de la clase `TreeItem`
La clase « TreeItem » proporciona elementos sencillos que contienen varios datos, incluida información sobre sus elementos padre e hijos:
class TreeItem
{
public:
explicit TreeItem(QVariantList data, TreeItem *parent = nullptr);
TreeItem *child(int number);
int childCount() const;
int columnCount() const;
QVariant data(int column) const;
bool insertChildren(int position, int count, int columns);
bool insertColumns(int position, int columns);
TreeItem *parent();
bool removeChildren(int position, int count);
bool removeColumns(int position, int columns);
int row() const;
bool setData(int column, const QVariant &value);
private:
std::vector<std::unique_ptr<TreeItem>> m_childItems;
QVariantList itemData;
TreeItem *m_parentItem;
};Hemos diseñado la API para que sea similar a la que proporciona QAbstractItemModel, dotando a cada elemento de funciones para devolver el número de columnas de información, leer y escribir datos, e insertar y eliminar columnas. Sin embargo, hacemos explícita la relación entre los elementos proporcionando funciones para gestionar los «elementos secundarios» en lugar de las «filas».
Cada elemento contiene una lista de punteros a elementos hijos, un puntero a su elemento padre y una lista de objetos QVariant que se corresponden con la información contenida en las columnas de una fila determinada del modelo.
Implementación de la clase `TreeItem`
Cada objeto ` TreeItem ` se crea con una lista de datos y un elemento padre opcional:
TreeItem::TreeItem(QVariantList data, TreeItem *parent)
: itemData(std::move(data)), m_parentItem(parent)
{}Inicialmente, cada elemento no tiene hijos. Estos se añaden al miembro interno « childItems » del elemento mediante la función « insertChildren() », que se describe más adelante.
Los hijos se almacenan en std::unique_ptr para garantizar que cada hijo añadido al elemento se elimine cuando se elimine el propio elemento.
Dado que cada elemento almacena un puntero a su padre, la función ` parent() ` es trivial:
TreeItem *TreeItem::parent()
{
return m_parentItem;
}Hay tres funciones que proporcionan información sobre los hijos de un elemento. child() devuelve un hijo específico de la lista interna de hijos:
TreeItem *TreeItem::child(int number)
{
return (number >= 0 && number < childCount())
? m_childItems.at(number).get() : nullptr;
}La función childCount() devuelve el número total de elementos secundarios:
int TreeItem::childCount() const
{
return int(m_childItems.size());
}La función ` row() ` se utiliza para determinar el índice del hijo en la lista de hijos de su padre. Accede directamente al miembro ` childItems ` del padre para obtener esta información:
int TreeItem::row() const
{
if (!m_parentItem)
return 0;
const auto it = std::find_if(m_parentItem->m_childItems.cbegin(), m_parentItem->m_childItems.cend(),
[this](const std::unique_ptr<TreeItem> &treeItem) {
return treeItem.get() == this;
});
if (it != m_parentItem->m_childItems.cend())
return std::distance(m_parentItem->m_childItems.cbegin(), it);
Q_ASSERT(false); // should not happen
return -1;
}El elemento raíz no tiene ningún elemento padre; para este elemento, devolvemos cero para mantener la coherencia con los demás elementos.
La función ` columnCount() ` simplemente devuelve el número de elementos de la lista interna ` itemData ` de objetos ` QVariant `:
int TreeItem::columnCount() const
{
return int(itemData.count());
}Los datos se recuperan mediante la función ` data() `, que accede al elemento correspondiente de la lista ` itemData `:
QVariant TreeItem::data(int column) const
{
return itemData.value(column);
}Los datos se establecen mediante la función ` setData() `, que solo almacena valores en la lista ` itemData ` para los índices de lista válidos, correspondientes a los valores de las columnas del modelo:
bool TreeItem::setData(int column, const QVariant &value)
{
if (column < 0 || column >= itemData.size())
return false;
itemData[column] = value;
return true;
}Para facilitar la implementación del modelo, devolvemos «true» para indicar que los datos se han establecido correctamente.
Los modelos editables suelen necesitar ser redimensionables, lo que permite insertar y eliminar filas y columnas. La inserción de filas debajo de un índice determinado del modelo da lugar a la inserción de nuevos elementos secundarios en el elemento correspondiente, lo cual se gestiona mediante la función ` insertChildren() `:
bool TreeItem::insertChildren(int position, int count, int columns)
{
if (position < 0 || position > qsizetype(m_childItems.size()))
return false;
for (int row = 0; row < count; ++row) {
QVariantList data(columns);
m_childItems.insert(m_childItems.cbegin() + position,
std::make_unique<TreeItem>(data, this));
}
return true;
}Esto garantiza que los nuevos elementos se creen con el número necesario de columnas y se inserten en una posición válida dentro de la lista interna ` childItems `. Los elementos se eliminan mediante la función ` removeChildren() `:
bool TreeItem::removeChildren(int position, int count)
{
if (position < 0 || position + count > qsizetype(m_childItems.size()))
return false;
for (int row = 0; row < count; ++row)
m_childItems.erase(m_childItems.cbegin() + position);
return true;
}Como se ha comentado anteriormente, las funciones para insertar y eliminar columnas se utilizan de forma diferente a las destinadas a insertar y eliminar elementos secundarios, ya que se espera que se llamen para cada elemento del árbol. Para ello, llamamos de forma recursiva a esta función en cada elemento secundario del elemento:
bool TreeItem::insertColumns(int position, int columns)
{
if (position < 0 || position > itemData.size())
return false;
for (int column = 0; column < columns; ++column)
itemData.insert(position, QVariant());
for (auto &child : std::as_const(m_childItems))
child->insertColumns(position, columns);
return true;
}Definición de la clase TreeModel
La clase ` TreeModel ` proporciona una implementación de la clase ` QAbstractItemModel `, exponiendo la interfaz necesaria para un modelo que se puede editar y redimensionar.
class TreeModel : public QAbstractItemModel
{
Q_OBJECT
public:
Q_DISABLE_COPY_MOVE(TreeModel)
TreeModel(const QStringList &headers, const QString &data,
QObject *parent = nullptr);
~TreeModel() override;El constructor y el destructor son específicos de este modelo.
QVariant data(const QModelIndex &index, int role) const override;
QVariant headerData(int section, Qt::Orientation orientation,
int role = Qt::DisplayRole) const override;
QModelIndex index(int row, int column,
const QModelIndex &parent = {}) const override;
QModelIndex parent(const QModelIndex &index) const override;
int rowCount(const QModelIndex &parent = {}) const override;
int columnCount(const QModelIndex &parent = {}) const override;Los modelos de árbol de solo lectura solo tienen que proporcionar las funciones mencionadas anteriormente. Las siguientes funciones públicas permiten editar y cambiar el tamaño:
Qt::ItemFlags flags(const QModelIndex &index) const override;
bool setData(const QModelIndex &index, const QVariant &value,
int role = Qt::EditRole) override;
bool setHeaderData(int section, Qt::Orientation orientation,
const QVariant &value, int role = Qt::EditRole) override;
bool insertColumns(int position, int columns,
const QModelIndex &parent = {}) override;
bool removeColumns(int position, int columns,
const QModelIndex &parent = {}) override;
bool insertRows(int position, int rows,
const QModelIndex &parent = {}) override;
bool removeRows(int position, int rows,
const QModelIndex &parent = {}) override;
private:
void setupModelData(const QList<QStringView> &lines);
TreeItem *getItem(const QModelIndex &index) const;
std::unique_ptr<TreeItem> rootItem;
};Para simplificar este ejemplo, los datos que expone el modelo se organizan en una estructura de datos mediante la función setupModelData() del modelo. Muchos modelos del mundo real no procesan en absoluto los datos sin procesar, sino que simplemente trabajan con una estructura de datos existente o con la API de una biblioteca.
Implementación de la clase `TreeModel`
El constructor crea un elemento raíz y lo inicializa con los datos de cabecera proporcionados:
TreeModel::TreeModel(const QStringList &headers, const QString &data, QObject *parent)
: QAbstractItemModel(parent)
{
QVariantList rootData;
for (const QString &header : headers)
rootData << header;
rootItem = std::make_unique<TreeItem>(rootData);
setupModelData(QStringView{data}.split(u'\n'));
}Llamamos a la función interna setupModelData() para convertir los datos textuales proporcionados en una estructura de datos que podamos utilizar con el modelo. Otros modelos pueden inicializarse con una estructura de datos ya preparada, o bien utilizar una API de una biblioteca que gestione sus propios datos.
TreeModel::~TreeModel() = default;El destructor solo tiene que eliminar el elemento raíz, lo que provocará que todos los elementos hijos se eliminen de forma recursiva. Esto lo realiza automáticamente el destructor por defecto, ya que el elemento raíz se almacena dentro de un `unique_ptr`.
Dado que la interfaz del modelo con los demás componentes de modelo y vista se basa en índices del modelo, y dado que la estructura de datos interna se basa en elementos, muchas de las funciones implementadas por el modelo deben ser capaces de convertir cualquier índice del modelo dado en su elemento correspondiente. Por comodidad y coherencia, hemos definido una función ` getItem() ` para realizar esta tarea repetitiva:
TreeItem *TreeModel::getItem(const QModelIndex &index) const
{
if (index.isValid()) {
if (auto *item = static_cast<TreeItem*>(index.internalPointer()))
return item;
}
return rootItem.get();
}Cada índice del modelo pasado a esta función debe corresponder a un elemento válido en memoria. Si el índice no es válido, o si su puntero interno no apunta a un elemento válido, se devuelve en su lugar el elemento raíz.
La implementación de rowCount() en el modelo es sencilla: primero utiliza la función getItem() para obtener el elemento correspondiente; a continuación, devuelve el número de elementos secundarios que contiene:
int TreeModel::rowCount(const QModelIndex &parent) const
{
if (parent.isValid() && parent.column() > 0)
return 0;
const TreeItem *parentItem = getItem(parent);
return parentItem ? parentItem->childCount() : 0;
}Por el contrario, la implementación de columnCount() no necesita buscar un elemento concreto, ya que todos los elementos están definidos para tener asociado el mismo número de columnas.
int TreeModel::columnCount(const QModelIndex &parent) const
{
Q_UNUSED(parent);
return rootItem->columnCount();
}Como resultado, el número de columnas se puede obtener directamente del elemento raíz.
Para permitir la edición y selección de elementos, es necesario implementar la función ` flags() ` de modo que devuelva una combinación de indicadores que incluya los indicadores ` Qt::ItemIsEditable ` y ` Qt::ItemIsSelectable `, así como ` Qt::ItemIsEnabled`:
Qt::ItemFlags TreeModel::flags(const QModelIndex &index) const
{
if (!index.isValid())
return Qt::NoItemFlags;
return Qt::ItemIsEditable | QAbstractItemModel::flags(index);
}El modelo debe ser capaz de generar índices de modelo para permitir que otros componentes soliciten datos e información sobre su estructura. Esta tarea la lleva a cabo la función ` index() `, que se utiliza para obtener los índices de modelo correspondientes a los elementos hijos de un elemento padre determinado:
QModelIndex TreeModel::index(int row, int column, const QModelIndex &parent) const
{
if (parent.isValid() && parent.column() != 0)
return {};En este modelo, solo devolvemos índices del modelo para los elementos hijos si el índice del elemento padre no es válido (correspondiente al elemento raíz) o si tiene un número de columna igual a cero.
Utilizamos la función personalizada `getItem()` para obtener una instancia de ` TreeItem ` que se corresponda con el índice del modelo proporcionado, y solicitamos su elemento hijo que corresponda a la fila especificada.
TreeItem *parentItem = getItem(parent);
if (!parentItem)
return {};
if (auto *childItem = parentItem->child(row))
return createIndex(row, column, childItem);
return {};
}Dado que cada elemento contiene información de una fila completa de datos, creamos un índice de modelo para identificarlo de forma única llamando a ` createIndex()` con los números de fila y columna y un puntero al elemento. En la función `data()`, utilizaremos el puntero al elemento y el número de columna para acceder a los datos asociados al índice del modelo; en este modelo, no se necesita el número de fila para identificar los datos.
La función parent() proporciona índices de modelo para los elementos padres de los elementos: para ello, busca el elemento correspondiente a un índice de modelo dado, utiliza su función parent() para obtener su elemento padre y, a continuación, crea un índice de modelo que represente al elemento padre. (Véase el diagrama anterior).
QModelIndex TreeModel::parent(const QModelIndex &index) const
{
if (!index.isValid())
return {};
TreeItem *childItem = getItem(index);
TreeItem *parentItem = childItem ? childItem->parent() : nullptr;
return (parentItem != rootItem.get() && parentItem != nullptr)
? createIndex(parentItem->row(), 0, parentItem) : QModelIndex{};
}Los elementos sin padres, incluido el elemento raíz, se gestionan devolviendo un índice de modelo nulo. En los demás casos, se crea un índice de modelo y se devuelve como en la función `index()`, con un número de fila adecuado, pero con un número de columna igual a cero para mantener la coherencia con el esquema utilizado en la implementación de `index()`.
Pruebas del modelo
Implementar correctamente un modelo de elementos puede resultar complicado. La clase ` QAbstractItemModelTester ` del Qt Test módulo comprueba la coherencia del modelo, como la creación del índice del modelo y las relaciones padre-hijo.
Puedes probar tu modelo simplemente pasando una instancia del modelo al constructor de la clase, por ejemplo, como parte de una prueba unitaria de Qt Test:
class TestEditableTreeModel : public QObject
{
Q_OBJECT
private slots:
void testTreeModel();
};
void TestEditableTreeModel::testTreeModel()
{
constexpr auto fileName = ":/default.txt"_L1;
QFile file(fileName);
QVERIFY2(file.open(QIODevice::ReadOnly | QIODevice::Text),
qPrintable(fileName + " cannot be opened: "_L1 + file.errorString()));
const QStringList headers{"column1"_L1, "column2"_L1};
TreeModel model(headers, QString::fromUtf8(file.readAll()));
QAbstractItemModelTester tester(&model);
}
QTEST_APPLESS_MAIN(TestEditableTreeModel)
#include "test.moc"Para crear una prueba que se pueda ejecutar con el ejecutable ctest, se utiliza add_test():
# Unit Test
include(CTest)
qt_add_executable(editabletreemodel_tester
test.cpp
treeitem.cpp treeitem.h
treemodel.cpp treemodel.h)
target_link_libraries(editabletreemodel_tester PRIVATE
Qt6::Core
Qt6::Test
)
if(ANDROID)
target_link_libraries(editabletreemodel_tester PRIVATE
Qt6::Gui
)
endif()
qt_add_resources(editabletreemodel_tester "editabletreemodel_tester"
PREFIX
"/"
FILES
${editabletreemodel_resource_files}
)
add_test(NAME editabletreemodel_tester
COMMAND editabletreemodel_tester)© 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.



