En esta página

ListView QML Type

Ofrece una vista en forma de lista de los elementos proporcionados por un modelo. Más...

Import Statement: import QtQuick
Inherits:

Flickable

Propiedades

Propiedades adjuntas

Señales adjuntas

Métodos

Descripción detallada

Un ListView muestra datos procedentes de modelos creados a partir de tipos QML integrados, como ListModel y XmlListModel, o de clases de modelo personalizadas definidas en C++ que heredan de QAbstractItemModel o QAbstractListModel.

Un ListView tiene un ` model`, que define los datos que se van a mostrar, y un ` delegate`, que define cómo deben mostrarse dichos datos. Los elementos de un ListView se disponen horizontal o verticalmente. Las vistas de lista son intrínsecamente desplazables, ya que ListView hereda de ` Flickable`.

Nota: ListView solo cargará tantos elementos delegados como sean necesarios para llenar la vista. Los elementos que queden fuera de la vista no se cargarán a menos que se haya establecido un cacheBuffer suficiente. Por lo tanto, es posible que un ListView con anchura o altura nula no cargue ningún elemento delegado.

Ejemplo de uso

El siguiente ejemplo muestra la definición de un modelo de lista sencillo definido en un archivo llamado ` ContactModel.qml`:

import QtQuick

ListModel {
    ListElement {
        name: "Bill Smith"
        number: "555 3264"
    }
    ListElement {
        name: "John Brown"
        number: "555 8426"
    }
    ListElement {
        name: "Sam Wise"
        number: "555 0473"
    }
}

Otro componente puede mostrar los datos de este modelo en un ListView, de la siguiente manera:

import QtQuick

ListView {
    width: 180; height: 200

    model: ContactModel {}
    delegate: Text {
        required property string name
        required property string number
        text: name + ": " + number
    }
}

ListView que muestra tres contactos con sus nombres y números de teléfono

Aquí, el ListView crea un componente « ContactModel » para su modelo y un elemento « Text » para su delegado. La vista creará un nuevo componente « Text » para cada elemento del modelo. Obsérvese que el delegado puede acceder directamente a los datos « name » y « number » del modelo.

A continuación se muestra una vista de lista mejorada. El delegado se ha mejorado visualmente y se ha trasladado a un componente independiente contactDelegate.

Rectangle {
    width: 180; height: 200

    Component {
        id: contactDelegate
        Item {
            id: myItem
            required property string name
            required property string number
            width: 180; height: 40
            Column {
                Text { text: '<b>Name:</b> ' + myItem.name }
                Text { text: '<b>Number:</b> ' + myItem.number }
            }
        }
    }

    ListView {
        anchors.fill: parent
        model: ContactModel {}
        delegate: contactDelegate
        highlight: Rectangle { color: "lightsteelblue"; radius: 5 }
        focus: true
    }
}

ListView con elementos de contacto con estilo y resaltado en azul en la selección actual

El elemento seleccionado actualmente se resalta con un Rectangle azul mediante la propiedad highlight, y focus se establece en true para habilitar la navegación mediante el teclado en la vista de lista. La propia vista de lista es un ámbito de foco (consulta «Foco del teclado» en Qt Quick para obtener más detalles).

Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Por lo tanto, state should never be stored in a delegate. Los delegados suelen estar asociados a ` contentItem` de `ListView`, pero, dependiendo de si están visibles en la vista o no, el elemento padre puede cambiar y, en ocasiones, ser ` null`. Por este motivo, no se recomienda vincular las propiedades del elemento padre desde dentro del delegado. Si deseas que el delegado ocupe todo el ancho del ListView, considera utilizar uno de los siguientes enfoques en su lugar:

ListView {
    id: listView
    // ...

    delegate: Item {
        // Incorrect.
        width: parent.width

        // Correct.
        width: listView.width
        width: ListView.view.width
        // ...
    }
}

ListView adjunta una serie de propiedades al elemento raíz del delegado, por ejemplo, ` ListView.isCurrentItem`. En el siguiente ejemplo, el elemento raíz del delegado puede acceder a esta propiedad adjunta directamente como ` ListView.isCurrentItem`, mientras que el objeto hijo ` contactInfo ` debe hacer referencia a esta propiedad como ` wrapper.ListView.isCurrentItem`.

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

Nota: Las vistas no activan el recorte automáticamente. Si la vista no está recortada por otro elemento o por la pantalla, será necesario establecer `clip: true ` para que los elementos que quedan fuera de la vista se recorten correctamente.

Diseños de ListView

El diseño de los elementos en un ListView se puede controlar mediante estas propiedades:

  • orientation - controla si los elementos se disponen horizontalmente o verticalmente. Este valor puede ser Qt.Horizontal o Qt.Vertical.
  • layoutDirection - controla la dirección de disposición horizontal para una vista orientada horizontalmente: es decir, si los elementos se disponen desde el lado izquierdo de la vista hacia la derecha, o viceversa. Este valor puede ser Qt.LeftToRight o Qt.RightToLeft.
  • verticalLayoutDirection - controla la dirección de disposición vertical para una vista orientada verticalmente: es decir, si los elementos se disponen desde la parte superior de la vista hacia la parte inferior, o viceversa. Este valor puede ser ListView.TopToBottom o ListView.BottomToTop.

Por defecto, una ListView tiene orientación vertical y los elementos se disponen de arriba abajo. La tabla siguiente muestra las diferentes disposiciones que puede tener una ListView, en función de los valores de las propiedades enumeradas anteriormente.

ListViews con orientación Qt.Vertical
De arriba abajo

Lista vertical con los elementos del 0 al 4 ordenados de arriba abajo

De abajo hacia arriba

Lista vertical con los elementos del 0 al 4 ordenados de abajo hacia arriba

ListViews con orientación Qt.Horizontal
De izquierda a derecha

Lista horizontal con elementos del 0 al 4 ordenados de izquierda a derecha

De derecha a izquierda

Lista horizontal con elementos del 0 al 4 ordenados de derecha a izquierda

Dirección de desplazamiento

Por defecto, una ListView vertical establece ` flickableDirection ` en `Flickable.Vertical`, y una ListView horizontal lo establece en ` Flickable.Horizontal`. Además, una ListView vertical solo calcula (estima) ` contentHeight`, y una ListView horizontal solo calcula ` contentWidth`. La otra dimensión se establece en -1.

Desde Qt 5.9 (Qt Quick 2.9), es posible crear un ListView en el que se pueda deslizar en ambas direcciones. Para ello, se puede establecer la propiedad « flickableDirection » en «Flickable.AutoFlickDirection» o «Flickable.AutoFlickIfNeeded», y hay que especificar el «contentWidth» o «contentHeight» deseados.

