ListModel QML Type
Define una fuente de datos de lista de formato libre. Más información...
| Import Statement: | import QtQml.Models |
Propiedades
- count : int
- dynamicRoles : bool
Métodos
- void append(jsobject dict)
- void clear()
- var get(int index)
- void insert(int index, jsobject dict)
- void move(int from, int to, int n)
- void remove(int index, int count)
- void set(int index, jsobject dict)
- void setProperty(int index, string property, var value)
- void sync()
Descripción detallada
El ListModel es un contenedor sencillo de definiciones de « ListElement », cada una de las cuales contiene roles de datos. El contenido se puede definir de forma dinámica o explícita en QML.
El número de elementos del modelo se puede obtener a través de su propiedad ` count `. También se proporcionan varios métodos habituales para manipular el contenido del modelo, entre ellos ` append()`, ` insert()`, ` move()`, ` remove()` y ` set()`. Estos métodos aceptan diccionarios como argumentos; el modelo los convierte en objetos ` ListElement `.
Los elementos se pueden manipular a través del modelo utilizando el método setProperty(), que permite establecer y modificar los roles del elemento especificado.
ListModel hereda de QAbstractListModel y proporciona sus métodos Q_INVOKABLE. Por ejemplo, puedes utilizar QAbstractItemModel::index para recuperar un QModelIndex correspondiente a una fila y una columna.
Ejemplo de uso
El siguiente ejemplo muestra un ListModel que contiene tres elementos, con los roles «name» y «cost».

import QtQuick
ListModel {
id: fruitModel
ListElement {
name: "Apple"
cost: 2.45
}
ListElement {
name: "Orange"
cost: 3.25
}
ListElement {
name: "Banana"
cost: 1.95
}
}Los roles (propiedades) de cada elemento deben comenzar con una letra minúscula y deben ser comunes a todos los elementos del modelo. La documentación de ListElement ofrece más directrices sobre cómo deben definirse los elementos.
Dado que el modelo de ejemplo contiene una propiedad « id », las vistas pueden hacer referencia a ella, como en el caso de « ListView » en este ejemplo:
import QtQuick
Rectangle {
width: 200; height: 200
ListModel {
id: fruitModel
...
}
Component {
id: fruitDelegate
Row {
spacing: 10
Text { text: name }
Text { text: '$' + cost }
}
}
ListView {
anchors.fill: parent
model: fruitModel
delegate: fruitDelegate
}
}Es posible que los roles contengan datos de lista. En el siguiente ejemplo creamos una lista de atributos de frutas:
ListModel {
id: fruitModel
ListElement {
name: "Apple"
cost: 2.45
attributes: [
ListElement { description: "Core" },
ListElement { description: "Deciduous" }
]
}
ListElement {
name: "Orange"
cost: 3.25
attributes: [
ListElement { description: "Citrus" }
]
}
ListElement {
name: "Banana"
cost: 1.95
attributes: [
ListElement { description: "Tropical" },
ListElement { description: "Seedless" }
]
}
}El delegado muestra todos los atributos de las frutas:

