GridView QML Type
Para definir una vista en cuadrícula de los elementos proporcionados por un modelo. Más información...
| Import Statement: | import QtQuick |
| Inherits: |
Propiedades
- add : Transition
- addDisplaced : Transition
- cacheBuffer : int
- cellHeight : real
- cellWidth : real
- count : int
- currentIndex : int
- currentItem : Item
- delegate : Component
- delegateModelAccess : enumeration
(since 6.10) - displaced : Transition
- displayMarginBeginning : int
(since QtQuick 2.3) - displayMarginEnd : int
(since QtQuick 2.3) - effectiveLayoutDirection : enumeration
- flow : enumeration
- footer : Component
- footerItem : Item
- header : Component
- headerItem : Item
- highlight : Component
- highlightFollowsCurrentItem : bool
- highlightItem : Item
- highlightMoveDuration : int
- highlightRangeMode : enumeration
- keyNavigationEnabled : bool
- keyNavigationWraps : bool
- layoutDirection : enumeration
- model : model
- move : Transition
- moveDisplaced : Transition
- populate : Transition
- preferredHighlightBegin : real
- preferredHighlightEnd : real
- remove : Transition
- removeDisplaced : Transition
- reuseItems : bool
- snapMode : enumeration
- verticalLayoutDirection : enumeration
Propiedades adjuntas
- delayRemove : bool
- isCurrentItem : bool
- view : GridView
Señales adjuntas
Métodos
- void forceLayout()
- int indexAt(real x, real y)
- Item itemAt(real x, real y)
- Item itemAtIndex(int index)
- void moveCurrentIndexDown()
- void moveCurrentIndexLeft()
- void moveCurrentIndexRight()
- void moveCurrentIndexUp()
- void positionViewAtBeginning()
- void positionViewAtEnd()
- void positionViewAtIndex(int index, PositionMode mode)
Descripción detallada
Un GridView 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 « QAbstractListModel ».
Un GridView 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 GridView se disponen horizontal o verticalmente. Las vistas de cuadrícula son inherentemente desplazables, ya que `GridView` hereda de ` Flickable`.
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: "Jim Williams"
portrait: "pics/portrait.png"
}
ListElement {
name: "John Brown"
portrait: "pics/portrait.png"
}
ListElement {
name: "Bill Smyth"
portrait: "pics/portrait.png"
}
ListElement {
name: "Sam Wise"
portrait: "pics/portrait.png"
}
}
Se puede hacer referencia a este modelo como « ContactModel » en otros archivos QML. Consulta «Módulos QML» para obtener más información sobre cómo crear componentes reutilizables como este.
Otro componente puede mostrar los datos de este modelo en un GridView, como en el siguiente ejemplo, que crea un componente « ContactModel » como modelo y un « Column » (que contiene los elementos « Image » y « Text ») como delegado.
import QtQuick
GridView {
width: 300; height: 200
model: ContactModel {}
delegate: Column {
Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
}
}
La vista creará un nuevo delegado para cada elemento del modelo. Tenga en cuenta que el delegado puede acceder directamente a los datos de « name » y « portrait » del modelo.
A continuación se muestra una vista de cuadrícula mejorada. El delegado se ha mejorado visualmente y se ha trasladado a un componente independiente de contactDelegate.
Rectangle {
width: 300; height: 200
Component {
id: contactDelegate
Item {
width: grid.cellWidth; height: grid.cellHeight
Column {
anchors.fill: parent
Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
}
}
}
GridView {
id: grid
anchors.fill: parent
cellWidth: 80; cellHeight: 80
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 por teclado en la vista de cuadrícula. La propia vista de cuadrícula es un ámbito de enfoque (véase «Enfoque del teclado» en Qt Quick para obtener más detalles).
Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Nunca se debe almacenar el estado en un delegado.
GridView adjunta una serie de propiedades al elemento raíz del delegado, por ejemplo, GridView.isCurrentItem. En el siguiente ejemplo, el elemento raíz del delegado puede acceder a esta propiedad adjunta directamente como GridView.isCurrentItem, mientras que el objeto hijo contactInfo debe hacer referencia a esta propiedad como wrapper.GridView.isCurrentItem.
GridView {
width: 300; height: 200
cellWidth: 80; cellHeight: 80
Component {
id: contactsDelegate
Rectangle {
id: wrapper
width: 80
height: 80
color: GridView.isCurrentItem ? "black" : "red"
Text {
id: contactInfo
text: name + ": " + number
color: wrapper.GridView.isCurrentItem ? "red" : "black"
}
}
}
model: ContactModel {}
delegate: contactsDelegate
focus: true
}Nota: Las vistas no establecen la propiedad clip automáticamente. Si la vista no está recortada por otro elemento o por la pantalla, será necesario establecer esta propiedad en «true» para recortar los elementos que se encuentren parcial o totalmente fuera de la vista.
Diseños de GridView
El diseño de los elementos en un GridView se puede controlar mediante estas propiedades:
- flow - controla si los elementos se disponen de izquierda a derecha (como una serie de filas) o de arriba abajo (como una serie de columnas). Este valor puede ser GridView.FlowLeftToRight o GridView.FlowTopToBottom.
- layoutDirection - controla la dirección de disposición horizontal: 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: es decir, si los elementos se disponen desde la parte superior de la vista hacia la parte inferior, o viceversa. Este valor puede ser GridView.TopToBottom o GridView.BottomToTop.
Por defecto, una GridView se desplaza de izquierda a derecha, y los elementos se disponen de izquierda a derecha en sentido horizontal y de arriba abajo en sentido vertical.
Estas propiedades se pueden combinar para generar una gran variedad de diseños, tal y como se muestra en la tabla siguiente. Todos los GridView de la primera fila tienen un valor de « flow » (dirección de flujo) de GridView.FlowLeftToRight, pero utilizan diferentes combinaciones de direcciones de diseño horizontal y vertical (especificadas mediante « layoutDirection » y « verticalLayoutDirection », respectivamente). Del mismo modo, todos los GridView de la segunda fila que aparece a continuación tienen un valor de « flow » (dirección de flujo) de «GridView.FlowTopToBottom», pero utilizan diferentes combinaciones de direcciones de diseño horizontal y vertical para distribuir sus elementos de distintas formas.
| GridViews con flujo GridView.FlowLeftToRight | |||
|---|---|---|---|
| (H) De izquierda a derecha (V) De arriba abajo
| (H) De derecha a izquierda (V) De arriba abajo
| (H) De izquierda a derecha (V) De abajo hacia arriba
| (H) De derecha a izquierda (V) De abajo hacia arriba
|
| GridViews con flujo GridView.FlowTopToBottom | |||
| (H) De izquierda a derecha (V) De arriba abajo
| (H) De derecha a izquierda (V) De arriba abajo
| (H) De izquierda a derecha (V) De abajo hacia arriba
| (H) De derecha a izquierda (V) De abajo hacia arriba
|
Véase también Modelos de datos QML, ListView, 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:
GridView {
...
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 se rellena la vista por primera vez, 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, los elementos situados debajo del nuevo elemento se colocarán 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 se vean desplazados por la incorporación de otros elementos a la vista.
Por ejemplo, aquí hay una vista que especifica dicha transición:
GridView {
...
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 se desplaza debido a 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 se desplaza 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 instanciados tantos delegados como quepan dentro del búfer especificado. Por ejemplo, si en una vista vertical el delegado tiene 20 píxeles de altura, hay 3 columnas y la propiedad « cacheBuffer » está establecida en 40, entonces se pueden crear o retener hasta 6 delegados por encima y 6 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 omitan 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 establecer 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 mediante ` displayMarginBeginning ` o ` displayMarginEnd`.
Estas propiedades definen la anchura y la altura de cada celda de la cuadrícula.
El tamaño predeterminado de las celdas es de 100 x 100.
count : int [read-only]
Esta propiedad contiene el número de elementos del modelo.
La propiedad ` currentIndex ` contiene el índice del elemento actual, y ` currentItem ` contiene el elemento actual. Al establecer ` 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 GridView 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.
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 de desplazamiento rápido de la vista. Siempre que sea posible, coloque 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 tamaño de los elementos de la ` GridView ` viene determinado por ` cellHeight ` y ` cellWidth`. No redimensionará los elementos en función del tamaño del elemento raíz del delegado.
El valor predeterminado de ` stacking order ` de las instancias de delegado es ` 1`.
Nota: Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Nunca se debe almacenar el estado en un delegado.
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 mediante propiedades de contexto, el objeto ` model ` o 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 una transición genérica para los elementos desplazados por operaciones 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:
GridView {
...
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 » a lo largo de 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, hay 3 columnas y tanto « displayMarginBeginning » como « displayMarginEnd » están establecidas en 40, se crearán y mostrarán 6 delegados por encima y 6 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 almacena la dirección efectiva de disposición de la cuadrícula.
Al utilizar la propiedad asociada LayoutMirroring::enabled para diseños de configuración regional, la dirección visual del diseño de la cuadrícula se invertirá. Sin embargo, la propiedad layoutDirection permanecerá sin cambios.
Véase también « GridView::layoutDirection » y « LayoutMirroring ».
flow : enumeration
Esta propiedad controla el flujo de la cuadrícula.
Valores posibles:
| Constante | Descripción |
|---|---|
GridView.FlowLeftToRight | (por defecto) Los elementos se disponen de izquierda a derecha y la vista se desplaza verticalmente |
GridView.FlowTopToBottom | Los elementos se disponen de arriba abajo y la vista se desplaza horizontalmente |
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 nombre de clase predeterminado ( stacking order ) del pie de página es 1.
Véase también header y footerItem.
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 sitúa al final de la vista, después de cualquier otro elemento. La URL predeterminada stacking order del pie de página es 1.
Véase también footer y headerItem.
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 y headerItem.
headerItem : Item [read-only]
Aquí se almacena el elemento de cabecera 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 de cualquier otro elemento. El valor predeterminado de « stacking order » de la cabecera es 1.
Véase también header y footerItem.
highlight : Component
Esta propiedad contiene el componente que se utilizará como resaltado.
Se crea una instancia del componente de resaltado para cada vista. La vista gestionará la geometría de la instancia del componente resultante de modo que permanezca con el elemento actual, a menos que la propiedad « highlightFollowsCurrentItem » tenga el valor «false». El valor predeterminado de « stacking order » del elemento de resaltado es « 0 ».
Véase también highlightItem y highlightFollowsCurrentItem.
highlightFollowsCurrentItem : bool
Esta propiedad determina si la vista se encarga de gestionar 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: view.cellWidth; height: view.cellHeight
color: "lightsteelblue"; radius: 5
x: view.currentItem.x
y: view.currentItem.y
Behavior on x { SpringAnimation { spring: 3; damping: 0.2 } }
Behavior on y { SpringAnimation { spring: 3; damping: 0.2 } }
}
}
GridView {
id: view
width: 300; height: 200
cellWidth: 80; cellHeight: 80
model: ContactModel {}
delegate: Column {
Image { source: portrait; anchors.horizontalCenter: parent.horizontalCenter }
Text { text: name; anchors.horizontalCenter: parent.horizontalCenter }
}
highlight: highlight
highlightFollowsCurrentItem: false
focus: true
}highlightItem : Item [read-only]
Aquí se almacena el elemento destacado creado a partir del componente « highlight ».
El elemento destacado (highlightItem) es gestionado por la vista, a menos que highlightFollowsCurrentItem esté establecido en false. La stacking order predeterminada del elemento destacado es 0.
Véase también « highlight » y « highlightFollowsCurrentItem ».
highlightMoveDuration : int
Esta propiedad almacena la duración de la animación de movimiento del delegado de resaltado.
highlightFollowsCurrentItem Debe ser «true» para que esta propiedad surta efecto.
El valor predeterminado de la duración es 150 ms.
Vé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 vista. Por ejemplo, si se desea que el elemento seleccionado actualmente permanezca en el centro de la vista al desplazarse, 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 vista se desplazará automáticamente para que el elemento actual quede en el centro de la vista. Además, este 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 |
|---|---|
GridView.ApplyRange | la vista intenta mantener el resaltado dentro del rango. Sin embargo, el resaltado puede salirse del rango en los extremos de la vista o debido a la interacción con el ratón. |
GridView.StrictlyEnforceRange | El elemento resaltado nunca sale del rango. El elemento actual cambia si una acción del teclado o del ratón provoca que el elemento resaltado salga del rango. |
GridView.NoHighlightRange | El valor por defecto |
keyNavigationEnabled : bool
Esta propiedad indica si la navegación mediante teclas de la cuadrícula está activada.
Si su 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 determina si la cuadrícula se desplaza al utilizar la navegación por teclas
Si este valor es «true», la navegación mediante teclas que llevaría la selección del elemento actual más allá de un extremo de la vista, en lugar de ello, se reanuda y desplaza la selección al otro extremo de la vista.
Por defecto, la navegación mediante teclas no se reenvuelve.
layoutDirection : enumeration
Esta propiedad determina la dirección de disposición de la cuadrícula.
Valores posibles:
| Constante | Descripción |
|---|---|
Qt.LeftToRight | (por defecto) Los elementos se distribuirán comenzando por la esquina superior izquierda. El flujo depende de la propiedad « GridView::flow ». |
Qt.RightToLeft | Los elementos se distribuirán comenzando por la esquina superior derecha. El flujo depende de la propiedad « GridView::flow ». |
Nota: Si GridView::flow se establece en GridView.FlowLeftToRight, esto no debe confundirse con el caso en que GridView::layoutDirection se establezca en Qt.RightToLeft. El valor de flujo GridView.FlowLeftToRight simplemente indica que el flujo es horizontal.
Véase también GridView::effectiveLayoutDirection y GridView::verticalLayoutDirection.
model : model
Esta propiedad contiene el modelo que proporciona los datos para la cuadrícula.
El modelo proporciona el conjunto de datos que se utiliza para crear los elementos de la vista. Los modelos pueden crearse directamente en QML utilizando ListModel, DelegateModel, 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:
GridView {
...
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, consulta 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, he aquí una vista que especifica dicha transición:
GridView {
...
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 verdaderos sujetos 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 «add», «move» o «remove», 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.
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 quedan completamente sustituidos
- 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:
GridView {
...
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 aparecen nuevos delegados, la que se ejecuta es la transición « add ». 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:
GridView {
...
delegate: Rectangle {
opacity: 1 // not necessary because it's the default; but don't set 0
...
}
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:
GridView {
...
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 animará hasta la posición (100,100) en el transcurso de un segundo y, al mismo tiempo, cambiará su opacidad a 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 dejará de ser válida.
Además, si se ha establecido la propiedad adjunta ` 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:
GridView {
...
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 una transición « 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 por 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, consulta la documentación de ViewTransition.
Véase también displaced, remove y ViewTransition.
reuseItems : bool
Esta propiedad te permite reutilizar los elementos instanciados desde el 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().
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 |
|---|---|
GridView.NoSnap | (por defecto) la vista se detiene en cualquier punto dentro del área visible. |
GridView.SnapToRow | La vista se estabiliza con una fila (o columna, en el caso de un flujo « GridView.FlowTopToBottom ») alineada con el inicio de la vista. |
GridView.SnapOneRow | La vista se estabilizará a una distancia máxima de una fila (o columna, en el caso de un flujo de « GridView.FlowTopToBottom ») de la primera fila visible en el momento en que se suelte el botón del ratón. Este modo resulta especialmente útil para desplazarse una página cada vez. |
verticalLayoutDirection : enumeration
Esta propiedad determina la dirección de disposición vertical de la cuadrícula.
Valores posibles:
| Constante | Descripción |
|---|---|
GridView.TopToBottom | (por defecto) Los elementos se disponen desde la parte superior de la vista hasta la parte inferior de la misma. |
GridView.BottomToTop | Los elementos se disponen desde la parte inferior de la vista hacia la parte superior de la vista. |
Véase también GridView::layoutDirection.
Documentación de la propiedad adjunta
GridView.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 {
GridView.onRemove: SequentialAnimation {
PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true }
NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false }
}
}
}Si se ha especificado una transición « remove », no se aplicará hasta que «delayRemove» devuelva « false ».
GridView.isCurrentItem : bool [read-only attached]
Esta propiedad adjunta devuelve «true» si este delegado es el elemento actual; en caso contrario, devuelve «false».
Se asocia a cada instancia del delegado.
GridView {
width: 300; height: 200
cellWidth: 80; cellHeight: 80
Component {
id: contactsDelegate
Rectangle {
id: wrapper
width: 80
height: 80
color: GridView.isCurrentItem ? "black" : "red"
Text {
id: contactInfo
text: name + ": " + number
color: wrapper.GridView.isCurrentItem ? "red" : "black"
}
}
}
model: ContactModel {}
delegate: contactsDelegate
focus: true
}GridView.view : GridView [read-only attached]
Esta propiedad asociada contiene la vista que gestiona esta instancia de delegado.
Está asociada a cada instancia del delegado, así como a los delegados de encabezado, pie de página 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.
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 los 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 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 « GridView » aún no se haya actualizado.
Este método obliga al « GridView » a responder inmediatamente a cualquier cambio pendiente en el modelo.
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 content item. 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 pantalla hasta que quede visible.
Nota: si añades un « MouseArea » como elemento secundario de « GridView », devolverá posiciones en coordenadas « GridView » en lugar de en coordenadas del elemento de contenido. Para utilizar esas posiciones en una llamada a esta función, primero debes asignarlas:
GridView {
id: view
MouseArea {
anchors.fill: parent
onClicked: (mouse) => {
let posInGridView = Qt.point(mouse.x, mouse.y)
let posInContentItem = mapToItem(view.contentItem, posInGridView)
let index = view.indexAt(posInContentItem.x, posInContentItem.y)
}
}
}Nota: los métodos solo deben llamarse una vez que el componente se haya completado.
Véase también itemAt.
Item itemAt(real x, real y)
Devuelve el elemento visible que contiene el punto x, y en coordenadas content item. 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 vista hasta él.
Nota: los métodos solo deben invocarse una vez que el componente haya finalizado.
Véase también indexAt.
Item itemAtIndex(int index)
Devuelve el elemento correspondiente a index. Si no existe ningún elemento con 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 dicho elemento.
void moveCurrentIndexDown()
Desplaza el ` currentIndex ` un elemento hacia abajo en la vista. 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.
void moveCurrentIndexLeft()
Desplaza el ` currentIndex ` un elemento hacia la izquierda en la vista. 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.
void moveCurrentIndexRight()
Desplaza el objeto ` currentIndex ` un elemento hacia la derecha en la vista. 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.
void moveCurrentIndexUp()
Desplaza el ` currentIndex ` un elemento hacia arriba en la vista. 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.
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 punto de vista ( index ) se sitúe en la posición especificada por el punto de vista ( mode):
| Constante | Descripción |
|---|---|
GridView.Beginning | elemento de posición en la parte superior (o a la izquierda, en el caso del flujo « GridView.FlowTopToBottom ») de la vista. |
GridView.Center | Elemento de posición en el centro de la vista. |
GridView.End | Coloca el elemento en la parte inferior (o a la derecha, en el caso de la orientación horizontal) de la vista. |
GridView.Visible | Si alguna parte del elemento es visible, no se realiza ninguna acción; de lo contrario, se muestra el elemento en la vista. |
GridView.Contain | Asegurarse de que todo el elemento esté visible. Si el elemento es más grande que la vista, se coloca en la parte superior (o a la izquierda en el caso de un flujo « GridView.FlowTopToBottom ») de la vista. |
GridView.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 el índice 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 vista no provoca que se reubiquen todos los demás elementos. 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 colocar la vista en el inicio, este método debe ser invocado por `Component.onCompleted`. Por ejemplo, para colocar la vista al final:
Component.onCompleted: positionViewAtIndex(count - 1, GridView.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.







