TreeView QML Type
QAbstractItemModel...의 데이터를 표시하는 트리 보기를 제공합니다... .
Import Statement: | import QtQuick |
Since: | Qt 6.3 |
Inherits: |
속성
- rootIndex : QModelIndex
(since 6.6)
신호
방법
- collapse(row)
- collapseRecursively(row)
(since 6.4)
- int depth(row)
- expand(row)
- expandRecursively(row, depth)
(since 6.4)
- expandToIndex(QModelIndex index)
(since 6.4)
- bool isExpanded(row)
- toggleExpanded(row)
상세 설명
트리뷰에는 표시할 데이터를 정의하는 모델과 데이터를 표시하는 방법을 정의하는 델리게이트가 있습니다.
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 {} }
데이터 모델 만들기
트리뷰는 QAbstractItemModel 을 상속하는 모델만 허용합니다.
사용자 지정 트리 모델을 만들고 사용하는 방법에 대한 자세한 내용은 예제 Qt Quick Controls - 목차를 참조하세요.
트리 노드 사용자 지정
유연성을 높이기 위해 TreeView 자체는 델리게이트 항목을 트리 구조에 배치하지 않습니다. 이 부담은 델리게이트에게 있습니다. Qt Quick Controls 는 이를 위해 사용할 수 있는 기성품 TreeViewDelegate 을 제공하며, 이 트리는 즉시 작동하고 애플리케이션이 실행되는 플랫폼의 스타일을 따르는 트리를 렌더링한다는 장점이 있습니다.
TreeViewDelegate 을 사용자 정의할 수 있더라도 트리를 다른 방식으로 렌더링하거나 성능상의 이유로 델리게이트를 가능한 한 최소한으로 만들고 싶은 경우가 있을 수 있습니다. 트리뷰는 트리의 각 노드를 올바르게 배치하고 렌더링하는 데 사용할 수 있는 일련의 속성을 제공하므로 자신만의 델리게이트를 처음부터 쉽게 만들 수 있습니다.
애니메이션 표시기가 있는 사용자 지정 델리게이트의 예는 아래와 같습니다:
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에 의해 채워지며, 첨부된 프로퍼티와 유사합니다. 필수로 표시함으로써 델리게이트는 TreeView에 간접적으로 값을 할당할 책임이 있음을 알립니다. 델리게이트에 추가할 수 있는 필수 프로퍼티는 다음과 같습니다:
required property 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
- 델리게이트에 의해 그려진 모델 항목의 깊이를 포함합니다. 모델 항목의 깊이는 모델에 있는 조상 수와 동일합니다.
필수 속성도 참조하세요.
최종 사용자 상호 작용
기본적으로 트리뷰는 행을 두 번 탭하면 행의 확장된 상태를 toggles 표시합니다. 이는 셀을 두 번 탭하여 편집하는 것과 충돌하므로 TreeView는 기본적으로 editTriggers 을 TableView.EditKeyPressed
으로 설정합니다( TableView.EditKeyPressed | TableView.DoubleTapped
을 사용하는 TableView 과는 다릅니다). editTriggers 을 TableView.DoubleTapped
도 포함하도록 변경하면 두 번 탭으로 확장 상태를 전환하는 기능이 비활성화됩니다.
속성 문서
rootIndex : QModelIndex |
이 속성은 트리에서 루트 항목의 모델 인덱스를 보유합니다. 기본적으로 이 인덱스는 모델의 루트 인덱스와 동일하지만 대신 하위 인덱스로 설정하여 트리의 가지만 표시할 수 있습니다. 전체 모델을 표시하려면 undefined
로 설정합니다.
이 속성은 Qt 6.6에 도입되었습니다.
신호 문서
collapsed(row, recursively) |
이 신호는 뷰에서 row 가 접힐 때 발생합니다. row 은 접힘을 발생시킨 호출에 주어진 인수(collapse() 또는 collapseRecursively())와 동일합니다. 행이 재귀적으로 축소된 경우 recursively 은 true
이 됩니다.
참고: 행이 재귀적으로 축소된 경우, 축소된 신호는 해당 행에 대해서만 발생하고 그 하위 행에는 발생하지 않습니다.
참고: 해당 핸들러는 onCollapsed
입니다.
expanded(), expand(), collapse() 및 toggleExpanded()도 참조하세요 .
expanded(row, depth) |
이 신호는 뷰에서 row 가 확장될 때 발생합니다. row 및 depth 는 확장을 발생시킨 호출에 주어진 인수(expand() 또는 expandRecursively())와 동일합니다. expand ()의 경우 depth 은 항상 1
이 됩니다. expandToIndex ()의 경우 depth 은 대상 인덱스의 깊이가 됩니다.
참고: 행이 재귀적으로 확장되면 확장된 신호는 해당 행에 대해서만 방출되고 그 하위 행에는 방출되지 않습니다.
참고: 해당 핸들러는 onExpanded
입니다.
collapsed(), expand(), collapse(), toggleExpanded()도 참조하세요 .
메서드 문서
collapse(row) |
뷰의 지정된 row 에서 트리 노드를 축소합니다.
row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다.
참고: 이 함수는 모델에는 영향을 주지 않으며 뷰의 시각적 표현에만 영향을 줍니다.
expand() 및 isExpanded()도 참조하세요 .
|
뷰에서 지정된 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()도 참조하세요 .
expand(row) |
뷰의 지정된 row 에서 트리 노드를 확장합니다.
row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다.
참고: 이 함수는 모델에는 영향을 주지 않으며 뷰의 시각적 표현에만 영향을 줍니다.
collapse(), isExpanded() 및 expandRecursively()도 참조하십시오 .
|
뷰에서 지정된 row 의 트리 노드를 depth 까지 재귀적으로 확장합니다. depth 는 row 의 깊이를 기준으로 해야 합니다. depth 가 -1
인 경우 트리는 모든 잎까지 확장됩니다.
루트가 두 개 이상인 모델의 경우 row 을 -1
과 같이 사용하여 이 함수를 호출할 수도 있습니다. 그러면 모든 루트가 확장됩니다. 따라서 확장 재귀적으로(-1, -1) 또는 간단히 확장 재귀적으로()를 호출하면 모델의 모든 노드가 확장됩니다.
row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다.
참고: 이 함수는 fetch more 데이터를 시도하지 않습니다.
참고: 이 함수는 모델에는 영향을 주지 않으며 뷰의 시각적 표현에만 영향을 줍니다.
경고: 모델에 많은 수의 항목이 포함된 경우 이 함수를 실행하는 데 시간이 다소 걸릴 수 있습니다.
이 메서드는 Qt 6.4에 도입되었습니다.
collapseRecursively(), expand(), collapse(), isExpanded() 및 depth()도 참조하십시오 .
|
주어진 모델 index 에서 트리를 확장하고 루트까지 재귀적으로 확장합니다. 그 결과 index 을 나타내는 델리게이트 항목이 뷰에 표시됩니다(뷰포트 외부로 나오지 않는 한). 행이 뷰포트에 표시되도록 하려면 다음과 같이 할 수 있습니다:
expandToIndex(index) forceLayout() positionViewAtRow(rowAtIndex(index), Qt.AlignVCenter)
이 메서드는 Qt 6.4에 도입되었습니다.
expand() 및 expandRecursively()도 참조하십시오 .
bool isExpanded(row) |
뷰에서 지정된 row 이 확장된 상태로 표시되면 반환합니다.
row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다. row 이 0
과 rows 사이에 있지 않은 경우 반환 값은 false
입니다.
toggleExpanded(row) |
지정된 row 의 트리 노드를 확장할지 여부를 토글합니다. 이는 편의를 위한 것입니다:
if (isExpanded(row)) collapse(row) else expand(row)
row 는 모델의 행이 아니라 뷰의 행(테이블 행)이어야 합니다.
© 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.