En esta página

Repeater QML Type

Crea varias instancias de componentes basados en «Item» utilizando un modelo proporcionado. Más...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Métodos

Descripción detallada

El tipo «Repeater» se utiliza para crear un gran número de elementos similares. Al igual que otros tipos de vista, un «Repeater» tiene un « model » y un « delegate »: para cada entrada del modelo, el delegado se instancia en un contexto alimentado con datos del modelo. Un elemento «Repeater» suele estar encerrado en un tipo de posicionador, como « Row » o « Column », para posicionar visualmente los múltiples elementos delegados creados por el «Repeater».

El siguiente «Repeater» crea tres instancias de un elemento « Rectangle » dentro de un « Row »:

import QtQuick

Row {
    Repeater {
        model: 3
        Rectangle {
            width: 100; height: 40
            border.width: 1
            color: "yellow"
        }
    }
}

Tres rectángulos amarillos en fila creados con Repeater

El model de un Repeater puede ser cualquiera de los modelos de datos compatibles. Además, al igual que los delegados de otras vistas, un delegado de Repeater puede acceder a su índice dentro del Repeater, así como a los datos del modelo relevantes para el delegado. Consulte la documentación de la propiedad delegate para obtener más detalles.

Los elementos instanciados por el Repeater se insertan, en orden, como hijos del elemento padre del Repeater. La inserción comienza inmediatamente después de la posición del repetidor en la lista de apilamiento de su elemento padre. Esto permite utilizar un repetidor dentro de un diseño. Por ejemplo, los elementos del siguiente repetidor se apilan entre un rectángulo rojo y un rectángulo azul:

Row {
    Rectangle { width: 10; height: 20; color: "red" }
    Repeater {
        model: 10
        Rectangle { width: 20; height: 20; radius: 10; color: "green" }
    }
    Rectangle { width: 10; height: 20; color: "blue" }
}

Fila con un rectángulo rojo, diez círculos verdes del «Repeater» y un rectángulo azul

Nota: Un elemento del Repeater es propietario de todos los elementos que instancia. Eliminar o destruir dinámicamente un elemento creado por un Repeater da lugar a un comportamiento impredecible.

Consideraciones al utilizar el Repeater

El tipo «Repeater» crea todos sus elementos delegados cuando se crea el «Repeater» por primera vez. Esto puede resultar ineficiente si hay un gran número de elementos delegados y no es necesario que todos los elementos estén visibles al mismo tiempo. Si este es el caso, plantéate utilizar otros tipos de vista, como « ListView » (que solo crea elementos delegados cuando estos aparecen en la vista al desplazarse), o utiliza los métodos de « Dynamic Object Creation » para crear elementos a medida que sean necesarios.

Además, ten en cuenta que «Repeater» se basa en « Item » y solo puede repetir objetos derivados de « Item ». Por ejemplo, no se puede utilizar para repetir «QtObjects»:

// bad code:
Item {
    // Can't repeat QtObject as it doesn't derive from Item.
    Repeater {
        model: 10
        QtObject {}
    }
}

Documentación de propiedades

count : int [read-only]

Esta propiedad contiene el número de elementos de la lista « model ».

El valor de « count » no siempre coincide con el número de « delegates » instanciados; utiliza « itemAt()» para comprobar si existe un delegado en un índice determinado. Devuelve « null » si el delegado no está instanciado.

  • Mientras el Repeater está instanciando delegados (al iniciarse o debido a cambios en model ), se emite la señal itemAdded por cada delegado creado, y la propiedad count cambia a continuación.
  • Si el Repeater no forma parte de una jerarquía visual completa, count refleja el tamaño del modelo, pero no se crean delegados.
  • Si el Repeater destruye delegados debido a cambios en model, se emite la señal itemRemoved() para cada uno de ellos, y la propiedad count cambia a continuación.
  • Si el Repeater se elimina de la jerarquía visual (por ejemplo, estableciendo ` parent = null`), los delegados se destruyen, se emite la señal ` itemRemoved()` para cada uno de ellos, pero ` count ` no cambia.

Véanse también itemAt(), itemAdded() y itemRemoved().

delegate : Component [default]

El delegado proporciona una plantilla que define cada elemento instanciado por el repetidor.

Los delegados tienen disponible una propiedad de solo lectura ` index ` que indica el índice del delegado dentro del repetidor. Por ejemplo, el siguiente delegado ` Text ` muestra el índice de cada elemento repetido:

Column {
    Repeater {
        model: 10
        Text {
            required property int index
            text: "I'm item " + index
        }
    }
}

Elementos de texto que muestran desde «Soy el elemento 0» hasta «Soy el elemento 9»

Si model es una lista de cadenas u objetos, el delegado también tiene a su disposición una propiedad de solo lectura modelData que contiene los datos de las cadenas u objetos. Por ejemplo:

Column {
    Repeater {
        model: ["apples", "oranges", "pears"]
        Text {
            required property string modelData
            text: "Data: " + modelData
        }
    }
}

Elementos de texto que muestran «Datos: manzanas», «Datos: naranjas», «Datos: peras»

Si el « model » es un objeto de modelo (como un « ListModel »), el delegado puede acceder a todas las funciones del modelo como propiedades con nombre, del mismo modo que lo hacen los delegados para clases de vista como « ListView ».

Véase también Modelos de datos de QML.

delegateModelAccess : enumeration [since 6.10]

Esta propiedad determina cómo pueden acceder los delegados al modelo.

ConstanteDescripción
DelegateModel.ReadOnlyImpide que los delegados escriban en el modelo a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias.
DelegateModel.ReadWritePermite a los delegados escribir en el modelo mediante las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias.
DelegateModel.Qt5ReadWritePermite a los delegados escribir en el modelo mediante el objeto ` model ` y las propiedades de contexto, pero no mediante las propiedades obligatorias.

El valor predeterminado es ` DelegateModel.Qt5ReadWrite`.

Esta propiedad se introdujo en Qt 6.10.

Véase también «Modelos y vistas» en Qt Quick, apartado «Modificación de los datos del modelo».

model : var

El modelo que proporciona datos al repetidor.

Esta propiedad se puede configurar con cualquiera de los modelos de datos compatibles:

  • Un número que indica el número de delegados que debe crear el repetidor
  • Un modelo (por ejemplo, un elemento de tipo ` ListModel ` o una subclase de ` QAbstractItemModel `)
  • Una lista de cadenas
  • Una lista de objetos

El tipo de modelo influye en las propiedades que se exponen a delegate.

Véase también «Modelos de datos».

Documentación de Signal

itemAdded(int index, Item item)

Esta señal se emite cuando se añade un elemento al repetidor. El parámetro « index » contiene el índice en el que se ha insertado el elemento dentro del repetidor, y el parámetro « item » contiene el « Item » que se ha añadido.

Nota: El controlador correspondiente es onItemAdded.

itemRemoved(int index, Item item)

Esta señal se emite cuando se elimina un elemento del repetidor. El parámetro « index » contiene el índice en el que se eliminó el elemento del repetidor, y el parámetro « item » contiene el « Item » que se ha eliminado.

No mantengas una referencia a item si fue creado por este repetidor, ya que en estos casos se eliminará poco después de que se gestione la señal.

Nota: El controlador correspondiente es onItemRemoved.

Documentación del método

Item itemAt(index)

Devuelve el objeto ` Item ` que se ha creado en la dirección ` index`, o en ` null ` si no existe ningún elemento en ` index`.

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