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 でレンダリング可能なフラットなテーブルモデルに変換しています。ツリー内の各ノードは、最終的にテーブルの1行を占めることになり、その最初の列がツリー自体をレンダリングします。 その列内の各デリゲート項目を、モデルにおける親子関係の深さに応じてインデントすることで、技術的には依然として単なる平坦な項目のリストであっても、結果としてツリーのように見えるようになります。

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 コントロール - 目次」を参照してください。

ツリーノードのカスタマイズ

柔軟性を高めるため、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 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によって設定され、アタッチドプロパティに類似しています。これらを必須（required）としてマークすることで、デリゲートは間接的にTreeViewに対し、それらの値の割り当てを担当すべきであることを通知します。デリゲートには、以下の必須プロパティを追加できます：

• required property TreeView treeView - デリゲート・アイテムを含むTreeViewを指します。
• required property bool isTreeNode - デリゲート項目がツリー内のノードを表す場合、true となります。ツリーの描画にはビュー内の1つの列のみが使用されるため、その列にあるデリゲート項目のみ、このプロパティが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 は、モデル内の行ではなく、ビュー内の行（テーブルの行）である必要があります。