TreeView QML Type

QAbstractItemModel 의 데이터를 표시하는 트리 뷰를 제공합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• rootIndex : QModelIndex (since 6.6)

신호

• collapsed(row, recursively)
• expanded(row, depth)

방법

• void collapse(row)
• void collapseRecursively(row) (since 6.4)
• int depth(row)
• void expand(row)
• void expandRecursively(row, depth) (since 6.4)
• void expandToIndex(QModelIndex index) (since 6.4)
• bool isExpanded(row)
• void toggleExpanded(row)

상세 설명

TreeView에는 표시할 데이터를 정의하는 데이터 모델( model )과 데이터의 표시 방식을 정의하는 스타일 모델( delegate )이 있습니다.

TreeView는 TableView 을 상속받습니다. 즉, 모델이 부모-자식 트리 구조를 가지고 있음에도 불구하고, TreeView는 내부적으로 해당 구조를 TableView 으로 렌더링할 수 있는 평면 테이블 모델로 변환하는 프록시 모델을 사용합니다. 트리의 각 노드는 테이블에서 한 행을 차지하게 되며, 첫 번째 열은 트리 자체를 렌더링합니다. 해당 열에 있는 각 델리게이트 항목을 모델 내의 부모-자식 관계 깊이에 따라 들여쓰기하면, 기술적으로는 여전히 평면적인 항목 목록일지라도 결과적으로 트리처럼 보이게 됩니다.

TreeView 선언

TreeView는 데이터 바인딩 컨트롤이므로 데이터 모델이 없으면 아무것도 표시할 수 없습니다. QML에서는 트리 노드를 직접 선언할 수 없습니다.

TreeView를 선언할 때는 다음을 지정해야 합니다:

• 데이터 모델. TreeView는 ` QAbstractItemModel`을 상속한 데이터 모델과 연동할 수 있습니다.
• 델리게이트. 델리게이트는 UI에서 트리 노드가 어떻게 표시될지를 지정하는 템플릿입니다.

TreeView {
    // The model needs to be a QAbstractItemModel
    model: myTreeModel
    // You can set a custom delegate or use a built-in TreeViewDelegate
    delegate: TreeViewDelegate {}
}

데이터 모델 생성

TreeView는 QAbstractItemModel 을 상속하는 모델만 허용합니다.

사용자 지정 트리 모델을 만들고 사용하는 방법에 대한 자세한 내용은 예제 ‘Qt Quick Controls - 목차’를 참조하십시오.

트리 노드 사용자 지정

유연성을 높이기 위해 TreeView 자체는 델리게이트 항목을 트리 구조에 배치하지 않습니다. 이 작업은 델리게이트가 담당합니다. Qt Quick Controls TreeView는 이를 위해 바로 사용할 수 있는 TreeViewDelegate 를 제공하며, 이 모델은 별도의 설정 없이 바로 작동하고 애플리케이션이 실행되는 플랫폼의 스타일에 따라 트리를 렌더링한다는 장점이 있습니다.

TreeViewDelegate 는 사용자 정의가 가능하지만, 성능상의 이유로 트리를 다른 방식으로 렌더링하거나 델리게이트를 가능한 한 최소한으로 유지하고 싶은 경우가 있을 수 있습니다. TreeView는 트리 내 각 노드를 올바르게 배치하고 렌더링하는 데 사용할 수 있는 일련의 속성을 제공하므로, 처음부터 직접 델리게이트를 만드는 것은 쉽습니다.