ListView {
    width: 180; height: 200

    contentWidth: 320
    flickableDirection: Flickable.AutoFlickDirection

    model: ContactModel {}
    delegate: Row {
        Text { text: '<b>Name:</b> ' + name; width: 160 }
        Text { text: '<b>Number:</b> ' + number; width: 160 }
    }
}

Orden de superposición en ListView

El valor « Z value » de los elementos determina si se muestran por encima o por debajo de otros elementos. ListView utiliza varios valores «Z» predeterminados diferentes, dependiendo del tipo de elemento que se esté creando:

PropiedadValor Z predeterminado
delegate1
footer1
header1
highlight0
section.delegate2

Estos valores por defecto se establecen si el valor Z del elemento es 0, por lo que establecer el valor Z de estos elementos en 0 no tiene ningún efecto. Ten en cuenta que el valor Z es de tipo real, por lo que es posible establecer valores fraccionarios como 0.1.

Reutilización de elementos

Desde la versión 5.15, ListView puede configurarse para reciclar elementos en lugar de instanciarlos desde delegate cada vez que se desplazan nuevas filas a la vista. Este enfoque mejora el rendimiento, dependiendo de la complejidad del delegado. La reutilización de elementos está desactivada por defecto (por motivos de compatibilidad con versiones anteriores), pero puede activarse estableciendo la propiedad reuseItems en true.

Cuando un elemento se elimina con un movimiento rápido, pasa al grupo de reutilización, que es una caché interna de elementos no utilizados. Cuando esto ocurre, se emite la señal « ListView::pooled » para informar al elemento al respecto. Del mismo modo, cuando el elemento vuelve a recuperarse del grupo, se emite la señal « ListView::reused ».

Cualquier propiedad del elemento que provenga del modelo se actualiza cuando se reutiliza el elemento. Esto incluye index y row, pero también cualquier rol del modelo.

Nota: Avoid storing any state inside a delegate. Si lo haces, restablece el valor manualmente al recibir la señal ListView::reused.

Si un elemento tiene temporizadores o animaciones, considera la posibilidad de pausarlos al recibir la señal « ListView::pooled ». De este modo, evitarás utilizar los recursos de la CPU para elementos que no están visibles. Del mismo modo, si un elemento tiene recursos que no se pueden reutilizar, estos podrían liberarse.

Nota: Aunque un elemento se encuentre en el pool, puede seguir activo y responder a las señales y enlaces conectados.

Nota: Para que un elemento se incluya en el grupo, debe salir completamente de los límites de la vista, incluidos los márgenes adicionales establecidos con ` cacheBuffer`. Algunos elementos tampoco se incluirán nunca en el grupo ni se reutilizarán, como ` currentItem`.

El siguiente ejemplo muestra un delegado que anima un rectángulo giratorio. Cuando se incluye en el grupo, la animación se pausa temporalmente:

Component {
    id: listViewDelegate
    Rectangle {
        width: 100
        height: 50

        ListView.onPooled: rotationAnimation.pause()
        ListView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

Tamaño variable del delegado y etiquetas de sección

Los tamaños variables de los delegados pueden provocar que se redimensionen y se omitan los elementos « ScrollBar » asociados. Esto se debe a que ListView estima el tamaño de su contenido a partir de los elementos asignados (normalmente solo los elementos visibles; se supone que el resto tiene un tamaño similar), y los tamaños variables de los delegados impiden una estimación precisa. Para reducir este efecto, se puede establecer cacheBuffer en valores más altos, lo que crea efectivamente más elementos y mejora la estimación del tamaño de los elementos no asignados, a costa de un mayor consumo de memoria. Sections tiene el mismo efecto, ya que adjunta y alarga la etiqueta de sección hasta el primer elemento dentro de la sección.

Evitar almacenar el estado en los delegados

Los delegados de ListView se instancian según sea necesario y pueden destruirse cuando quedan fuera de la vista. Para ilustrarlo, ejecuta el siguiente ejemplo:

ListView {
    anchors.fill: parent
    model: 3
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)

        required property int index
        property bool channelActivated

        onClicked: channelActivated = checked
    }
}

Al hacer clic en un elemento, se establece ` channelActivated ` en ` true`. Sin embargo, dado que los delegados pueden ser ` reused ` y destruidos, todo el estado se pierde cuando la vista se desplaza lo suficiente. Cuando el delegado vuelva a ser visible, tendrá su estado predeterminado, sin modificar (o, en el caso de un elemento que se haya reutilizado, el estado anterior de un elemento previo).

Para evitarlo, el estado debe almacenarse en el modelo:

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement {
            channelActivated: true
        }
        // ...
    }
    delegate: CheckDelegate {
        text: qsTr("Channel %1").arg(index + 1)
        checked: model.channelActivated

        required property int index
        required property var model

        onClicked: model.channelActivated = checked
    }
}

Ocultar delegados

Al establecer la propiedad ` visible ` de un delegado en ` false `, se ocultará ese elemento, pero el espacio que ocupaba en la vista permanecerá. Es posible establecer la propiedad ` height ` del elemento en ` 0 ` (para una `ListView` de tipo ` vertical `):

ListView {
    anchors.fill: parent
    model: ListModel {
        ListElement { hidden: false }
        ListElement { hidden: false }
        ListElement { hidden: false }
        // ...
    }
    delegate: ItemDelegate {
        text: qsTr("Item %1").arg(index)
        visible: !model.hidden
        height: visible ? implicitHeight : 0

        required property int index
        required property var model

        onClicked: model.hidden = true
    }
}

Ten en cuenta que el estado oculto se almacena en el modelo, siguiendo las recomendaciones de la sección Avoid Storing State in Delegates.

Sin embargo, si spacing es distinto de cero, habrá espacios irregulares entre los delegados.

Una opción mejor es filtrar el modelo para que los elementos que no deben estar visibles no sean cargados en absoluto por la vista. Esto se puede conseguir con ` QSortFilterProxyModel`.

Otra opción es aplicar « disable » al delegado en lugar de ocultarlo.

Véase también Modelos de datos QML, GridView, PathView y Qt Quick Ejemplos - Vistas.

Documentación de propiedades

add : Transition

Esta propiedad define la transición que se aplicará a los elementos que se añadan a la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    add: Transition {
        NumberAnimation { properties: "x,y"; from: 100; duration: 1000 }
    }
}

Cada vez que se añada un elemento a la vista anterior, dicho elemento se animará desde la posición (100,100) hasta su posición final x,y dentro de la vista, en el transcurso de un segundo. La transición solo se aplica a los nuevos elementos que se añaden a la vista; no se aplica a los elementos situados debajo que quedan desplazados por la incorporación de los nuevos elementos. Para animar los elementos desplazados, configura las propiedades ` displaced ` o ` addDisplaced `.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de ViewTransition.

