Back to Qt.io
Contact Us Blog Download Qt

SafeArea QML Type

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

Import Statement: import QtQuick
Since: Qt 6.9

속성

상세 설명

안전 영역 첨부 유형은 시스템 제목 표시줄이나 상태 표시줄과 같이 콘텐츠가 다른 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 을 추가하지 않는 한 여백이 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
            }
        }
    }
}

위의 예에서 헤더 항목은 창 상단에 위치하므로 창에서 오는 기존 안전 영역 여백과 겹칠 가능성이 있습니다. 이를 고려하기 위해 창의 안전 영역 여백을 넘어 확장되는 헤더 부분에 대해서만 여백을 추가합니다.

참고: 이 예제에서는 헤더 항목이 하위 항목과 겹치지 않는데, 이는 안전 영역 여백 변경에 따라 항목의 위치 및 크기가 어떻게 조정되는지 보여주기 위한 것입니다.

컨트롤

컨트롤은 이미 컨트롤의 콘텐츠 항목에 패딩을 추가하는 속성을 제공하므로 컨트롤에 안전 영역 여백을 적용하는 것은 간단합니다.

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.