Back to Qt.io
Contact Us Blog Download Qt

SafeArea QML Type

用于访问项目或窗口的安全区域属性。更多

Import Statement: import QtQuick
Since: Qt 6.9

属性

详细说明

SafeArea 附件类型提供了有关项目或窗口中内容可能被其他 UI 元素（如系统标题栏或状态栏）重叠的区域的信息。

该信息可用于在项目的安全区域内布局项目的子项，同时仍允许背景颜色或效果横跨整个项目。

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
        }
    }
}

安全区域边距是相对于其所依附的项目而言的。如果祖先项目已在安全区域边距内布局其子项目，那么任何附加了自己安全区域的子项目都将报告零边距，除非已添加additional margins 。

注意： 项不应根据其自身的安全区域进行定位，否则会导致绑定循环。

附加边距

有时，一个项目的布局会涉及到相互重叠的子项目，例如，在一个带有半透明标题的窗口中，窗口内容的其余部分都位于标题下方。

在这种情况下，项目可通过additionalMargins 属性向子项目反映页眉的位置和大小。

额外的边距将被添加到项目已从其父层次结构中获取的任何边距（包括系统边距，如标题栏或状态栏）中，子项目将反映相应的组合边距。

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
            }
        }
    }
}

在上面的示例中，页眉项目位于窗口顶部，有可能与来自窗口的现有安全区域边距重叠。为此，我们只为超出窗口安全区域边距的页眉部分添加额外边距。

注： 在本例中，页眉项目不会与子项目重叠，因为我们的目的是展示项目是如何根据安全区域边距的变化进行定位和调整大小的。

控件

在控件中应用安全区域边距非常简单，因为控件已经提供了为控件内容项添加填充的属性。

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
    }
}

属性文档

additionalMargins group

additionalMargins.bottom : real

additionalMargins.left : real

additionalMargins.right : real

additionalMargins.top : real

该属性用于保存项目的附加安全区域边距。

附加安全区域边距不能为负值，并将自动箝位为 0。

项目的安全区域边距是继承边距（例如来自标题栏或状态栏）和应用于项目的附加边距的总和。

另请参阅 margins 。


margins group

margins.bottom : real [read-only]

margins.left : real [read-only]

margins.right : real [read-only]

margins.top : real [read-only]

该属性保存相对于附加项目的安全区域边距。

另请参阅 additionalMargins 。


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