Nota: Esta transición no se aplica a los elementos que se crean cuando la vista se rellena inicialmente, ni cuando cambia el model de la vista. (En esos casos, se aplica en su lugar la transición populate ). Además, esta transición no debe animar la altura del nuevo elemento; si se hace, provocará que cualquier elemento situado debajo del nuevo se coloque en una posición incorrecta. En su lugar, la altura se puede animar dentro del controlador onAdd del delegado.

Véase también addDisplaced, populate y ViewTransition.

addDisplaced : Transition

Esta propiedad define la transición que se aplicará a los elementos de la vista que queden desplazados al añadirse otros elementos a la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    addDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que se añade un elemento a la vista anterior, todos los elementos situados debajo del nuevo elemento se desplazan, lo que hace que se muevan hacia abajo (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos hacia sus nuevas posiciones x, y dentro de la vista se animará mediante una transición « NumberAnimation » durante un segundo, tal y como se ha especificado. Esta transición no se aplica al nuevo elemento que se ha añadido a la vista; para animar los elementos añadidos, configura la propiedad « add ».

Si un elemento es desplazado por varios tipos de operaciones al mismo tiempo, no queda definido si se aplicará la transición «addDisplaced», « moveDisplaced » o « removeDisplaced ». Además, si no es necesario especificar diferentes transiciones en función de si un elemento es desplazado por una operación de adición, desplazamiento o eliminación, considere la posibilidad de establecer la propiedad « displaced » en su lugar.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de « ViewTransition ».

Nota: Esta transición no se aplica a los elementos que se crean cuando la vista se rellena inicialmente, ni cuando cambia el model de la vista. En esos casos, se aplica en su lugar la transición populate.

Véase también displaced, add, populate y ViewTransition.

cacheBuffer : int

Esta propiedad determina si los delegados se conservan fuera del área visible de la vista.

Si este valor es mayor que cero, la vista puede mantener tantos delegados instanciados como quepan dentro del búfer especificado. Por ejemplo, si en una vista vertical el delegado tiene 20 píxeles de altura y la propiedad « cacheBuffer » está establecida en 40, entonces se pueden crear o retener hasta 2 delegados por encima y 2 delegados por debajo del área visible. Los delegados almacenados en el búfer se crean de forma asíncrona, lo que permite que la creación se produzca a lo largo de varios fotogramas y reduce la probabilidad de que se salten fotogramas. Para mejorar el rendimiento del dibujo, los delegados que se encuentran fuera del área visible no se dibujan.

El valor por defecto de esta propiedad depende de la plataforma, pero suele ser un valor mayor que cero. Se ignoran los valores negativos.

Ten en cuenta que `cacheBuffer` no es un búfer de píxeles: solo mantiene delegados instanciados adicionales.

Nota: Establecer esta propiedad no sustituye a la creación de delegados eficientes. Puede mejorar la fluidez del comportamiento de desplazamiento a costa de un mayor consumo de memoria. Cuantos menos objetos y enlaces haya en un delegado, más rápido se podrá desplazar una vista. Es importante tener en cuenta que configurar un `cacheBuffer` solo pospondrá los problemas causados por delegados de carga lenta; no es una solución para este escenario.

El `cacheBuffer` funciona al margen de cualquier margen de visualización especificado por ` displayMarginBeginning ` o ` displayMarginEnd`.

count : int [read-only]

Esta propiedad refleja el número de elementos del modelo de la clase « ListView », independientemente de si están visibles o instanciados como « Item » de un componente delegado.

currentIndex : int

currentItem : Item [read-only]

La propiedad ` currentIndex ` contiene el índice del elemento actual, y ` currentItem ` contiene el elemento actual. Si se establece ` currentIndex ` en -1, se borrará el resaltado y se establecerá ` currentItem ` en `null`.

Si highlightFollowsCurrentItem es true, al establecer cualquiera de estas propiedades se desplazará suavemente el ListView para que el elemento actual quede visible.

Ten en cuenta que la posición del elemento actual puede ser solo aproximada hasta que se haga visible en la vista.

Dado que ` currentItem ` debe funcionar con cualquier delegado, su tipo es ` Item`. Sin embargo, a menudo un ` ListView ` se utiliza con un único tipo de delegado. En ese caso, convertir ` currentItem ` al tipo del delegado puede facilitar el uso de herramientas y dar lugar a un código más eficiente:

component Message : Item {
    required property string sender
    required property string text
}
ListView {
    id: messageView
    delegate: Message {}
    model: messageModel
}
Button {
    text: "Reply to %1".arg((messageView.currentItem) as Message).sender
}

currentSection : string [read-only]

Esta propiedad contiene la sección que se encuentra actualmente al principio de la vista.

delegate : Component

El delegado proporciona una plantilla que define cada elemento instanciado por la vista. El índice se expone como una propiedad accesible de tipo « index ». Las propiedades del modelo también están disponibles en función del tipo de modelo de datos.

El número de objetos y enlaces en el delegado influye directamente en el rendimiento del desplazamiento rápido de la vista. Siempre que sea posible, coloca la funcionalidad que no sea necesaria para la visualización normal del delegado en un ` Loader `, que pueda cargar componentes adicionales cuando sea necesario.

El ` ListView ` distribuirá los elementos en función del tamaño del elemento raíz del delegado.

Se recomienda que el tamaño del delegado sea un número entero para evitar la alineación de los elementos a nivel de subpíxeles.

El « stacking order » predeterminado de las instancias de delegado es 1.

Nota: Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Están vinculados al ` contentItem` del ` ListView`, no a la propia vista. Nunca se debe almacenar el estado en un delegado.

Véase también Stacking Order in ListView.

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 a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias.
DelegateModel.Qt5ReadWritePermite a los delegados escribir en el modelo a través del objeto ` model ` y de las propiedades de contexto, pero no a través de 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».

displaced : Transition

Esta propiedad contiene la transición genérica que se aplicará a los elementos que hayan sido desplazados por cualquier operación del modelo que afecte a la vista.

Esto resulta muy práctico para especificar la transición genérica que se aplicará a cualquier elemento desplazado por una operación de añadir, mover o eliminar, sin tener que especificar las propiedades individuales addDisplaced, moveDisplaced y removeDisplaced. Por ejemplo, aquí hay una vista que especifica una transición de desplazamiento:

ListView {
    ...
    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cuando se añade, mueve o elimina cualquier elemento dentro de la vista anterior, los elementos situados debajo de él se desplazan, lo que hace que se desplacen hacia abajo (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos hacia sus nuevas posiciones x, y dentro de la vista se animará mediante una transición « NumberAnimation » durante un segundo, tal y como se ha especificado.

Si una vista especifica esta transición genérica de desplazamiento, así como una transición específica de tipo « addDisplaced », « moveDisplaced » o « removeDisplaced », se utilizará la transición más específica en lugar de la transición genérica de desplazamiento cuando se produzca la operación correspondiente, siempre que la transición más específica no se haya desactivado (estableciendo ` enabled ` en «false»). Si, efectivamente, se ha desactivado, se aplicará en su lugar la transición genérica de desplazamiento.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de ViewTransition.

Véase también addDisplaced, moveDisplaced, removeDisplaced y ViewTransition.

displayMarginBeginning : int [since QtQuick 2.3]

displayMarginEnd : int [since QtQuick 2.3]

Esta propiedad permite que los delegados se muestren fuera de la geometría de la vista.

Si este valor es distinto de cero, la vista creará delegados adicionales antes del inicio de la vista o después de su final. La vista creará tantos delegados como quepan en el tamaño en píxeles especificado.

Por ejemplo, si en una vista vertical el delegado tiene 20 píxeles de altura y tanto « displayMarginBeginning » como « displayMarginEnd » están establecidos en 40, se crearán y mostrarán 2 delegados por encima y 2 delegados por debajo.

El valor por defecto es 0.

Esta propiedad está pensada para permitir determinadas configuraciones de la interfaz de usuario, y no como una optimización del rendimiento. Si deseas crear delegados fuera de la geometría de la vista por motivos de rendimiento, probablemente te convenga utilizar la propiedad cacheBuffer en su lugar.

Estas propiedades se introdujeron en QtQuick 2.3.

effectiveLayoutDirection : enumeration [read-only]

Esta propiedad define la dirección de diseño efectiva de una lista orientada horizontalmente.

Al utilizar la propiedad asociada LayoutMirroring::enabled para diseños de configuración regional, la dirección visual de la lista horizontal se invertirá. Sin embargo, la propiedad layoutDirection permanecerá sin cambios.

Véase también « ListView::layoutDirection » y « LayoutMirroring ».

Esta propiedad contiene el componente que se utilizará como pie de página.

Se crea una instancia del componente de pie de página para cada vista. El pie de página se coloca al final de la vista, después de cualquier elemento. El valor predeterminado de « stacking order » del pie de página es « 1 ».

Véase también header, footerItem y Stacking Order in ListView.

footerItem : Item [read-only]

Aquí se aloja el elemento de pie de página creado a partir del componente footer.

Se crea una instancia del componente de pie de página para cada vista. El pie de página se coloca al final de la vista, después de cualquier otro elemento. El valor predeterminado de « stacking order » del pie de página es « 1 ».

Véase también footer, headerItem y Stacking Order in ListView.

footerPositioning : enumeration [since Qt 5.4]

Esta propiedad determina la posición del elemento ` footer item`.

ConstanteDescripción
ListView.InlineFooter(por defecto) El pie de página se sitúa al final del contenido y se desplaza junto con este, como un elemento cualquiera.
ListView.OverlayFooterEl pie de página se sitúa al final de la vista.
ListView.PullBackFooterEl pie de página se sitúa al final de la vista. El pie de página puede desplazarse hacia atrás al mover el contenido hacia atrás, y volver a su posición al mover el contenido hacia delante.

Nota: Esta propiedad no tiene ningún efecto sobre la « stacking order » del pie de página. Por ejemplo, si se desea que el pie de página se muestre por encima de los elementos « delegate » al utilizar « ListView.OverlayFooter », su valor Z debe establecerse en un valor superior al de los delegados. Para obtener más información, consulte Stacking Order in ListView.

Nota: Si footerPositioning no está establecido en ListView.InlineFooter, el usuario no podrá pulsar ni deslizar la lista desde el pie de página. En cualquier caso, el footer item puede contener elementos o controladores de eventos que proporcionen un manejo personalizado de las entradas del ratón o táctiles.

Esta propiedad se introdujo en Qt 5.4.

header : Component

Esta propiedad contiene el componente que se utilizará como encabezado.

Se crea una instancia del componente de cabecera para cada vista. La cabecera se coloca al principio de la vista, antes de cualquier elemento. El valor predeterminado de « stacking order » de la cabecera es « 1 ».

Véase también footer, headerItem y Stacking Order in ListView.

headerItem : Item [read-only]

Aquí se almacena el elemento de encabezado creado a partir del componente header.

Se crea una instancia del componente de cabecera para cada vista. La cabecera se coloca al principio de la vista, antes que cualquier otro elemento. El stacking order predeterminado de la cabecera es 1.

Véase también header, footerItem y Stacking Order in ListView.

headerPositioning : enumeration [since Qt 5.4]

Esta propiedad determina la posición del elemento ` header item`.

ConstanteDescripción
ListView.InlineHeader(por defecto) El encabezado se sitúa al principio del contenido y se desplaza junto con este, como un elemento cualquiera.
ListView.OverlayHeaderEl encabezado se sitúa al principio de la vista.
ListView.PullBackHeaderEl encabezado se sitúa al principio de la vista. El encabezado puede desplazarse hacia delante al mover el contenido hacia delante, y hacia atrás al mover el contenido hacia atrás.

Nota: Esta propiedad no afecta a la « stacking order » del encabezado. Por ejemplo, si se desea que el encabezado se muestre por encima de los elementos « delegate » al utilizar « ListView.OverlayHeader », su valor Z debe establecerse en un valor superior al de los delegados. Para obtener más información, consulte Stacking Order in ListView.

Nota: Si headerPositioning no está establecido en ListView.InlineHeader, el usuario no podrá pulsar y deslizar la lista desde el encabezado. En cualquier caso, header item puede contener elementos o controladores de eventos que proporcionen un manejo personalizado de las entradas del ratón o táctiles.

Esta propiedad se introdujo en Qt 5.4.

highlight : Component

Esta propiedad contiene el componente que se utilizará como resaltado.

Se crea una instancia del componente de resaltado para cada lista. La lista gestiona la geometría de la instancia del componente resultante de modo que permanezca junto al elemento actual, a menos que la propiedad « highlightFollowsCurrentItem » tenga el valor «false». El valor predeterminado de « stacking order » del elemento resaltado es « 0 ».

Véase también highlightItem, highlightFollowsCurrentItem, Ejemplo de resaltado en ListView y Stacking Order in ListView.

highlightFollowsCurrentItem : bool

Esta propiedad indica si la vista gestiona el resaltado.

Si esta propiedad es «true» (el valor por defecto), el resaltado se desplaza suavemente para seguir al elemento actual. De lo contrario, la vista no mueve el resaltado, y cualquier movimiento debe ser implementado por el propio resaltado.

A continuación se muestra un resaltado cuyo movimiento viene definido por un elemento « SpringAnimation »:

Component {
    id: highlight
    Rectangle {
        width: 180; height: 40
        color: "lightsteelblue"; radius: 5
        y: list.currentItem.y
        Behavior on y {
            SpringAnimation {
                spring: 3
                damping: 0.2
            }
        }
    }
}

ListView {
    id: list
    width: 180; height: 200
    model: ContactModel {}
    delegate: Text { text: name }

    highlight: highlight
    highlightFollowsCurrentItem: false
    focus: true
}

Ten en cuenta que la animación del resaltado también afecta a la forma en que se desplaza la vista. Esto se debe a que la vista se mueve para mantener el resaltado dentro del rango de resaltado preferido (o ventana de visualización visible).

Véase también highlight y highlightMoveVelocity.

highlightItem : Item [read-only]

Aquí se almacena el elemento destacado creado a partir del componente « highlight ».

El « highlightItem » es gestionado por la vista, a menos que se establezca « highlightFollowsCurrentItem » en «false». El « stacking order » predeterminado del elemento destacado es « 0 ».

Véase también « highlight », « highlightFollowsCurrentItem » y « Stacking Order in ListView ».

highlightMoveDuration : int

highlightMoveVelocity : real

highlightResizeDuration : int

highlightResizeVelocity : real

Estas propiedades controlan la velocidad de las animaciones de desplazamiento y cambio de tamaño del delegado de resaltado.

highlightFollowsCurrentItem Debe ser «true» para que estas propiedades surtan efecto.

El valor por defecto de las propiedades de velocidad es de 400 píxeles/segundo. El valor por defecto de las propiedades de duración es -1, es decir, el resaltado tardará el tiempo que sea necesario para desplazarse a la velocidad establecida.

Estas propiedades tienen las mismas características que un « SmoothedAnimation »: si se establecen tanto la velocidad como la duración, la animación utilizará el valor que proporcione la duración más corta.

Las propiedades de velocidad de desplazamiento y duración se utilizan para controlar el movimiento debido a cambios de índice; por ejemplo, cuando se llama a ` incrementCurrentIndex()`. Cuando el usuario desliza rápidamente un ` ListView`, se utiliza la velocidad de ese deslizamiento para controlar el movimiento.

Para establecer solo una propiedad, la otra se puede fijar en ` -1`. Por ejemplo, si solo quieres animar la duración y no la velocidad, utiliza el siguiente código:

highlightMoveDuration: 1000
highlightMoveVelocity: -1

Véase también highlightFollowsCurrentItem.

highlightRangeMode : enumeration

preferredHighlightBegin : real

preferredHighlightEnd : real

Estas propiedades definen el rango preferido de la selección (para el elemento actual) dentro de la vista. El valor de « preferredHighlightBegin » debe ser menor que el valor de « preferredHighlightEnd ».

Estas propiedades afectan a la posición del elemento actual cuando se desplaza la lista. Por ejemplo, si se desea que el elemento seleccionado actualmente permanezca en el centro de la lista al desplazar la vista, establezca los valores de « preferredHighlightBegin » y « preferredHighlightEnd » en las coordenadas superior e inferior de la posición en la que se encontraría el elemento central. Si se modifica el índice del elemento actual ( currentItem ) mediante programación, la lista se desplazará automáticamente para que el elemento actual quede en el centro de la vista. Además, el comportamiento del índice del elemento actual se producirá independientemente de si existe o no un resaltado.

Los valores válidos para ` highlightRangeMode ` son:

ConstanteDescripción
ListView.ApplyRangela vista intenta mantener el resaltado dentro del rango. Sin embargo, el resaltado puede salirse del rango al llegar al final de la lista o debido a la interacción con el ratón.
ListView.StrictlyEnforceRangeEl elemento resaltado nunca sale del rango. El elemento actual cambia si una acción del teclado o del ratón provocara que el elemento resaltado saliera del rango.
ListView.NoHighlightRangeEste es el valor por defecto.

keyNavigationEnabled : bool

Esta propiedad indica si la navegación por teclas de la lista está activada.

Si el valor es « true », el usuario puede navegar por la vista con el teclado. Resulta útil para aplicaciones que necesitan habilitar o deshabilitar de forma selectiva la interacción con el ratón y el teclado.

De forma predeterminada, el valor de esta propiedad está vinculado a « interactive » para garantizar la compatibilidad de comportamiento con las aplicaciones existentes. Cuando se establece explícitamente, dejará de estar vinculada a la propiedad «interactive».

Véase también « interactive ».

keyNavigationWraps : bool

Esta propiedad indica si la lista realiza un salto al principio o al final al navegar con las teclas.

Si el valor es «true», la navegación mediante teclas que llevaría la selección del elemento actual más allá del final de la lista se reinicia y desplaza la selección al principio de la lista, y viceversa.

Por defecto, la navegación mediante teclas no se reenvuelve.

layoutDirection : enumeration

Esta propiedad define la dirección de disposición de una lista orientada horizontalmente.

Valores posibles:

ConstanteDescripción
Qt.LeftToRight(por defecto) Los elementos se dispondrán de izquierda a derecha.
Qt.RightToLeftLos elementos se dispondrán de derecha a izquierda.

La configuración de esta propiedad no tiene ningún efecto si la propiedad « orientation » tiene el valor Qt.Vertical.

Véase también « ListView::effectiveLayoutDirection » y « ListView::verticalLayoutDirection ».

model : model

Esta propiedad contiene el modelo que proporciona los datos para la lista.

El modelo proporciona el conjunto de datos que se utiliza para crear los elementos de la vista. Los modelos se pueden crear directamente en QML utilizando ListModel, ObjectModel, o bien pueden ser proporcionados por clases de modelo en C++. Si se utiliza una clase de modelo en C++, debe ser una subclase de QAbstractItemModel o una lista simple.

Véase también Modelos de datos.

move : Transition

Esta propiedad contiene la transición que se aplicará a los elementos de la vista que se estén moviendo debido a una operación de desplazamiento en el « model » de la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    move: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que el « model » realice una operación de desplazamiento para mover un conjunto concreto de índices, los elementos correspondientes de la vista se animarán hasta alcanzar sus nuevas posiciones en la vista en el plazo de un segundo. La transición solo se aplica a los elementos que son objeto de la operación de desplazamiento en el modelo; no se aplica a los elementos situados debajo de ellos que se ven desplazados por dicha operación. Para animar los elementos desplazados, configura las propiedades « displaced » o « moveDisplaced ».

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también moveDisplaced y ViewTransition.

moveDisplaced : Transition

Esta propiedad define la transición que se aplicará a los elementos que se desplacen como consecuencia de una operación de movimiento en el « model » de la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    moveDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que el « model » realiza una operación de desplazamiento para mover un conjunto concreto de índices, los elementos situados entre los índices de origen y destino de dicha operación se desplazan, lo que hace que se muevan hacia arriba o hacia abajo (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos hacia sus nuevas posiciones x, y dentro de la vista se animará mediante una transición « NumberAnimation » durante un segundo, tal y como se ha especificado. Esta transición no se aplica a los elementos que son los sujetos reales de la operación de desplazamiento; para animar los elementos desplazados, configura la propiedad « move ».

Si un elemento es desplazado por varios tipos de operaciones al mismo tiempo, no queda definido si se aplicará la transición « addDisplaced », «moveDisplaced» o « removeDisplaced ». Además, si no es necesario especificar diferentes transiciones en función de si un elemento es desplazado por una operación de adición, desplazamiento o eliminación, considere la posibilidad de establecer la propiedad « displaced » en su lugar.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de ViewTransition.

Véase también displaced, move y ViewTransition.

orientation : enumeration

Esta propiedad determina la orientación de la lista.

Valores posibles:

ConstanteDescripción
ListView.HorizontalLos elementos se disponen horizontalmente
Tres tarjetas de contacto dispuestas horizontalmente: Bill Smith, John Brown, Sam Wise
ListView.Vertical(por defecto) Los elementos se disponen verticalmente
Tres tarjetas de contacto apiladas verticalmente: Bill Smith, John Brown, Sam Wise

Véase también Flickable Direction.

populate : Transition

Esta propiedad determina la transición que se aplicará a los elementos creados inicialmente para una vista.

Se aplica a todos los elementos que se crean cuando:

  • Se crea la vista por primera vez
  • El « model » de la vista cambia de tal forma que los delegados visibles se sustituyen por completo
  • El ` model ` de la vista es ` reset`, si el modelo es una subclase de ` QAbstractItemModel `

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    populate: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cuando se inicializa la vista, esta creará todos los elementos necesarios para la vista y, a continuación, los animará hasta sus posiciones correctas dentro de la vista en el transcurso de un segundo.

Sin embargo, al desplazarse por la vista posteriormente, la transición «populate» no se ejecuta, aunque los delegados se instancien a medida que se hacen visibles. Cuando el modelo cambia de tal forma que se hacen visibles nuevos delegados, la transición « add » es la que se ejecuta. Por lo tanto, no debes depender de la transición « populate » para inicializar propiedades en el delegado, ya que no se aplica a todos los delegados. Si tu animación establece el valor to de una propiedad, dicha propiedad debería tener inicialmente el valor to, y la animación debería establecer el valor from en caso de que se anime:

ListView {
    ...
    delegate: Rectangle {
        opacity: 1 // not necessary because it's the default
    }
    populate: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
    }
}

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulta la documentación de ViewTransition.

Véase también add y ViewTransition.

remove : Transition

Esta propiedad define la transición que se aplicará a los elementos que se eliminen de la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    remove: Transition {
        ParallelAnimation {
            NumberAnimation { property: "opacity"; to: 0; duration: 1000 }
            NumberAnimation { properties: "x,y"; to: 100; duration: 1000 }
        }
    }
}

Cada vez que se elimine un elemento de la vista anterior, dicho elemento se desplazará de forma animada hasta la posición (100,100) en el transcurso de un segundo y, al mismo tiempo, su opacidad pasará a ser 0. La transición solo se aplica a los elementos que se eliminan de la vista; no se aplica a los elementos situados debajo de ellos que se desplazan como consecuencia de la eliminación de dichos elementos. Para animar los elementos desplazados, configura las propiedades « displaced » o « removeDisplaced ».

Ten en cuenta que, en el momento en que se aplica la transición, el elemento ya se ha eliminado del modelo; cualquier referencia a los datos del modelo correspondientes al índice eliminado ya no será válida.

Además, si se ha establecido la propiedad asociada ` delayRemove ` para un elemento delegado, la transición de eliminación no se aplicará hasta que ` delayRemove ` vuelva a ser `false`.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de « ViewTransition ».

Véase también « removeDisplaced » y « ViewTransition ».

removeDisplaced : Transition

Esta propiedad especifica la transición que se aplicará a los elementos de la vista que queden desplazados al eliminarse otros elementos de la vista.

Por ejemplo, aquí hay una vista que especifica dicha transición:

ListView {
    ...
    removeDisplaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 1000 }
    }
}

