ListView QML Type
Ofrece una vista en forma de lista de los elementos proporcionados por un modelo. Más...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- add : Transition
- addDisplaced : Transition
- cacheBuffer : int
- count : int
- currentIndex : int
- currentItem : Item
- currentSection : string
- delegate : Component
- delegateModelAccess : enumeration
(since 6.10) - displaced : Transition
- displayMarginBeginning : int
(since QtQuick 2.3) - displayMarginEnd : int
(since QtQuick 2.3) - effectiveLayoutDirection : enumeration
- footer : Component
- footerItem : Item
- footerPositioning : enumeration
(since Qt 5.4) - header : Component
- headerItem : Item
- headerPositioning : enumeration
(since Qt 5.4) - highlight : Component
- highlightFollowsCurrentItem : bool
- highlightItem : Item
- highlightMoveDuration : int
- highlightMoveVelocity : real
- highlightRangeMode : enumeration
- highlightResizeDuration : int
- highlightResizeVelocity : real
- keyNavigationEnabled : bool
- keyNavigationWraps : bool
- layoutDirection : enumeration
- model : model
- move : Transition
- moveDisplaced : Transition
- orientation : enumeration
- populate : Transition
- preferredHighlightBegin : real
- preferredHighlightEnd : real
- remove : Transition
- removeDisplaced : Transition
- reuseItems : bool
- section
- section.criteria : enumeration
- section.delegate : Component
- section.labelPositioning : enumeration
- section.property : string
- snapMode : enumeration
- spacing : real
- verticalLayoutDirection : enumeration
Propiedades adjuntas
- delayRemove : bool
- isCurrentItem : bool
- nextSection : string
- previousSection : string
- section : string
- view : ListView
Señales adjuntas
Métodos
- void decrementCurrentIndex()
- void forceLayout()
- void incrementCurrentIndex()
- int indexAt(real x, real y)
- Item itemAt(real x, real y)
- Item itemAtIndex(int index)
- void positionViewAtBeginning()
- void positionViewAtEnd()
- void positionViewAtIndex(int index, PositionMode mode)
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
}
}
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
}
}
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
| De abajo hacia arriba
|
| ListViews con orientación Qt.Horizontal | |
| De izquierda a derecha
| 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:
| Propiedad | Valor Z predeterminado |
|---|---|
| delegate | 1 |
| footer | 1 |
| header | 1 |
| highlight | 0 |
| section.delegate | 2 |
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.
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.
| Constante | Descripción |
|---|---|
DelegateModel.ReadOnly | Impide que los delegados escriban en el modelo a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias. |
DelegateModel.ReadWrite | Permite a los delegados escribir en el modelo a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias. |
DelegateModel.Qt5ReadWrite | Permite 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.
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 ».
footer : Component
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`.
| Constante | Descripció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.OverlayFooter | El pie de página se sitúa al final de la vista. |
ListView.PullBackFooter | El 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 « Nota: Si |
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`.
| Constante | Descripció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.OverlayHeader | El encabezado se sitúa al principio de la vista. |
ListView.PullBackHeader | El 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 « Nota: Si |
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: -1Véase también highlightFollowsCurrentItem.
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:
| Constante | Descripción |
|---|---|
ListView.ApplyRange | la 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.StrictlyEnforceRange | El 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.NoHighlightRange | Este 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:
| Constante | Descripción |
|---|---|
Qt.LeftToRight | (por defecto) Los elementos se dispondrán de izquierda a derecha. |
Qt.RightToLeft | Los 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:
| Constante | Descripción |
|---|---|
ListView.Horizontal | Los elementos se disponen horizontalmente ![]() |
ListView.Vertical | (por defecto) Los elementos se disponen verticalmente ![]() |
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:
| Constante | Descripción |
|---|---|
ViewSection.FullString | (por defecto) las secciones se crean basándose en el valor de section.property. |
ViewSection.FirstCharacter | Las 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:
| Constante | Descripció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.CurrentLabelAtStart | La etiqueta de la sección actual se mantiene al principio de la vista a medida que se desplaza. |
ViewSection.NextLabelAtEnd | La 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 « |
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
}
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:
| Constante | Descripción |
|---|---|
ListView.NoSnap | (por defecto) la vista se detiene en cualquier punto dentro del área visible. |
ListView.SnapToItem | La vista se detiene con un elemento alineado con el inicio de la vista. |
ListView.SnapOneItem | La 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:
| Constante | Descripción |
|---|---|
ListView.TopToBottom | (predeterminado) Los elementos se disponen desde la parte superior de la vista hasta la parte inferior de la misma. |
ListView.BottomToTop | Los 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.
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 »:
| Constante | Descripción |
|---|---|
ListView.Beginning | elemento de posición en la parte superior (o a la izquierda, en orientación horizontal) de la vista. |
ListView.Center | Elemento de posición en el centro de la vista. |
ListView.End | Coloca el elemento en la parte inferior (o a la derecha, en orientación horizontal) de la vista. |
ListView.Visible | si alguna parte del elemento está visible, no se realiza ninguna acción; de lo contrario, se muestra el elemento en la vista. |
ListView.Contain | Asegura 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.SnapPosition | Colocar 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.




