항목 포지셔너

포지셔너 항목은 선언적 사용자 인터페이스에서 항목의 위치를 관리하는 컨테이너 항목입니다. 포지셔너는 표준 Qt Widgets에서 사용되는 레이아웃 관리자와 유사한 방식으로 동작하지만, 그 자체로도 독립적인 컨테이너라는 점이 다릅니다.

포지셔너를 사용하면 많은 항목을 규칙적인 레이아웃으로 배열해야 할 때 작업이 훨씬 수월해집니다.

Qt Quick LayoutsQt Quick 항목을 사용자 인터페이스에 배치하는 데에도 사용할 수 있습니다. 포지셔너는 선언적 사용자 인터페이스에서 항목의 위치와 크기를 모두 관리하며, 크기 조정이 가능한 사용자 인터페이스에 매우 적합합니다.

포지셔너

Qt Quick 그래픽 유형의 기본 세트에는 다음과 같은 표준 포지셔너들이 제공됩니다:

Column	자식 요소를 열 형태로 배치합니다
Flow	자식 요소를 나란히 배치하며, 필요에 따라 줄 바꿈을 적용합니다
Grid	자식 요소를 그리드 형태로 배치합니다
LayoutMirroring	레이아웃 동작을 대칭으로 반전시키는 데 사용되는 속성
Positioner	포지셔너 내에서 항목이 위치한 위치에 대한 세부 정보를 포함하는 첨부 속성을 제공합니다
Row	자식 요소를 행 단위로 배치합니다

컬럼 항목

‘책’, ‘음악’, ‘영화’라고 적힌 세 개의 직사각형이 세로로 쌓여 있다

Column 항목은 항목을 세로로 배열하는 데 사용됩니다. 다음 예제에서는 Column 항목을 사용하여 외부 Item 로 정의된 영역 내에 세 개의 Rectangle 항목을 배열합니다. spacing 속성은 사각형 사이에 약간의 간격을 두도록 설정되어 있습니다.

import QtQuick

Item {
    width: 310; height: 170

    Column {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter

        spacing: 5

        Rectangle { color: "lightblue"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Books" } }
        Rectangle { color: "gold"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Music" } }
        Rectangle { color: "lightgreen"; radius: 10.0
                    width: 300; height: 50
                    Text { anchors.centerIn: parent
                           font.pointSize: 24; text: "Movies" } }
    }
}

Column은 Item을 직접 상속받으므로, 필요한 경우 배경색은 상위 Rectangle에 추가해야 합니다.

Row 항목

가로로 나란히 배치된 둥근 사각형 세 개

Row 항목은 항목을 가로로 배열하는 데 사용됩니다. 다음 예제에서는 Row 항목을 사용하여, 바깥쪽의 색상이 지정된 Rectangle로 정의된 영역 내에 둥근 모서리의 Rectangle 항목 세 개를 배열합니다. spacing 속성은 직사각형들 사이에 약간의 간격을 두도록 설정되어 있습니다.

수평으로 중앙 정렬된 행(Row) 항목의 가장자리 주변에 약간의 공간이 남도록 부모 사각형(Rectangle)의 크기를 충분히 크게 설정합니다.

import QtQuick

Rectangle {
    width: 320; height: 110
    color: "#c0c0c0"

    Row {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter

        spacing: 5

        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "#024c1c" }
        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "#42a51c" }
        Rectangle { width: 100; height: 100; radius: 20.0
                    color: "white" }
    }
}

Grid 항목

간격을 둔 2×2 격자 안에 있는 네 개의 색깔이 있는 직사각형

Grid 항목은 그리드나 표 형태로 항목을 배치하는 데 사용됩니다. 다음 예제에서는 Grid 항목을 사용하여 4개의 Rectangle 항목을 2×2 그리드에 배치합니다. 다른 배치 도구와 마찬가지로, 항목 간의 간격은 spacing 속성을 사용하여 지정할 수 있습니다.

import QtQuick

Rectangle {
    width: 112; height: 112
    color: "#303030"

    Grid {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
        columns: 2
        spacing: 6

        Rectangle { color: "#aa6666"; width: 50; height: 50 }
        Rectangle { color: "#aaaa66"; width: 50; height: 50 }
        Rectangle { color: "#9999aa"; width: 50; height: 50 }
        Rectangle { color: "#6666aa"; width: 50; height: 50 }
    }
}

항목 사이에 삽입되는 수평 및 수직 간격에는 차이가 없으므로, 추가적인 공간은 항목 내부에서 직접 확보해야 합니다.

그리드 내의 빈 셀은 그리드 정의에서 적절한 위치에 자리 표시자 항목을 정의하여 만들어야 합니다.

흐름 항목

좁은 Flow 컨테이너로 감싸진 텍스트 항목들 더 넓은 Flow 컨테이너로 감싸인 텍스트 항목들

Flow 항목은 단어와 같은 항목을 페이지에 배치하는 데 사용되며, 항목들이 겹치지 않게 행이나 열로 배열됩니다.

흐름 항목(Flow items)은 그룹 항목( Grid )과 유사한 방식으로 항목을 배열하며, 항목은 한 축(부축)을 따라 줄로 배열되고, 항목의 줄은 다른 축(주축)을 따라 서로 나란히 배치됩니다. 흐름의 방향과 항목 간의 간격은 flow 및 spacing 속성으로 제어됩니다.

다음 예제는 여러 개의 Text 자식 항목을 포함하는 Flow 항목을 보여줍니다. 이 항목들은 스크린샷에 표시된 것과 유사한 방식으로 배열되어 있습니다.

import QtQuick

Rectangle {
    color: "lightblue"
    width: 300; height: 200

    Flow {
        anchors.fill: parent
        anchors.margins: 4
        spacing: 10

        Text { text: "Text"; font.pixelSize: 40 }
        Text { text: "items"; font.pixelSize: 40 }
        Text { text: "flowing"; font.pixelSize: 40 }
        Text { text: "inside"; font.pixelSize: 40 }
        Text { text: "a"; font.pixelSize: 40 }
        Text { text: "Flow"; font.pixelSize: 40 }
        Text { text: "item"; font.pixelSize: 40 }
    }
}

Grid와 Flow 배치기의 주요 차이점은, Flow 내의 항목은 부축(minor axis)의 공간이 부족해지면 줄바꿈(wrap)되며, 항목의 크기가 균일하지 않은 경우 한 줄의 항목이 다른 줄의 항목과 정렬되지 않을 수 있다는 점입니다. Grid 항목과 마찬가지로, 항목 간 간격이나 항목 줄 간 간격을 독립적으로 제어할 수는 없습니다.

항목을 배치하는 다른 방법

사용자 인터페이스에서 항목의 위치를 지정하는 방법에는 여러 가지가 있습니다. 좌표를 직접 지정하는 기본적인 기술 외에도, 앵커를 사용하여 다른 항목에 상대적으로 위치를 지정하거나, 객체 모델(Object Model)과 같은 QML 데이터 모델과 함께 사용할 수 있습니다.

앵커를 이용한 배치 오른쪽에서 왼쪽으로 진행되는 사용자 인터페이스

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