En esta página

Posicionamiento con anclajes

Además de las propiedades más tradicionales como « Grid », « Row » y « Column », « Qt Quick » también ofrece una forma de distribuir los elementos utilizando el concepto de anclajes. Se puede considerar que cada elemento tiene un conjunto de siete «líneas de anclaje» invisibles: « left », « horizontalCenter », « right », « top », « verticalCenter », « baseline » y « bottom ».

Rectángulo en el que se muestran seis líneas de anclaje: izquierda, derecha, superior, inferior y los centros

La línea de base (que no aparece en la imagen anterior) corresponde a la línea imaginaria sobre la que se situaría el texto. Para los elementos sin texto, es lo mismo que «top».

El sistema de anclaje « Qt Quick » te permite definir relaciones entre las líneas de anclaje de diferentes elementos. Por ejemplo, puedes escribir:

Rectangle { id: rect1; ... }
Rectangle { id: rect2; anchors.left: rect1.right; ... }

En este caso, el borde izquierdo de «rect2» queda vinculado al borde derecho de «rect1», lo que da como resultado lo siguiente:

rect1 y rect2 uno al lado del otro, con el borde izquierdo anclado al derecho

Puedes especificar varios puntos de anclaje. Por ejemplo:

Rectangle { id: rect1; ... }
Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... }

rect2 está situado debajo y a la derecha de rect1

Al especificar varios anclajes horizontales o verticales, puedes controlar el tamaño de un elemento. A continuación, rect2 está anclado a la derecha de rect1 y a la izquierda de rect3. Si se mueve cualquiera de los rectángulos azules, rect2 se estirará o se encogerá según sea necesario:

Rectangle { id: rect1; x: 0; ... }
Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: rect3.left; ... }
Rectangle { id: rect3; x: 150; ... }

rect2 se extiende entre rect1, a la izquierda, y rect3, a la derecha

También existen algunos anclajes de conveniencia. « anchors.fill » es un anclaje de conveniencia que equivale a establecer los anclajes izquierdo, derecho, superior e inferior en la izquierda, la derecha, la parte superior y la parte inferior del elemento de destino. « anchors.centerIn » es otro anclaje de conveniencia, y equivale a establecer los anclajes « verticalCenter » y « horizontalCenter » en la « verticalCenter » y la « horizontalCenter » del elemento de destino.

Márgenes y desplazamientos de los anclajes

El sistema de anclaje también permite especificar márgenes y desplazamientos para los anclajes de un elemento. Los márgenes especifican la cantidad de espacio vacío que se debe dejar en el exterior del anclaje de un elemento, mientras que los desplazamientos permiten manipular el posicionamiento utilizando las líneas de anclaje centrales. Un elemento puede especificar sus márgenes de anclaje de forma individual mediante leftMargin, rightMargin, topMargin y bottomMargin, o utilizar anchors.margins para especificar el mismo valor de margen para los cuatro bordes. Los desplazamientos de anclaje se especifican utilizando horizontalCenterOffset, verticalCenterOffset y baselineOffset.

Rectángulo con áreas de margen etiquetadas: superior, inferior, izquierda, derecha

El siguiente ejemplo especifica un margen izquierdo:

Rectangle { id: rect1; ... }
Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }

En este caso, se reserva un margen de 5 píxeles a la izquierda de rect2, lo que da como resultado lo siguiente:

rect1 y rect2 uno al lado del otro, con un espacio de margen entre ellos

Nota: Los márgenesde anclaje solo se aplican a los anclajes; no son un método genérico para aplicar márgenes a un elemento « Item ». Si se especifica un margen de anclaje para un borde, pero el elemento no está anclado a ningún otro elemento de ese borde, el margen no se aplica.

Cambiar anclajes

Qt Quick proporciona el tipo « AnchorChanges » para especificar los anclajes en un estado.

State {
    name: "anchorRight"
    AnchorChanges {
        target: rect2
        anchors.right: parent.right
        anchors.left: undefined  //remove the left anchor
    }
}

