En esta página

ListModel QML Type

Define una fuente de datos de lista de formato libre. Más información...

Import Statement: import QtQml.Models

Propiedades

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

Lista en la que figuran las manzanas, las naranjas y los plátanos con sus precios

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:

Lista en la que se muestran frutas con datos de atributos anidados

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.