En esta página

Uso de modelos C++ con vistas de Qt Quick

Datos proporcionados en un modelo C++ personalizado

Los modelos se pueden definir en C++ y, a continuación, poner a disposición de QML. Esto resulta útil para exponer a QML modelos de datos existentes en C++ o conjuntos de datos complejos.

Una clase de modelo en C++ puede definirse como un « QStringList », un « QVariantList », un « QObjectList » o un « QAbstractItemModel ». Los tres primeros son útiles para exponer conjuntos de datos más sencillos, mientras que « QAbstractItemModel » ofrece una solución más flexible para modelos más complejos.

Modelo basado en QStringList

Un modelo puede ser un simple ` QStringList`, que proporciona el contenido de la lista a través del rol `modelData `.

A continuación se muestra un ` ListView ` con un delegado que hace referencia al valor de su elemento de modelo mediante el rol ` modelData `:

ListView {
    width: 100
    height: 100
    required model

    delegate: Rectangle {
        required property string modelData
        height: 25
        width: 100
        Text { text: parent.modelData }
    }
}

Una aplicación Qt puede cargar este documento QML y establecer el valor de ` myModel ` como ` QStringList`:

    QStringList dataList = {
        "Item 1",
        "Item 2",
        "Item 3",
        "Item 4"
    };

    QQuickView view;
    view.setInitialProperties({{ "model", QVariant::fromValue(dataList) }});

El código fuente completo de este ejemplo está disponible en examples/quick/models/stringlistmodel, dentro del directorio de instalación de Qt.

Nota: La vista notiene forma de saber que el contenido de un ` QStringList ` ha cambiado. Si el ` QStringList ` cambia, será necesario restablecer el modelo volviendo a establecer la propiedad ` model ` de la vista.

Modelo basado en QVariantList

Un modelo puede ser un único ` QVariantList`, que proporciona el contenido de la lista a través del rol `modelData `.

La API funciona exactamente igual que con QStringList, tal y como se muestra en la sección anterior.

Nota: La vista notiene forma de saber que el contenido de un ` QVariantList ` ha cambiado. Si cambia el ` QVariantList `, será necesario restablecer el modelo volviendo a establecer la propiedad ` model ` de la vista.

Modelo basado en QObjectList

También se puede utilizar como modelo una lista de valores de QObject*. Un QList<QObject*> proporciona las propiedades de los objetos de la lista como roles.

La siguiente aplicación crea una clase ` DataObject ` con valores ` Q_PROPERTY ` a los que se podrá acceder como roles con nombre cuando se exponga un ` QList` a QML:

class DataObject : public QObject
{
    Q_OBJECT

    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
    Q_PROPERTY(QString color READ color WRITE setColor NOTIFY colorChanged)
    ...
};

