Back to Qt.io
Contact Us Blog Download Qt

TreeView QML Type

QAbstractItemModel のデータを表示するツリービューを提供する。

Import Statement: import QtQuick
Since: Qt 6.3
Inherits:

TableView

プロパティ

シグナル

メソッド

詳細説明

TreeViewは、表示するデータを定義するモデルと、データをどのように表示するかを定義するデリゲートを持ちます。

TreeViewはTableView を継承します。これは、モデルが親子ツリー構造を持っていたとしても、TreeViewは内部的に、その構造をTableView によってレンダリング可能なフラットテーブルモデルに変換するプロキシモデルを使用していることを意味します。ツリーの各ノードはテーブルの1行を占め、最初の列がツリー自体をレンダリングします。その列の各デリゲートアイテムをモデル内の親子間の深さに従ってインデントすることで、技術的にはまだアイテムのフラットリストであっても、ツリーのように見えるようになります。

最大限の柔軟性を持たせるために、TreeView自体はデリゲートアイテムをツリー構造に配置しません。この責任はデリゲートにあります。Qt Quick Controlsは、このために使用できる既製の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 int 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
            }
        }
    }
}

カスタムツリーモデルの作成方法と使用方法の詳細については、Qt Quick Controls - Table of Contentsの例を参照してください。

required としてマークされたプロパティは、TreeViewによって入力され、アタッチされたプロパティに似ています。必須とマークされることで、デリゲートは間接的にTreeViewにそれらの値を割り当てる責任を負うように通知します。以下の必須プロパティをデリゲートに追加することができます：

  • required property TreeView treeView - デリゲートアイテムを含むTreeViewを指します。
  • required property bool isTreeNode - デリゲートアイテムがツリーのノードを表している場合、 。ツリーを描画するために使用されるのは、ビュー内の 1 つの列のみであるため、その列のデリゲートアイテムにのみ、このプロパティが に設定されます。ツリー内のノードは通常、 に従ってインデントされ、 が の場合はインジケータが表示されます。他の列のデリゲート・アイテムは、このプロパティが に設定され、モデル内の残りの列のデータを表示します（そして、通常はインデントされません）。true true depth hasChildren true false
  • required property bool expanded - デリゲートによって描画されたモデルアイテムがビューで展開される場合、 。true
  • required property bool hasChildren - デリゲートによって描画されたモデル項目がモデル内に子を持つ場合、 。true
  • required property int depth - デリゲートによって描画されたモデル項目の深さを含みます。モデル項目の深さは、モデル内に持つ祖先の数と同じです。

必須プロパティも参照してください。

デフォルトでは、TreeViewtoggles は、行をダブルタップすると、その行の展開状態を保持します。これは、セルを編集するためにダブルタップすることと矛盾するため、TreeViewはデフォルトでeditTriggers をTableView.EditKeyPressed に設定します（これは、TableView とは異なり、TableView.EditKeyPressed | TableView.DoubleTapped を使用します）。editTriggers をTableView.DoubleTapped も含むように変更すると、ダブルタップによる展開状態の切り替えは無効になります。

注: TreeViewは、QAbstractItemModel を継承するモデルのみを受け入れます。

プロパティ ドキュメント

rootIndex : QModelIndex [since 6.6]

このプロパティは、ツリーのルートアイテムのモデルインデックスを保持します。デフォルトでは、これはモデルのルートインデックスと同じですが、代わりに子インデックスに設定することで、ツリーの分岐のみを表示することができます。モデル全体を表示するには、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()も参照してください 。


[since 6.4] 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()も参照してください 。


expand(row)

ビューの指定されたrow にあるツリー・ノードを展開します。

row はビューの行（テーブルの行）でなければならず、モデルの行であってはなりません。

注意: この関数はモデルには影響せず、ビューでの視覚的な表現にのみ影響します。

collapse(),isExpanded(),expandRecursively()も参照してください 。


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

ビュー内の指定されたrow にあるツリーノードを、再帰的にdepth まで展開します。depth はrow の深さに対する相対値でなければなりません。depth が-1 の場合、ツリーはすべての葉まで展開されます。

複数のルートを持つモデルの場合、row を-1 と等しくしてこの関数を呼び出すこともできます。 これにより、すべてのルートが展開されます。したがって、expandRecursively(-1, -1)、または単に expandRecursively() を呼び出すと、モデル内のすべてのノードが展開されます。

row は、ビューの行 (テーブルの行) でなければならず、モデルの行であってはなりません。

注意: この関数はfetch more データを試行しません。

注意: この関数はモデルには影響せず、ビューでの視覚的な表現にのみ影響します。

警告 モデルに多数の項目が含まれている場合、この関数の実行には時間がかかります。

このメソッドは Qt 6.4 で導入されました。

collapseRecursively(),expand(),collapse(),isExpanded(),depth()も参照してください 。


[since 6.4] 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


toggleExpanded(row)

指定されたrow のツリーノードを展開するかどうかを切り替えます。これは便利な機能です：

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

row はビューの行（テーブルの行）でなければならず、モデルの行であってはなりません。


このドキュメントに含まれるコントリビューションの著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。