애니메이션 표시기가 포함된 사용자 정의 델리게이트의 예는 다음과 같습니다:

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 800
    height: 600
    visible: true

    TreeView {
        id: treeView
        anchors.fill: parent
        anchors.margins: 10
        clip: true

        selectionModel: ItemSelectionModel {}

        // The model needs to be a QAbstractItemModel
        // model: yourTreeModel

        delegate: Item {
            implicitWidth: padding + label.x + label.implicitWidth + padding
            implicitHeight: label.implicitHeight * 1.5

            readonly property real indentation: 20
            readonly property real padding: 5

            // Assigned to by TreeView:
            required property TreeView treeView
            required property bool isTreeNode
            required property bool expanded
            required property bool hasChildren
            required property int depth
            required property int row
            required property int column
            required property bool current

            // Rotate indicator when expanded by the user
            // (requires TreeView to have a selectionModel)
            property Animation indicatorAnimation: NumberAnimation {
                target: indicator
                property: "rotation"
                from: expanded ? 0 : 90
                to: expanded ? 90 : 0
                duration: 100
                easing.type: Easing.OutQuart
            }
            TableView.onPooled: indicatorAnimation.complete()
            TableView.onReused: if (current) indicatorAnimation.start()
            onExpandedChanged: indicator.rotation = expanded ? 90 : 0

            Rectangle {
                id: background
                anchors.fill: parent
                color: row === treeView.currentRow ? palette.highlight : "black"
                opacity: (treeView.alternatingRows && row % 2 !== 0) ? 0.3 : 0.1
            }

            Label {
                id: indicator
                x: padding + (depth * indentation)
                anchors.verticalCenter: parent.verticalCenter
                visible: isTreeNode && hasChildren
                text: "▶"

                TapHandler {
                    onSingleTapped: {
                        let index = treeView.index(row, column)
                        treeView.selectionModel.setCurrentIndex(index, ItemSelectionModel.NoUpdate)
                        treeView.toggleExpanded(row)
                    }
                }
            }

            Label {
                id: label
                x: padding + (isTreeNode ? (depth + 1) * indentation : 0)
                anchors.verticalCenter: parent.verticalCenter
                width: parent.width - padding - x
                clip: true
                text: model.display
            }
        }
    }
}

required 로 표시된 속성은 TreeView에 의해 자동으로 채워지며, 첨부 속성(attached properties)과 유사합니다. 이러한 속성을 필수(required)로 표시함으로써, 델리게이트는 TreeView가 해당 속성에 값을 할당할 책임을 져야 함을 간접적으로 알립니다. 델리게이트에는 다음과 같은 필수 속성을 추가할 수 있습니다:

• required property TreeView treeView - 델리게이트 항목을 포함하는 TreeView를 가리킵니다.
• required property bool isTreeNode - 델리게이트 항목이 트리 내의 노드를 나타내는 경우 ` true `입니다. 뷰의 단일 열만 트리 그리기에 사용되므로, 해당 열에 있는 델리게이트 항목에만 이 속성이 ` true`로 설정됩니다. 트리 내의 노드는 일반적으로 해당 노드의 ‘ depth ’에 따라 들여쓰기가 적용되어야 하며, ‘ hasChildren ’가 ‘ true ’인 경우 표시기를 보여야 합니다. 다른 열에 있는 델리게이트 항목의 경우 이 속성이 ‘ false ’로 설정되며, 모델의 나머지 열에 있는 데이터를 표시합니다(일반적으로 들여쓰기는 적용되지 않음).
• required property bool expanded - 델리게이트가 그리는 모델 항목이 뷰에서 확장된 경우 true 입니다.
• required property bool hasChildren - 델리게이트가 그린 모델 항목이 모델 내에 자식 항목을 가지고 있는 경우 true 입니다.
• required property int depth - 델리게이트가 그린 모델 항목의 깊이를 포함합니다. 모델 항목의 깊이는 모델 내에서 해당 항목이 가진 조상의 수와 같습니다.

‘필수 속성’ 항목도 참조하십시오.

최종 사용자 상호 작용

기본적으로 TreeView는 행을 더블 탭할 때 해당 행의 확장 상태를 toggles 합니다. 이는 셀 편집을 위한 더블 탭 동작과 충돌하므로, TreeView는 기본적으로 editTriggers 를 TableView.EditKeyPressed 로 설정합니다(이는 TableView.EditKeyPressed | TableView.DoubleTapped 를 사용하는 TableView 와는 다릅니다). editTriggers 를 TableView.DoubleTapped 도 포함하도록 변경하면, 더블 탭을 통한 확장 상태 전환 기능이 비활성화됩니다.

속성 설명서

rootIndex : QModelIndex [since 6.6]

이 속성은 트리 내 루트 항목의 모델 인덱스를 저장합니다. 기본적으로 이 값은 모델의 루트 인덱스와 동일하지만, 트리의 특정 분기만 표시하려면 대신 자식 인덱스로 설정할 수 있습니다. 전체 모델을 표시하려면 이 값을 ` undefined `로 설정하십시오.

이 속성은 Qt 6.6에서 도입되었습니다.

신호 문서

collapsed(row, recursively)

이 신호는 뷰에서 행( row )이 접힐 때 발생합니다. ` row `는 접힘을 유발한 호출에 전달된 인자와 동일합니다(`collapse()` 또는 ` collapseRecursively()`). 행이 재귀적으로 접힌 경우, ` recursively `는 ` true`가 됩니다.

또한 expanded(), expand(), collapse(), toggleExpanded()을참조하십시오 .

expanded(row, depth)

