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 `:
- La propiedad de rol `hasModelChildren ` permite determinar si un nodo tiene nodos hijos.
- DelegateModel::rootIndex permite especificar el nodo raíz
- DelegateModel::modelIndex() devuelve un ` QModelIndex ` que se puede asignar a DelegateModel::rootIndex
- DelegateModel::parentModelIndex() devuelve un ` QModelIndex ` que se puede asignar a DelegateModel::rootIndex
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++ | |
| QML | |
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.