En esta página

Qt Quick Descripción general de los diseños

Utiliza los diseños de « Qt Quick » para organizar los elementos en una interfaz de usuario. Los diseños de « Qt Quick » ajustan el tamaño de sus elementos, lo que los hace muy adecuados para interfaces de usuario redimensionables.

Características principales

Algunas de las características principales de los diseños de Qt Quick son:

Además, « GridLayout » añade estas características:

Primeros pasos

Para empezar a utilizar los diseños de « Qt Quick », importa los tipos QML a tu aplicación con la siguiente instrucción de importación en tu archivo « .qml »:

import QtQuick.Layouts

El siguiente paso es crear un diseño sencillo. También puedes consultar el ejemplo básico de diseños de «Qt Quick ».

Un diseño sencillo

El objetivo de utilizar un diseño es reorganizar sus elementos secundarios cada vez que el diseño cambie de tamaño. Esto significa que la aplicación debe garantizar que el diseño se redimensione. En el siguiente fragmento de código, el RowLayout lo garantiza especificando « anchors.fill: parent ». Sin embargo, también se puede lograr de otras formas, como especificando las propiedades « width » y « height ». En el mismo fragmento de código, el rectángulo naranja tiene un tamaño fijo de 100 por 150 píxeles, mientras que el rectángulo ciruela se expandirá para ocupar todo el espacio que se le asigne.

Window {
    RowLayout {
        anchors.fill: parent
        spacing: 6
        Rectangle {
            color: 'azure'
            Layout.preferredWidth: 100
            Layout.preferredHeight: 150
        }
        Rectangle {
            color: "plum"
            Layout.fillWidth: true
            Layout.fillHeight: true
        }
    }
}

Los diseños se encargan de la geometría de sus elementos secundarios. Esto incluye propiedades como width, height, x, y, anchors), etc.

Importante: No especifiques propiedades que influyan en la geometría de los elementos secundarios de tu aplicación. Establecer estas propiedades en un elemento secundario provoca un conflicto de intereses, y el resultado es indefinido. Esto también se aplica cuando el elemento secundario es un diseño. Por lo tanto, solo los diseños que no tengan un diseño principal pueden tener anchors.fill: parent.

Espaciado

Como se ve en el fragmento de código anterior, el espaciado del RowLayout está establecido en 6. Esto garantiza que todos los elementos del diseño tengan un espaciado de 6 píxeles entre ellos:

spacing: 6

Si no se especifica ningún valor de espaciado, el diseño utilizará un valor predeterminado de 5 píxeles. El espaciado, así como el `implicitWidth` de cualquier elemento secundario, contribuye al `implicitWidth` del diseño. Es importante tener esto en cuenta si se confía en el comportamiento predeterminado, ya que puede afectar al diseño. Por ejemplo, los dos ColumnLayouttienen establecido Layout.fillWidth: true en el siguiente fragmento de código. Es lógico pensar que ambos tendrían el mismo ancho. Sin embargo, debido al espaciado predeterminado de 5 píxeles entre los elementos del RowLayout interior, el ancho implícito (implicitWidth) del primer ColumnLayout aumenta, dejando menos espacio para el segundo. Por ejemplo:

