En esta página

SafeArea QML Type (Uncreatable)

Permite acceder a las propiedades del área segura del elemento o la ventana. Más...

Import Statement: import QtQuick
Since: Qt 6.9

Nota: Se trata de un tipo no creable. No se puede instanciar en QML.

Propiedades

Descripción detallada

El tipo adjunto SafeArea proporciona información sobre las áreas de un elemento o una ventana en las que el contenido corre el riesgo de solaparse con otros elementos de la interfaz de usuario, como las barras de título o las barras de estado del sistema.

Esta información puede utilizarse para distribuir los elementos hijos de un elemento dentro de su área segura, al tiempo que se permite que un color de fondo o un efecto se extienda por todo el elemento.

Rectangle {
    id: parentItem
    gradient: Gradient.SunnyMorning
    anchors.fill: parent

    Rectangle {
        id: childItem
        gradient: Gradient.DustyGrass

        anchors {
            fill: parent

            topMargin: parent.SafeArea.margins.top
            leftMargin: parent.SafeArea.margins.left
            rightMargin: parent.SafeArea.margins.right
            bottomMargin: parent.SafeArea.margins.bottom
        }
    }
}
iPhone que muestra el contenido respetando los márgenes del área segura

Los márgenes de SafeArea son relativos al elemento al que se asocian. Si un elemento antecesor ha distribuido sus elementos hijos dentro de los márgenes del área segura, cualquier elemento descendiente con su propio SafeArea asociado indicará márgenes nulos, a menos que se hayan añadido « additional margins ».

Nota: Un elemento no debe posicionarse basándose en su propio área segura, ya que eso daría lugar a un bucle de enlace.

Márgenes adicionales

A veces, el diseño de un elemento incluye elementos hijos que se superponen entre sí, por ejemplo, en una ventana con un encabezado semitransparente, donde el resto del contenido de la ventana fluye por debajo del encabezado.

En este caso, el elemento puede reflejar la posición y el tamaño del encabezado en los elementos secundarios a través de la propiedad « additionalMargins ».

Los márgenes adicionales se sumarán a cualquier margen que el elemento ya haya heredado de su jerarquía de elementos padres (incluidos los márgenes del sistema, como las barras de título o de estado), y los elementos secundarios reflejarán los márgenes combinados en consecuencia.

Rectangle {
    id: parentItem
    gradient: Gradient.SunnyMorning
    anchors.fill: parent

    Rectangle {
        id: headerItem
        width: parent.width
        height: 80
        gradient: Gradient.WinterNeva
        z: 1
    }

    Item {
        id: contentItem
        anchors.fill: parent
        z: 0

        SafeArea.additionalMargins.top: headerItem.height
                                      - parent.SafeArea.margins.top

        Rectangle {
            id: childItem
            gradient: Gradient.DustyGrass
            anchors {
                fill: parent

                topMargin: parent.SafeArea.margins.top
                leftMargin: parent.SafeArea.margins.left
                rightMargin: parent.SafeArea.margins.right
                bottomMargin: parent.SafeArea.margins.bottom
            }
        }
    }
}

iPhone con cabecera que añade un margen adicional de área segura

En el ejemplo anterior, el elemento de encabezado se sitúa en la parte superior de la ventana, lo que podría solaparse con los márgenes del área segura existentes de la ventana. Para tenerlo en cuenta, solo añadimos márgenes adicionales a la parte del encabezado que se extiende más allá de los márgenes del área segura de la ventana.

Nota: En este ejemplo, el elemento de cabecera no se superpone al elemento secundario, ya que el objetivo es mostrar cómo se posicionan y redimensionan los elementos en respuesta a los cambios en los márgenes del área segura.

Controles

Aplicar márgenes del área segura a un control es sencillo, ya que el control ya ofrece propiedades para añadir relleno al elemento de contenido del control.

Control {
    anchors.fill: parent

    background: Rectangle {
        gradient: Gradient.SunnyMorning
    }

    topPadding: SafeArea.margins.top
    leftPadding: SafeArea.margins.left
    rightPadding: SafeArea.margins.right
    bottomPadding: SafeArea.margins.bottom

    contentItem: Rectangle {
        gradient: Gradient.DustyGrass
    }
}

Documentación de propiedades

additionalMargins group

additionalMargins.bottom : real

additionalMargins.left : real

additionalMargins.right : real

additionalMargins.top : real

Esta propiedad contiene los márgenes de área de seguridad adicionales para el elemento.

Los márgenes adicionales del área segura no pueden ser negativos y se limitarán automáticamente a 0.

Los márgenes del área segura resultantes del elemento son la suma de los márgenes heredados (por ejemplo, de las barras de título o de la barra de estado) y los márgenes adicionales aplicados al elemento.

Véase también margins.

margins group

margins.bottom : real [read-only]

margins.left : real [read-only]

margins.right : real [read-only]

margins.top : real [read-only]

Esta propiedad contiene los márgenes de la zona de seguridad, en relación con el elemento adjunto.

Véase también additionalMargins.

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