Cada vez que se elimina un elemento de la vista anterior, todos los elementos situados debajo de él se desplazan, lo que hace que se muevan hacia arriba (o hacia los lados, si están orientados horizontalmente) dentro de la vista. A medida que se produce este desplazamiento, el movimiento de los elementos hacia sus nuevas posiciones x, y dentro de la vista se animará mediante un « NumberAnimation » durante un segundo, tal y como se ha especificado. Esta transición no se aplica al elemento que se ha eliminado realmente de la vista; para animar los elementos eliminados, configura la propiedad « remove ».

Si un elemento se desplaza debido a varios tipos de operaciones al mismo tiempo, no está definido si se aplicará la transición « addDisplaced », « moveDisplaced » o «removeDisplaced». Además, si no es necesario especificar diferentes transiciones en función de si un elemento se desplaza por una operación de añadir, mover o eliminar, considere la posibilidad de establecer la propiedad « displaced » en su lugar.

Para obtener más detalles y ejemplos sobre cómo utilizar las transiciones de vista, consulte la documentación de ViewTransition.

Véase también displaced, remove y ViewTransition.

reuseItems : bool

Esta propiedad te permite reutilizar los elementos instanciados a partir de la clase ` delegate`. Si se establece en ` false`, se eliminarán todos los elementos que se encuentren actualmente en el pool.