Component {
id: fruitDelegate
Item {
width: 200; height: 50
Text { id: nameField; text: name }
Text { text: '$' + cost; anchors.left: nameField.right }
Row {
anchors.top: nameField.bottom
spacing: 5
Text { text: "Attributes:" }
Repeater {
model: attributes
Text { text: description }
}
}
}
}Modificación de modelos de lista
El contenido de un ListModel se puede crear y modificar utilizando los métodos clear(), append(), set(), insert() y setProperty(). Por ejemplo:
Component {
id: fruitDelegate
Item {
width: 200; height: 50
Text { text: name }
Text { text: '$' + cost; anchors.right: parent.right }
// Double the price when clicked.
MouseArea {
anchors.fill: parent
onClicked: fruitModel.setProperty(index, "cost", cost * 2)
}
}
}Ten en cuenta que, al crear contenido de forma dinámica, el conjunto de propiedades disponibles no se puede modificar una vez establecido. Las propiedades que se añadan primero al modelo serán las únicas permitidas en él.
Uso de modelos de lista multihilo con WorkerScript
ListModel se puede utilizar junto con WorkerScript para acceder a un modelo de lista desde varios subprocesos. Esto resulta útil si las modificaciones de la lista son sincrónicas y llevan cierto tiempo: las operaciones de la lista se pueden trasladar a un subproceso diferente para evitar el bloqueo del subproceso principal de la interfaz gráfica de usuario.
A continuación se muestra un ejemplo que utiliza ` WorkerScript ` para añadir periódicamente la hora actual a un modelo de lista:
Timer {
id: timer
interval: 2000; repeat: true
running: true
triggeredOnStart: true
onTriggered: {
var msg = {'action': 'appendCurrentTime', 'model': listModel};
worker.sendMessage(msg);
}
}El archivo incluido, dataloader.mjs, tiene este aspecto:
WorkerScript.onMessage = function(msg) {
if (msg.action == 'appendCurrentTime') {
var data = {'time': new Date().toTimeString()};
msg.model.append(data);
msg.model.sync(); // updates the changes to the list
}
}El temporizador del ejemplo principal envía mensajes al script de trabajo llamando a ` WorkerScript::sendMessage()`. Cuando se recibe este mensaje, se invoca ` WorkerScript.onMessage() ` en ` dataloader.mjs`, lo que añade la hora actual al modelo de lista.
Fíjate en la llamada a ` sync()` desde el hilo externo. Debes llamar a ` sync()`, ya que, de lo contrario, los cambios realizados en la lista desde ese hilo no se reflejarán en el modelo de lista del hilo principal.
Véase también Modelos de datos y Qt Qml.
Documentación de propiedades
count : int [read-only]
El número de registros de datos del modelo.
dynamicRoles : bool
Por defecto, el tipo de un rol queda fijado la primera vez que se utiliza dicho rol. Por ejemplo, si creas un rol llamado «data» y le asignas un número, ya no podrás asignarle una cadena al rol «data». Sin embargo, cuando la propiedad dynamicRoles está habilitada, el tipo de un rol determinado no queda fijado y puede variar entre los distintos elementos.
La propiedad `dynamicRoles` debe configurarse antes de añadir cualquier dato a la ` ListModel`, y debe configurarse desde el hilo principal.
Un ` ListModel ` cuyos datos estén definidos de forma estática (mediante la sintaxis QML ` ListElement `) no puede tener habilitada la propiedad `dynamicRoles`.
El uso de un ` ListModel ` con roles dinámicos habilitados conlleva un coste de rendimiento significativo. Este coste varía de una plataforma a otra, pero suele ser entre 4 y 6 veces más lento que el uso de tipos de roles estáticos.
Debido al coste en rendimiento que supone el uso de roles dinámicos, estos vienen desactivados por defecto.
Documentación del método
void append(jsobject dict)
Añade un nuevo elemento al final del modelo de lista, con los valores de dict.
fruitModel.append({"cost": 5.95, "name":"Pizza"})Véanse también set() y remove().
void clear()
Elimina todo el contenido del modelo. En concreto, esto invalida todos los objetos que hayas podido recuperar mediante get().
Véanse también append(), remove() y get().
var get(int index)
Devuelve el elemento situado en index en el modelo de lista. Esto permite acceder a los datos del elemento o modificarlos desde JavaScript:
Component.onCompleted: {
fruitModel.append({"cost": 5.95, "name":"Jackfruit"});
console.log(fruitModel.get(0).cost);
fruitModel.get(0).cost = 10.95;
}El index debe ser un elemento de la lista.
Ten en cuenta que las propiedades del objeto devuelto que sean a su vez objetos también serán modelos, y este método get() se utiliza para acceder a los elementos:
fruitModel.append(..., "attributes":
[{"name":"spikes","value":"7mm"},
{"name":"color","value":"green"}]);
fruitModel.get(0).attributes.get(1).value; // == "green"Advertencia: No se garantiza queel objeto devuelto siga siendo válido. No debe utilizarse en enlaces de propiedades ni para almacenar datos tras modificaciones de su elemento de origen ` ListModel`.
Véase también ` append()` y ` clear()`.
void insert(int index, jsobject dict)
Añade un nuevo elemento al modelo de lista en la posición index, con los valores de dict.
fruitModel.insert(2, {"cost": 5.95, "name":"Pizza"})El index debe corresponder a un elemento existente de la lista o a uno situado más allá del final de la lista (equivalente a «append»).
Véanse también set() y append().
void move(int from, int to, int n)
Mueve los elementos « n » from una posición to otra.
Los intervalos «from» y «to» deben existir; por ejemplo, para mover los tres primeros elementos al final de la lista:
fruitModel.move(0, fruitModel.count - 3, 3)Véase también append().
void remove(int index, int count = 1)
Elimina del modelo un número de elementos count en index.
Véase también clear().
void set(int index, jsobject dict)
Modifica el elemento de index en el modelo de lista con los valores de dict. Las propiedades que no aparecen en dict no se modifican.
fruitModel.set(3, {"cost": 5.95, "name":"Pizza"})Si index es igual a count(), se añade un nuevo elemento a la lista. De lo contrario, index debe ser un elemento de la lista.
Véase también append().
void setProperty(int index, string property, var value)
Cambia el campo « property » del elemento situado en index del modelo de lista por value.
fruitModel.setProperty(3, "cost", 5.95)El index debe ser un elemento de la lista.
Véase también append().
void sync()
Guarda los cambios no guardados en el modelo de lista después de que haya sido modificado desde un script de trabajo.
© 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.