Back to Qt.io
Contact Us Blog Download Qt
本页内容

SafeArea QML Type (Uncreatable)

提供对项目或窗口安全区域属性的访问。更多...

Import Statement: import QtQuick
Since: Qt 6.9

注意：此为不可创建的类型。无法在 QML 中实例化。

属性

详细说明

“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
        }
    }
}
iPhone 在显示内容时会遵守安全区域的边距

SafeArea 的边距是相对于其附加的项而言的。如果父项已将其子项布局在安全区域边距内，则任何附加了自身 SafeArea 的子孙项都会报告零边距，除非已添加了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
            }
        }
    }
}

带有标题栏的 iPhone，增加了安全区域的边距

在上例中，标题项位于窗口顶部，这可能会与来自窗口的现有安全区域边距发生重叠。为解决此问题，我们仅针对超出窗口安全区域边距的标题部分添加额外边距。

注意：在此示例中， 标题项并未与子项重叠，因为本示例旨在展示项目如何根据安全区域边距的变化进行定位和调整大小。

控件

将安全区域边距应用于控件非常简单，因为控件本身已提供用于为控件内容项添加内边距的属性。

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 。

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