Esta propiedad tiene el valor « false » de forma predeterminada.

Véase también Reusing items, pooled() y reused().

section group

section.criteria : enumeration

section.delegate : Component

section.labelPositioning : enumeration

section.property : string

Estas propiedades determinan la expresión que se va a evaluar y el aspecto de las etiquetas de las secciones.

section.property Contiene el nombre de la propiedad en la que se basa cada sección.

section.criteria contiene los criterios para formar cada sección basándose en section.property. Este valor puede ser uno de los siguientes:

ConstanteDescripción
ViewSection.FullString(por defecto) las secciones se crean basándose en el valor de section.property.
ViewSection.FirstCharacterLas secciones se crean en función del primer carácter del valor de « section.property » (por ejemplo, secciones «A», «B», «C»... para una agenda de direcciones).

Se utiliza una comparación que no distingue entre mayúsculas y minúsculas a la hora de determinar los límites de las secciones.

section.delegate Contiene el componente delegado de cada sección. El ` stacking order ` predeterminado de las instancias del delegado de sección es ` 2`. Si se declara en él una propiedad ` required ` denominada «section», dicha propiedad contendrá el título de la sección.

section.labelPositioning Determina si las etiquetas de la sección actual y/o la siguiente se ajustan al inicio o al final de la vista, y si las etiquetas se muestran en línea. Este valor puede ser una combinación de:

