Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

SafeArea QML Type (Uncreatable)

항목 또는 창의 안전 영역 속성에 대한 액세스를 제공합니다. 더 보기...

Import Statement: import QtQuick
Since: Qt 6.9

참고: 이 타입은 생성할 수 없는 타입입니다. QML에서 인스턴스화할 수 없습니다.

속성

상세 설명

SafeArea 부착형 타입은 시스템 제목 표시줄이나 상태 표시줄과 같은 다른 UI 요소에 의해 콘텐츠가 겹칠 위험이 있는 항목(Item) 또는 창(Window)의 영역에 대한 정보를 제공합니다.

이 정보를 활용하면, 항목의 배경색이나 효과가 항목 전체에 걸쳐 표시되도록 하면서도, 항목의 자식 요소들을 해당 항목의 안전 영역 내에 배치할 수 있습니다.

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 `가 추가되지 않은 한 여백이 0으로 보고됩니다.

참고: 항목은 자체 안전 영역을 기준으로 위치를 지정해서는 안 됩니다. 이는 바인딩 루프를 유발할 수 있기 때문입니다.

추가 여백

때로는 항목의 레이아웃에 서로 겹치는 자식 항목이 포함되기도 합니다. 예를 들어, 반투명한 헤더가 있는 창에서 나머지 창 콘텐츠가 헤더 아래로 흐르는 경우가 있습니다.

이 시나리오에서 항목은 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에는 이미 컨트롤의 콘텐츠 항목에 패딩을 추가하는 속성이 제공되므로, 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
    }
}

속성 설명서

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.