En esta página

Grid QML Type

Coloca sus elementos secundarios en una disposición en cuadrícula. Más...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Métodos

Descripción detallada

Grid es un tipo que coloca sus elementos secundarios en forma de cuadrícula.

Una «Grid» crea una cuadrícula de celdas lo suficientemente grande como para contener todos sus elementos secundarios y coloca estos elementos en las celdas de izquierda a derecha y de arriba abajo. Cada elemento se coloca en la esquina superior izquierda de su celda con la posición (0, 0).

Por defecto, una Grid tiene cuatro columnas y crea tantas filas como sean necesarias para que quepan todos sus elementos secundarios. El número de filas y columnas se puede limitar estableciendo las propiedades « rows » y « columns ».

Por ejemplo, a continuación se muestra una cuadrícula que contiene cinco rectángulos de distintos tamaños:

import QtQuick

Grid {
    columns: 3
    spacing: 2
    Rectangle { color: "red"; width: 50; height: 50 }
    Rectangle { color: "green"; width: 20; height: 50 }
    Rectangle { color: "blue"; width: 50; height: 20 }
    Rectangle { color: "cyan"; width: 50; height: 50 }
    Rectangle { color: "magenta"; width: 10; height: 10 }
}

La cuadrícula coloca automáticamente los elementos secundarios en una disposición de cuadrícula:

Cinco rectángulos de colores dispuestos en forma de cuadrícula

Si un elemento dentro de una cuadrícula no tiene un ancho ( visible) o si su ancho o altura es 0, el elemento no se distribuirá y no será visible dentro de la columna. Además, dado que una cuadrícula posiciona automáticamente a sus elementos secundarios, un elemento secundario dentro de una cuadrícula no debe establecer sus posiciones de altura ( x ) ni de ancho ( y ), ni anclarse mediante ninguna de las propiedades de alineación ( anchor ).

Para obtener más información sobre el uso de Grid y otros tipos de posicionadores relacionados, consulta «Posicionadores de elementos».

Véase también « Flow» , « Row », « Column », « Positioner », « GridLayout » y «Qt Quick » Ejemplos: Posicionadores.

Documentación de propiedades

add : Transition

Esta propiedad define la transición que se aplicará a los elementos que se añadan a este posicionador. En el caso de un posicionador, esto se aplica a:

  • Los elementos que se crean o se reasignan como hijos del posicionador después de que este se haya creado
  • Elementos hijos que cambian su propiedad « Item::visible » de «false» a «true» y, por lo tanto, pasan a ser visibles

La transición puede utilizar la propiedad ` ViewTransition ` para acceder a más detalles sobre el elemento que se está añadiendo. Consulta la documentación de « ViewTransition » para obtener más detalles y ejemplos sobre el uso de estas transiciones.

Nota: Esta transición no se aplica a los elementos que ya forman parte del posicionador en el momento de su creación. En este caso, se aplica en su lugar la transición « populate ».

Véase también populate, ViewTransition y Qt Quick Ejemplos: Posicionadores.

bottomPadding : real

leftPadding : real

padding : real

rightPadding : real

topPadding : real

Estas propiedades definen el relleno que rodea el contenido.

columnSpacing : real

Esta propiedad define el espaciado, en píxeles, entre columnas.

Si esta propiedad no está definida, se utiliza el espaciado para el espaciado entre columnas.

Por defecto, esta propiedad no está configurada.

Véase también rowSpacing.

columns : int

Esta propiedad indica el número de columnas de la cuadrícula. El número predeterminado de columnas es 4.

Si la cuadrícula no tiene suficientes elementos para llenar el número de columnas especificado, algunas columnas tendrán un ancho nulo.

effectiveHorizontalItemAlignment : enumeration [read-only]

horizontalItemAlignment : enumeration

verticalItemAlignment : enumeration

Establece la alineación horizontal y vertical de los elementos de la cuadrícula. Por defecto, los elementos se alinean verticalmente en la parte superior. La alineación horizontal sigue la propiedad « layoutDirection » de la cuadrícula; por ejemplo, si « layoutDirection » tiene el valor «LeftToRight», los elementos se alinearán a la izquierda.

Los valores válidos para « horizontalItemAlignment » son: « Grid.AlignLeft », « Grid.AlignRight » y « Grid.AlignHCenter ».

Los valores válidos para « verticalItemAlignment » son « Grid.AlignTop », « Grid.AlignBottom » y « Grid.AlignVCenter ».

Las siguientes imágenes muestran tres ejemplos de cómo alinear elementos.

Rectángulos de colores alineados en la esquina superior izquierda de las celdas de la cuadrículaRectángulos de colores alineados en la parte superior central de las celdas de la cuadrículaRectángulos de colores centrados en las casillas de la cuadrícula
Alineación horizontalAlignLeftAlignHCenterAlignHCenter
Alineación verticalAlinear arribaAlinear arribaAlignVCenter