ApplicationWindow {
    id: root
    width: 300
    height: 300
    visible: true

    RowLayout {
        anchors.fill: parent
        ColumnLayout {
            Rectangle {
                color: "tomato";
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            RowLayout {
                Rectangle {
                    color: "navajowhite"
                    Layout.fillWidth: true
                    Layout.fillHeight: true
                }
                Rectangle {
                    color: "darkseagreen"
                    Layout.fillWidth: true
                    Layout.fillHeight: true
                }
            }
        }
        ColumnLayout {
            Rectangle {
                color: "lightpink"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            Rectangle {
                color: "slategray"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
            Rectangle {
                color: "lightskyblue"
                Layout.fillWidth: true
                Layout.fillHeight: true
            }
        }
    }
}

Este fragmento de código generará un diseño con este aspecto:

Un diseño QML con espaciado predeterminado

Para asegurarte de que estas dos columnas tengan el mismo tamaño, puedes:

  1. establecer el espaciado del RowLayout en 0, o
  2. establecer el valor de preferredWidth en el mismo valor para ambas ColumnLayout.

Especificar el tamaño preferido

Para cada elemento, el tamaño preferido efectivo puede proceder de una de varias propiedades candidatas. Para determinar el tamaño preferido efectivo, un elemento consulta estas propiedades candidatas en el siguiente orden y utilizará la primera candidata con un ancho o una altura válidos.

Propiedades candidatasDescripción
Layout.preferredWidth o Layout.preferredHeightSe supone que la aplicación debe modificar estas propiedades si el tamaño implícito por defecto no proporciona la disposición óptima.
implicitWidth o « implicitHeight ».Se espera que cada elemento proporcione estas propiedades para establecer un tamaño ideal significativo. Por ejemplo, el tamaño necesario para mostrar todo el contenido de un tipo « Text ». Un ancho o una altura implícitos de « 0 » se interpretan como no válidos.

Un elemento puede especificar « Layout.preferredWidth » sin necesidad de especificar « Layout.preferredHeight ». En tales casos, la altura preferida efectiva se determina a partir de « implicitHeight ».

Nota: Si no se especifica ni preferredWidth ni implicitWidth, el diseño consultará width como valor definitivo para el ancho preferido efectivo. Sin embargo, no se debe confiar en width como fuente del ancho preferido efectivo, ya que ello podría provocar un comportamiento inesperado. Por ejemplo, cambiar las propiedades « width » o « height » no provocará una reorganización del diseño, o bien el diseño podría utilizar el ancho y la altura reales —y no los especificados en tu archivo QML— cuando se vea obligado a realizar una reconstrucción completa.

Restricciones de tamaño

Dado que un elemento puede cambiar de tamaño según su diseño, este debe conocer los tamaños « minimum », « preferred » y « maximum » de todos los elementos en los que « Layout.fillWidth » o « Layout.fillHeight » estén establecidos en «true».

El ancho y la altura « preferred » son el ancho y la altura reales de un elemento, si el diseño no está vinculado a un tamaño específico. Si el diseño se establece en un tamaño específico, distribuye el espacio adicional en función de la proporción de los tamaños «preferred» de sus elementos, teniendo en cuenta al mismo tiempo los tamaños mínimo y máximo. Los tamaños «preferred» e «implicit» actúan como proporciones y ponderaciones cuando todos los elementos tienen configurados «fillWidth » y «fillHeight».

Por ejemplo, lo siguiente genera un diseño con dos rectángulos situados uno al lado del otro que se extiende horizontalmente. El rectángulo naranja se puede redimensionar de 50x150 a 300x150, y el rectángulo ciruela se puede redimensionar de 100x100 a ∞x100. Siempre que no se superen el ancho mínimo y máximo de cada elemento, el rectángulo color ciruela tendrá el doble de ancho que el naranja.

RowLayout {
    id: layout
    anchors.fill: parent
    spacing: 6
    Rectangle {
        color: 'orange'
        Layout.fillWidth: true
        Layout.minimumWidth: 50
        Layout.preferredWidth: 100
        Layout.maximumWidth: 300
        Layout.minimumHeight: 150
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
    Rectangle {
        color: 'plum'
        Layout.fillWidth: true
        Layout.minimumWidth: 100
        Layout.preferredWidth: 200
        Layout.preferredHeight: 100
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
}

RowLayout en su configuración mínima

La combinación de las restricciones de cada elemento da lugar a estas restricciones implícitas para el elemento de diseño:

mínimopreferidomáximo
restricciones implícitas (anchura)156306∞ (Number.POSITIVE_INFINITY)
restricciones implícitas (alturas)150150150

Por lo tanto, el diseño no puede tener una anchura inferior a 156, ni una altura superior o inferior a 150, sin incumplir ninguna de las restricciones de sus elementos secundarios.

Conexión de ventanas y diseños

Puedes utilizar los conceptos habituales de anclaje para garantizar que tu diseño se adapte al cambio de tamaño de la ventana.

RowLayout {
    id: layout
    anchors.fill: parent

Puedes basarte en las restricciones de tamaño de los diseños para garantizar que la ventana no pueda cambiarse de tamaño más allá de las restricciones del diseño. Puedes tomar las restricciones de tamaño del diseño y establecerlas en los atributos `minimumWidth`, `minimumHeight`, `maximumWidth` y `maximumHeight` del elemento ` Window `. El siguiente código garantiza que el tamaño de la ventana no pueda modificarse más allá de las restricciones del diseño:

minimumWidth: layout.Layout.minimumWidth
minimumHeight: layout.Layout.minimumHeight
maximumWidth: 1000
maximumHeight: layout.Layout.maximumHeight

Nota: Dado que `layout.Layout.maximumWidth ` es infinito en este caso, no podemos vincularlo a la propiedad `maximumWidth` de `Window`, ya que se trata de un número entero. Por lo tanto, el ancho máximo se establece en un valor fijo de ` 1000`.

Por último, establece el tamaño inicial de la ventana en el tamaño implícito del diseño:

width: layout.implicitWidth
height: layout.implicitHeight

Extender y estirar elementos

Utiliza ` spans ` en un ` GridLayout ` para que los elementos hijos ocupen más de una celda. Por ejemplo, puedes tener un ` GridLayout ` con seis celdas distribuidas en dos filas. La fila superior contiene los elementositem1, item2 e item3. La fila inferior contiene el elemento item4, que especifica columnSpan: 3 y alignment: Qt.AlignHCenter. Esto sitúa a item4 en el centro de las tres celdas que componen la fila inferior. El siguiente fragmento de código sirve como ejemplo:

ApplicationWindow {
    id: root
    width: 300
    height: 300
    visible: true

    GridLayout {
       rows: 2
       columns: 3
       Rectangle {
           color: 'cyan'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'magenta'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'yellow'
           implicitWidth: 50
           implicitHeight: 50
       }
       Rectangle {
           color: 'black'
           implicitWidth: 50
           implicitHeight: 50
           Layout.columnSpan: 3
           Layout.alignment: Qt.AlignHCenter
       }
    }
}

El tamaño de las filas y las columnas viene determinado implícitamente por su contenido. Por ejemplo, un botón (Button) puede afectar al ancho de la columna en la que se encuentra o a la altura de la fila en la que está. Esto significa que un elemento de diseño ( GridLayout ) no tiene una distribución uniforme. Por este motivo, no se puede utilizar un «span» para estirar un diseño. Para manipular el estiramiento de un elemento o diseño, utiliza en su lugar los « stretchFactor» y/o las indicaciones de tamaño.

Nota: Al establecer tamaños implícitos o preferidos, no vincules las propiedades correspondientes al ancho o la altura del propio diseño ni a los elementos de los que depende para sus cálculos de tamaño, ya que esto puede provocar dependencias cíclicas difíciles de detectar.

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