ConstanteDescripción
ViewSection.InlineLabels(por defecto) las etiquetas de sección se muestran en línea entre los delegados de elemento que separan las secciones.
ViewSection.CurrentLabelAtStartLa etiqueta de la sección actual se mantiene al principio de la vista a medida que se desplaza.
ViewSection.NextLabelAtEndLa etiqueta de la siguiente sección (más allá de todas las secciones visibles) se mantiene al final de la vista a medida que esta se desplaza.

Nota: Al habilitar la función « ViewSection.NextLabelAtEnd » (Siguiente sección), la vista debe buscar por adelantado la siguiente sección, lo que tiene implicaciones en el rendimiento, especialmente en modelos más lentos.

Cada elemento de la lista tiene asociadas unas propiedades denominadas « ListView.section », « ListView.previousSection » y « ListView.nextSection ».

Por ejemplo, aquí hay un « ListView » que muestra una lista de animales, dividida en secciones. Cada elemento de la « ListView » se coloca en una sección diferente en función de la propiedad «size» del elemento del modelo. El componente delegado « sectionHeading » proporciona la barra azul claro que marca el inicio de cada sección.

    // The delegate for each section header
    Component {
        id: sectionHeading
        Rectangle {
            width: ListView.view.width
            height: childrenRect.height
            color: "lightsteelblue"

            required property string section

            Text {
                text: parent.section
                font.bold: true
                font.pixelSize: 20
            }
        }
    }

    ListView {
        id: view
        anchors.top: parent.top
        anchors.bottom: buttonBar.top
        width: parent.width
        model: animalsModel
        delegate: Text {
            required property string name

            text: name
            font.pixelSize: 18
        }

        section.property: "size"
        section.criteria: ViewSection.FullString
        section.delegate: sectionHeading
    }