Al reflejar el diseño utilizando la propiedad adjunta LayoutMirroring::enabled o estableciendo el valor layoutDirection, la alineación horizontal de los elementos también se reflejará. Sin embargo, la propiedad horizontalItemAlignment permanecerá sin cambios. Para consultar la alineación horizontal efectiva de los elementos, utilice la propiedad de solo lectura effectiveHorizontalItemAlignment.

Véase también Grid::layoutDirection y LayoutMirroring.

effectiveLayoutDirection : enumeration [read-only]

Esta propiedad contiene la dirección de diseño efectiva 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 del posicionador de la cuadrícula se invertirá. Sin embargo, la propiedad layoutDirection permanecerá sin cambios.

Véase también Grid::layoutDirection y LayoutMirroring.

flow : enumeration

Esta propiedad controla el flujo de la maquetación.

Los valores posibles son:

  • Grid.LeftToRight (por defecto): los elementos se colocan uno al lado del otro en el layoutDirection y, a continuación, se ajustan a la línea siguiente.
  • Grid.TopToBottom: los elementos se colocan uno al lado del otro de arriba abajo y, a continuación, se ajustan a la siguiente columna.

layoutDirection : enumeration

Esta propiedad define la dirección de la disposición.

Los valores posibles son:

  • Qt.LeftToRight (por defecto): los elementos se colocan de arriba abajo y de izquierda a derecha. La dirección del flujo depende de la propiedad « Grid::flow ».
  • Qt.RightToLeft: los elementos se colocan de arriba abajo y de derecha a izquierda. La dirección del flujo depende de la propiedad « Grid::flow ».

Véase también « Flow::layoutDirection » y « Row::layoutDirection ».

move : Transition

Esta propiedad controla la transición que se ejecutará para los elementos que se hayan desplazado dentro del posicionador. En el caso de un posicionador, esto se aplica a:

  • Elementos secundarios que se desplazan al ser reubicados debido a la adición, eliminación o reorganización de otros elementos en el posicionador
  • Elementos secundarios que se reposicionan debido al cambio de tamaño de otros elementos del posicionador

La transición puede utilizar la propiedad ` ViewTransition ` para acceder a más detalles sobre el elemento que se está moviendo. Sin embargo, ten en cuenta que, para esta transición de movimiento, las listas ` ViewTransition.targetIndexes` y ` ViewTransition.targetItems` solo se establecen cuando esta transición se activa por la adición de otros elementos en el posicionador; en los demás casos, estas listas estarán vacías. Consulte la documentación de ViewTransition para obtener más detalles y ejemplos sobre el uso de estas transiciones.

Véase también add, populate, ViewTransition y Qt Quick Ejemplos: Posicionadores.

populate : Transition

Esta propiedad contiene la transición que se ejecutará para los elementos que formen parte de este posicionador en el momento de su creación. La transición se ejecuta cuando se crea el posicionador por primera vez.

La transición puede utilizar la propiedad ViewTransition para acceder a más detalles sobre el elemento que se está añadiendo. Consulte la documentación de ViewTransition para obtener más detalles y ejemplos sobre el uso de estas transiciones.

Véase también « add» , « ViewTransition » y «Qt Quick: Ejemplos — Posicionadores».

rowSpacing : real

Esta propiedad establece el espaciado entre filas en píxeles.

Si no se establece esta propiedad, se utiliza el espaciado para el espaciado entre filas.

Por defecto, esta propiedad no está definida.

Véase también columnSpacing.

rows : int

Esta propiedad indica el número de filas de la cuadrícula.

Si la cuadrícula no tiene suficientes elementos para llenar el número de filas especificado, algunas filas tendrán un ancho nulo.

spacing : real

El espaciado es la distancia en píxeles que se deja libre entre elementos adyacentes. La cantidad de espaciado aplicada será la misma tanto en horizontal como en vertical. El espaciado por defecto es 0.

En el siguiente ejemplo se coloca una cuadrícula que contiene un rectángulo rojo, uno azul y uno verde sobre un fondo gris. El área que ocupa el posicionador de la cuadrícula aparece en blanco. El posicionador de la izquierda no tiene espaciado (valor por defecto), mientras que el de la derecha tiene un espaciado de 6.

Cuatro cuadrados de colores en una cuadrícula sin espacios entre ellos Cuatro cuadrados de colores dispuestos en una cuadrícula, con espacio entre ellos

Véase también rows y columns.

Documentación de Signal

positioningComplete()

Esta señal se emite cuando se ha completado el posicionamiento.

Nota: El controlador correspondiente es onPositioningComplete.

Documentación del método

void forceLayout()

Normalmente, Grid posiciona sus elementos hijos una vez por fotograma. Esto significa que, dentro de los bloques de script, es posible que los elementos hijos subyacentes hayan cambiado, pero que Grid aún no se haya actualizado en consecuencia.

Este método obliga a la cuadrícula a responder de inmediato a cualquier cambio pendiente en sus elementos secundarios.

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

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