Back to Qt.io
Contact Us Blog Download Qt

SafeArea QML Type

アイテムまたはウィンドウのセーフエリアプロパティへのアクセスを提供します。詳細...

Import Statement: import QtQuick
Since: Qt 6.9

プロパティ

詳細な説明

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

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

上記の例では、ヘッダー アイテムはウィンドウの上部に配置されており、ウィンドウから来る既存のセーフ エリア マージンと重なる可能性があります。これを考慮し、ウィンドウのセーフ エリア マージンからはみ出るヘッダーの部分のみにマージンを追加します。

注: この例では、ヘッダー項目は子項目と重なっていません。安全領域のマージンの変更に応じて、項目がどのように配置され、サイズが変更されるかを示すことが目的だからです。

コントロール

コントロールはすでに、コントロールのコンテンツアイテムにパディングを追加するプロパティを提供しているので、コントロールにセーフエリアマージンを適用するのは簡単です。

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.