ListView con elementos agrupados en secciones con barras de encabezado de color azul claro

Nota: Añadir secciones a un ListView no reordena automáticamente los elementos de la lista según los criterios de las secciones. Si el modelo no está ordenado por secciones, es posible que las secciones creadas no sean únicas; cada límite entre secciones diferentes dará lugar a la creación de un encabezado de sección, incluso si esa sección ya existe en otro lugar.

Véanse también los ejemplos de ListView y Stacking Order in ListView.

snapMode : enumeration

Esta propiedad determina cómo se estabilizará el desplazamiento de la vista tras un arrastre o un movimiento rápido. Los valores posibles son:

ConstanteDescripción
ListView.NoSnap(por defecto) la vista se detiene en cualquier punto dentro del área visible.
ListView.SnapToItemLa vista se detiene con un elemento alineado con el inicio de la vista.
ListView.SnapOneItemLa vista se estabiliza a una distancia máxima de un elemento del primer elemento visible en el momento en que se suelta el botón del ratón. Este modo resulta especialmente útil para desplazarse una página cada vez. Cuando SnapOneItem está habilitado, la vista « ListView » mostrará una mayor afinidad con los elementos adyacentes cuando se produzca un desplazamiento. Por ejemplo, un arrastre breve que, con SnapToItem, se ajuste al elemento actual, podría ajustarse a un elemento adyacente con SnapOneItem.

snapMode no afecta a la propiedad « currentIndex ». Para actualizar la propiedad « currentIndex » a medida que se desplaza la lista, establezca « highlightRangeMode » en « ListView.StrictlyEnforceRange ».

Véase también highlightRangeMode.

spacing : real

Esta propiedad determina el espaciado entre los elementos.

El valor por defecto es 0.

verticalLayoutDirection : enumeration

Esta propiedad determina la dirección de disposición de una lista orientada verticalmente.

Valores posibles:

ConstanteDescripción
ListView.TopToBottom(predeterminado) Los elementos se disponen desde la parte superior de la vista hasta la parte inferior de la misma.
ListView.BottomToTopLos elementos se disponen desde la parte inferior de la vista hacia la parte superior de la misma.

La configuración de esta propiedad no tiene ningún efecto si la propiedad « orientation » es Qt.Horizontal.

Véase también « ListView::layoutDirection ».

Documentación de la propiedad adjunta

ListView.delayRemove : bool [attached]

Esta propiedad adjunta indica si el delegado puede ser destruido. Se adjunta a cada instancia del delegado. El valor por defecto es «false».

A veces es necesario retrasar la eliminación de un elemento hasta que finalice una animación. El delegado de ejemplo que se muestra a continuación garantiza que la animación finalice antes de que el elemento se elimine de la lista.

Component {
    id: delegate
    Item {
        SequentialAnimation {
            id: removeAnimation
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: true }
            NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
            PropertyAction { target: wrapper; property: "ListView.delayRemove"; value: false }
        }
        ListView.onRemove: removeAnimation.start()
    }
}

Si se ha especificado una transición « remove », no se aplicará hasta que «delayRemove» devuelva « false ».

ListView.isCurrentItem : bool [read-only attached]

Esta propiedad adjunta devuelve «true» si este delegado es el elemento actual; en caso contrario, devuelve «false».

Está asociada a cada instancia del delegado.

Esta propiedad se puede utilizar para ajustar la apariencia del elemento actual, por ejemplo:

ListView {
    width: 180; height: 200

    Component {
        id: contactsDelegate
        Rectangle {
            id: wrapper
            width: 180
            height: contactInfo.height
            color: ListView.isCurrentItem ? "black" : "red"
            Text {
                id: contactInfo
                text: name + ": " + number
                color: wrapper.ListView.isCurrentItem ? "red" : "black"
            }
        }
    }

    model: ContactModel {}
    delegate: contactsDelegate
    focus: true
}

ListView.nextSection : string [read-only attached]

Esta propiedad asociada contiene la sección del siguiente elemento.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades « section ».

ListView.previousSection : string [read-only attached]

Esta propiedad asociada contiene la sección del elemento anterior.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades « section ».