AnchorChanges Se puede animar utilizando el tipo « AnchorAnimation ».

Transition {
    AnchorAnimation {}  //animates any AnchorChanges in the corresponding state change
}

Los anclajes también se pueden modificar de forma imperativa en JavaScript. Sin embargo, estos cambios deben ordenarse cuidadosamente, ya que de lo contrario pueden producir resultados inesperados. El siguiente ejemplo ilustra este problema:

// May produce unexpected results
Rectangle {
    width: 50
    anchors.left: parent.left

    function reanchorToRight() {
        anchors.right = parent.right
        anchors.left = undefined
    }
}

Tres pasos que muestran cómo «rect1» se estira de forma inesperada al volver a anclarlo

Cuando se llama a ` reanchorToRight `, la función establece primero el anclaje derecho. En ese momento, quedan establecidos tanto el anclaje izquierdo como el derecho, y el elemento se estirará horizontalmente para ocupar todo el espacio de su elemento padre. Cuando se desactiva el ancla izquierda, se mantendrá el nuevo ancho. Por lo tanto, al actualizar los anclajes en JavaScript, primero debes desactivar cualquier ancla que ya no sea necesaria y, solo entonces, establecer los nuevos anclajes que se requieran, tal y como se muestra a continuación:

// Correct code
Rectangle {
    width: 50
    anchors.left: parent.left

    function reanchorToRight() {
        anchors.left = undefined
        anchors.right = parent.right
    }
}

Tres pasos que muestran cómo «rect1» se desplaza correctamente desde el ancla de la izquierda hasta la de la derecha

Dado que el orden de evaluación de los enlaces no está definido, no se recomienda cambiar los anclajes mediante enlaces condicionales, ya que esto puede provocar el problema de ordenación descrito anteriormente. En el siguiente ejemplo, el Rectangle acabará ocupando todo el ancho de su elemento padre, ya que tanto el anclaje izquierdo como el derecho se establecerán simultáneamente durante la actualización del enlace.

// May produce unexpected results
Rectangle {
    width: 50; height: 50
    anchors.left: state == "right" ? undefined : parent.left;
    anchors.right: state == "right" ? parent.right : undefined;
}

Esto debería reescribirse para utilizar en su lugar AnchorChanges, ya que AnchorChanges gestionará automáticamente los problemas de ordenación de forma interna. A continuación se muestra cómo reescribir correctamente el ejemplo anterior:

// Correct code
Rectangle {
    id: rect
    width: 50; height: 50
    anchors.left: parent.left  // initial position

    states: State {
        name: "rightAligned"
        AnchorChanges {
            target: rect
            anchors.left: undefined
            anchors.right: parent.right
        }
    }
    function toggleAnchoring() {
        parent.state = (parent.state == "" ? "rightAligned" : "")
    }
}

Restricciones

Por motivos de rendimiento, solo se puede anclar un elemento a sus hermanos y a su padre directo. Por ejemplo, el siguiente anclaje no es válido y generaría una advertencia:

//bad code
Item {
    id: group1
    Rectangle { id: rect1; ... }
}
Item {
    id: group2
    Rectangle { id: rect2; anchors.left: rect1.right; ... }    // invalid anchor!
}

Además, los diseños basados en anclajes no pueden combinarse con el posicionamiento absoluto. Si un elemento especifica su posición x y también establece anchors.left, o ancla sus bordes izquierdo y derecho pero además establece un width, el resultado es indefinido, ya que no quedaría claro si el elemento debe utilizar el anclaje o el posicionamiento absoluto. Lo mismo puede decirse al establecer las propiedades y y height de un elemento con anchors.top y anchors.bottom, o al establecer anchors.fill junto con width o height. Lo mismo se aplica al utilizar posicionadores como Row y Grid, que pueden establecer las propiedades x y y del elemento. Si deseas pasar del posicionamiento basado en anclajes al posicionamiento absoluto, puedes borrar un valor de anclaje estableciéndolo en undefined.

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