이 신호는 뷰에서 ` row `가 확장될 때 발생합니다. ` row `와 ` depth `는 확장을 유발한 호출(`expand()` 또는 ` expandRecursively()`)에 전달된 인자와 동일합니다. ` expand()`의 경우, ` depth `는 항상 ` 1`가 됩니다. ` expandToIndex()`의 경우, ` depth `는 대상 인덱스의 깊이가 됩니다.

collapsed(), expand(), collapse() 및 toggleExpanded()도 참조하십시오 .

메서드 문서

void collapse(row)

뷰에서 지정된 row 에 있는 트리 노드를 접습니다.

row 여기서 `xml-ph-0000@deepl.internal`는 뷰의 행(테이블 행)을 의미하며, 모델의 행을 가리키는 것이 아닙니다.

expand() 및 isExpanded()도 참조하십시오 .

[since 6.4] void collapseRecursively(row = -1)

뷰에서 지정된 row 에 있는 트리 노드를 모든 잎 노드까지 재귀적으로 접습니다.

모델에 루트가 두 개 이상인 경우, ` row `을 ` -1`으로 설정하여 이 함수를 호출할 수도 있습니다. 이렇게 하면 모든 루트가 접힙니다. 따라서 `collapseRecursively(-1)` 또는 간단히 `collapseRecursively()`를 호출하면 모델의 모든 노드가 접힙니다.

row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다.

이 메서드는 Qt 6.4에서 도입되었습니다.

expandRecursively(), expand(), collapse(), isExpanded() 및 depth()도 참조하십시오 .

int depth(row)

주어진 row 의 깊이(루트까지의 상위 노드 수)를 반환합니다.

row row 는 모델의 행이 아닌 뷰(테이블 행)의 행이어야 합니다. 가 와 사이에 속하지 않는 경우, 반환 값은 가 됩니다. 0 rows -1

modelIndex()도 참조하십시오 .

void expand(row)

뷰에서 지정된 위치( row )에 있는 트리 노드를 펼칩니다.

row 여기서 `xml-ph-0000@deepl.internal`는 모델의 행이 아닌 뷰(테이블 행)의 행이어야 합니다.

collapse(), isExpanded(), expandRecursively()도 참조하십시오 .

[since 6.4] void expandRecursively(row = -1, depth = -1)

뷰에서 지정된 row 에 있는 트리 노드를 depth 까지 재귀적으로 확장합니다. depth 는 row 의 깊이를 기준으로 한 상대 경로여야 합니다. depth 가 -1 인 경우, 트리는 모든 잎 노드까지 완전히 확장됩니다.

루트가 두 개 이상인 모델의 경우, row 을 -1 으로 설정하여 이 함수를 호출할 수도 있습니다. 이렇게 하면 모든 루트가 확장됩니다. 따라서 expandRecursively(-1, -1) 또는 간단히 expandRecursively()를 호출하면 모델 내의 모든 노드가 확장됩니다.

row 는 모델의 행이 아니라 뷰(테이블 행)의 행이어야 합니다.

이 메서드는 Qt 6.4에서 도입되었습니다.

collapseRecursively(), expand(), collapse(), isExpanded() 및 depth()도 참조하십시오 .

[since 6.4] void expandToIndex(QModelIndex index)

지정된 모델 index 을 기반으로 트리를 확장하여 루트까지 재귀적으로 처리합니다. 그 결과, index 를 나타내는 델리게이트 항목이 뷰에 표시됩니다(뷰포트 밖으로 벗어나지 않는 한). 행이 뷰포트 내에 표시되도록 하려면 다음과 같이 할 수 있습니다:

expandToIndex(index)
forceLayout()
positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)

이 메서드는 Qt 6.4에서 도입되었습니다.

expand() 및 expandRecursively()도 참조하십시오 .

bool isExpanded(row)

뷰에서 지정된 ` row `가 확장된 상태로 표시되는지 여부를 반환합니다.

row row 는 모델의 행이 아닌 뷰의 행(테이블 행)이어야 합니다. 가 과 사이에 있지 않은 경우, 반환 값은 가 됩니다. 0 rows false

void toggleExpanded(row)

지정된 row 에 있는 트리 노드를 펼칠지 여부를 전환합니다. 이는 다음 작업을 편리하게 수행하기 위한 기능입니다:

if (isExpanded(row))
    collapse(row)
else
    expand(row)

row 여기서 `xml-ph-0000@deepl.internal`는 뷰의 행(테이블 행)이어야 하며, 모델의 행이 아니어야 합니다.