ListView.section : string [read-only attached]

Esta propiedad asociada contiene la sección de este elemento.

Se adjunta a cada instancia del delegado.

La sección se evalúa utilizando las propiedades section.

ListView.view : ListView [read-only attached]

Esta propiedad asociada contiene la vista que gestiona esta instancia del delegado.

Está asociada a cada instancia del delegado, así como a los delegados de encabezado, pie de página, sección y resaltado.

Documentación sobre señales asociadas

[attached] add()

Esta señal adjunta se emite inmediatamente después de que se añada un elemento a la vista.

Si se especifica una transición de adición, esta se aplica inmediatamente después de que se gestione esta señal.

Nota: El controlador correspondiente es onAdd.

[attached] pooled()

Esta señal se emite después de que se haya añadido un elemento al conjunto de reutilización. Puedes utilizarla para pausar temporizadores o animaciones en curso dentro del elemento, o para liberar recursos que no se puedan reutilizar.

Esta señal se emite únicamente si la propiedad « reuseItems » tiene el valor « true ».

Nota: El controlador correspondiente es onPooled.

Véase también Reusing items, reuseItems y reused().

[attached] remove()

Esta señal adjunta se emite inmediatamente antes de que un elemento se elimine de la vista.

Si se ha especificado una transición de eliminación, esta se aplica tras la gestión de esta señal, siempre que delayRemove sea falso.

Nota: El controlador correspondiente es ` onRemove`.

[attached] reused()

Esta señal se emite después de que un elemento se haya reutilizado. En ese momento, el elemento se ha retirado del grupo y se ha colocado dentro de la vista de contenido, y se han actualizado las propiedades del modelo, como « index » y « row ».

Las demás propiedades que no proporciona el modelo no cambian cuando se reutiliza un elemento. Se debe evitar almacenar cualquier estado dentro de un delegado, pero, si se hace, hay que restablecer manualmente ese estado al recibir esta señal.

Esta señal se emite cuando se reutiliza el elemento, y no la primera vez que se crea.

Esta señal se emite únicamente si la propiedad reuseItems tiene el valor true.

Nota: El controlador correspondiente es onReused.

Véase también Reusing items, reuseItems y pooled().

Documentación del método

void decrementCurrentIndex()

Disminuye el índice actual. El índice actual se reiniciará si ` keyNavigationWraps ` es verdadero y se encuentra actualmente al principio. Este método no tiene ningún efecto si ` count ` es cero.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.

void forceLayout()

La respuesta a los cambios en el modelo suele procesarse por lotes, de modo que solo se produce una vez por fotograma. Esto significa que, dentro de los bloques de script, es posible que el modelo subyacente haya cambiado, pero que el « ListView » aún no se haya actualizado.

Este método obliga a la función « ListView » a responder inmediatamente a cualquier cambio pendiente en el modelo.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado su ejecución.

void incrementCurrentIndex()

Aumenta el índice actual. El índice actual se reiniciará si ` keyNavigationWraps ` es verdadero y se encuentra actualmente al final. Este método no tiene ningún efecto si ` count ` es cero.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.

int indexAt(real x, real y)

Devuelve el índice del elemento visible que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, o si el elemento no está visible, se devuelve -1.

Si el elemento se encuentra fuera del área visible, se devuelve -1, independientemente de si existirá un elemento en ese punto cuando se desplace la vista hasta él.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.

Item itemAt(real x, real y)

Devuelve el elemento visible que contiene el punto x, y en coordenadas de contenido. Si no hay ningún elemento en el punto especificado, o si el elemento no está visible, se devuelve null.

Si el elemento se encuentra fuera del área visible, se devuelve `null`, independientemente de si existirá un elemento en ese punto cuando se desplace la pantalla hasta que quede visible.

Nota: los métodos solo deben invocarse una vez que el componente se haya cargado por completo.

Item itemAtIndex(int index)

Devuelve el elemento correspondiente a index. Si no existe ningún elemento para ese índice —por ejemplo, porque aún no se ha creado o porque se ha desplazado fuera del área visible y se ha eliminado de la caché—, se devuelve null.

Nota: este método solo debe invocarse una vez que el componente haya finalizado. Tampoco debe almacenarse el valor devuelto, ya que puede pasar a ser `null` tan pronto como el control salga del ámbito de la llamada, si la vista libera ese elemento.

void positionViewAtBeginning()

void positionViewAtEnd()

Sitúa la vista al principio o al final, teniendo en cuenta cualquier encabezado o pie de página.

No se recomienda utilizar « contentX » o « contentY » para situar la vista en un índice concreto. Esto no es fiable, ya que eliminar elementos del principio de la lista no provoca que se reubiquen todos los demás elementos, y porque el inicio real de la vista puede variar en función del tamaño de los delegados.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado. Para posicionar la vista al inicio, este método debe ser invocado por `Component.onCompleted`. Por ejemplo, para posicionar la vista al final al inicio:

Component.onCompleted: positionViewAtEnd()

void positionViewAtIndex(int index, PositionMode mode)

Coloca la vista de tal forma que el « index » quede en la posición especificada por « mode »:

ConstanteDescripción
ListView.Beginningelemento de posición en la parte superior (o a la izquierda, en orientación horizontal) de la vista.
ListView.CenterElemento de posición en el centro de la vista.
ListView.EndColoca el elemento en la parte inferior (o a la derecha, en orientación horizontal) de la vista.
ListView.Visiblesi alguna parte del elemento está visible, no se realiza ninguna acción; de lo contrario, se muestra el elemento en la vista.
ListView.ContainAsegura que todo el elemento quede visible. Si el elemento es más grande que la vista, se coloca en la parte superior (o a la izquierda, en orientación horizontal) de la vista.
ListView.SnapPositionColocar el elemento en preferredHighlightBegin. Este modo solo es válido si highlightRangeMode es StrictlyEnforceRange o si el ajuste está habilitado mediante snapMode.

Si al colocar la vista en index se mostrara un espacio vacío al principio o al final de la vista, esta se colocará en el límite.

No se recomienda utilizar contentX o contentY para situar la vista en un índice concreto. Esto no es fiable, ya que eliminar elementos del principio de la lista no provoca que se reubiquen todos los demás elementos, y porque el inicio real de la vista puede variar en función del tamaño de los delegados. La forma correcta de traer un elemento a la vista es mediante positionViewAtIndex.

Nota: los métodos solo deben invocarse una vez que el componente haya finalizado. Para situar la vista al inicio, este método debe invocarse mediante `Component.onCompleted`. Por ejemplo, para situar la vista al final:

Component.onCompleted: positionViewAtIndex(count - 1, ListView.Beginning)

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