int main(int argc, char ** argv)
{
    QGuiApplication app(argc, argv);

    const QStringList colorList = {"red",
                                   "green",
                                   "blue",
                                   "yellow"};

    const QStringList moduleList = {"Core", "GUI", "Multimedia", "Multimedia Widgets", "Network",
                                    "QML", "Quick", "Quick Controls", "Quick Dialogs",
                                    "Quick Layouts", "Quick Test", "SQL", "Widgets", "3D",
                                    "Android Extras", "Bluetooth", "Concurrent", "D-Bus",
                                    "Gamepad", "Graphical Effects", "Help", "Image Formats",
                                    "Location", "Mac Extras", "NFC", "OpenGL", "Platform Headers",
                                    "Positioning", "Print Support", "Purchasing", "Quick Extras",
                                    "Quick Timeline", "Quick Widgets", "Remote Objects", "Script",
                                    "SCXML", "Script Tools", "Sensors", "Serial Bus",
                                    "Serial Port", "Speech", "SVG", "UI Tools", "WebEngine",
                                    "WebSockets", "WebView", "Windows Extras", "XML",
                                    "XML Patterns", "Charts", "Network Authorization",
                                    "Virtual Keyboard", "Quick 3D", "Quick WebGL"};

    QList<QObject *> dataList;
    for (const QString &module : moduleList)
        dataList.append(new DataObject("Qt " + module, colorList.at(rand() % colorList.length())));

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.setInitialProperties({{ "model", QVariant::fromValue(dataList) }});
    ...

El ` QObject*` está disponible como la propiedad ` modelData `. Para mayor comodidad, las propiedades del objeto también están disponibles directamente en el contexto del delegado. Aquí, ` view.qml ` hace referencia a las propiedades ` DataModel ` en el delegado ` ListView `:

ListView {
    id: listview
    width: 200; height: 320
    required model
    ScrollBar.vertical: ScrollBar { }

    delegate: Rectangle {
        width: listview.width; height: 25

        required color
        required property string name

        Text { text: parent.name }
    }
}

Fíjate en el uso de la propiedad color. Puedes requerir propiedades existentes declarándolas como required en un tipo derivado.

El código fuente completo de este ejemplo está disponible en examples/quick/models/objectlistmodel, dentro del directorio de instalación de Qt.

Nota: La vista notiene forma de saber que el contenido de un « QObjectList » ha cambiado. Si el « QObjectList » cambia, será necesario restablecer el modelo volviendo a establecer la propiedad « model » de la vista.

Subclase de QAbstractItemModel

Se puede definir un modelo creando una subclase de ` QAbstractItemModel`. Este es el mejor enfoque si se dispone de un modelo más complejo que no puede ser gestionado por los otros enfoques. Un ` QAbstractItemModel ` también puede notificar automáticamente a una vista QML cuando cambian los datos del modelo.

Los roles de una subclase de ` QAbstractItemModel ` pueden exponerse a QML reimplementando ` QAbstractItemModel::roleNames()`.

A continuación se muestra una aplicación con una subclase de ` QAbstractListModel ` llamada ` AnimalModel`, que expone los roles «type » y «sizes ». Reimplementa ` QAbstractItemModel::roleNames()` para exponer los nombres de los roles, de modo que se pueda acceder a ellos a través de QML:

class Animal
{
public:
    Animal(const QString &type, const QString &size);
    ...
};

class AnimalModel : public QAbstractListModel
{
    Q_OBJECT
public:
    enum AnimalRoles {
        TypeRole = Qt::UserRole + 1,
        SizeRole
    };

    AnimalModel(QObject *parent = nullptr);
    ...
};

QHash<int, QByteArray> AnimalModel::roleNames() const {
    QHash<int, QByteArray> roles;
    roles[TypeRole] = "type";
    roles[SizeRole] = "size";
    return roles;
}

int main(int argc, char ** argv)
{
    QGuiApplication app(argc, argv);

    AnimalModel model;
    model.addAnimal(Animal("Wolf", "Medium"));
    model.addAnimal(Animal("Polar bear", "Large"));
    model.addAnimal(Animal("Quoll", "Small"));

    QQuickView view;
    view.setResizeMode(QQuickView::SizeRootObjectToView);
    view.setInitialProperties({{"model", QVariant::fromValue(&model)}});
    ...

Este modelo se muestra mediante un delegado de « ListView » que accede a los roles «type » y «size »:

ListView {
    width: 200; height: 250

    required model

    delegate: Text {
        required property string type
        required property string size

        text: "Animal: " + type + ", " + size
    }
}

Las vistas QML se actualizan automáticamente cuando el modelo cambia. Recuerda que el modelo debe seguir las reglas estándar para los cambios en el modelo y notificar a la vista cuando el modelo haya cambiado utilizando QAbstractItemModel::dataChanged(), QAbstractItemModel::beginInsertRows(), etc. Consulta la referencia sobre subclasificación de modelos para obtener más información.

El código fuente completo de este ejemplo está disponible en examples/quick/models/abstractitemmodel, dentro del directorio de instalación de Qt.

QAbstractItemModel presenta una jerarquía de tablas, pero las vistas que ofrece actualmente QML solo pueden mostrar datos de lista. Para mostrar las listas secundarias de un modelo jerárquico, utilice el tipo QML ` DelegateModel `, que proporciona las siguientes propiedades y funciones para su uso con modelos de lista del tipo ` QAbstractItemModel `:

Exposición de modelos de datos C++ a QML

Los ejemplos anteriores utilizan propiedades obligatorias en la vista para establecer valores del modelo directamente en componentes QML. Una alternativa a esto es registrar la clase de modelo de C++ como un tipo QML (véase Definición de tipos QML desde C++). Esto permite crear las clases de modelo directamente como tipos dentro de QML:

C++
class MyModel : public QAbstractItemModel
{
    Q_OBJECT
    QML_ELEMENT

    // [...]
}
QML
MyModel {
    id: myModel
}
ListView {
    width: 200; height: 250
    model: myModel
    delegate: Text {
        required property string someProperty
        text: someProperty
    }
}

Consulta «Escribir extensiones de QML con C++» para obtener más detalles sobre cómo escribir tipos de QML en C++.

Modificación de los datos del modelo

Además de los métodos ` roleNames() ` y ` data()`, los modelos editables deben reimplementar el método ` setData ` para guardar los cambios en los datos del modelo existentes. La siguiente versión del método comprueba si el índice del modelo dado es válido y si ` role ` es igual a ` Qt::EditRole`:

bool EditableModel::setData(const QModelIndex &index, const QVariant &value, int role)
{
    if (index.isValid() && role == Qt::EditRole) {
        // Set data in model here. It can also be a good idea to check whether
        // the new value actually differs from the current value
        if (m_entries[index.row()] != value.toString()) {
            m_entries[index.row()] = value.toString();
            emit dataChanged(index, index, { Qt::EditRole, Qt::DisplayRole });
            return true;
        }
    }
    return false;
}

Nota: Es importante emitir la señal dataChanged() tras guardar los cambios.

A diferencia de las vistas de elementos de C++, como QListView o QTableView, el método setData() debe invocarse explícitamente desde los delegados de QML siempre que sea necesario. Esto se hace simplemente asignando un nuevo valor a la propiedad del modelo correspondiente.

ListView {
    anchors.fill: parent
    model: EditableModel {}
    delegate: TextField {
        width: ListView.view.width
        text: model.edit
        onAccepted: model.edit = text
    }
}

Nota: El rol « edit » es equivalente a « Qt::EditRole ». Consulte « roleNames()» para conocer los nombres de los roles integrados. Sin embargo, en la práctica, los modelos suelen registrar roles personalizados.

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