syncfusion-winforms-treeview

Windows Forms での TreeView の実装

このスキルを使用するタイミング

次の場合は、必ずすぐにこのスキルを使用してください。

• 階層データをツリー構造で表示する必要がある
• ファイルエクスプローラー、フォルダーブラウザー、ディレクトリナビゲーションを構築する
• 組織図、カテゴリーツリー、またはネストされたメニューを実装する
• 展開／折りたたみ可能なノードを持つ親子関係が必要である
• 自己参照データまたはデータリレーションを扱う
• ツリーノードのドラッグ＆ドロップによる並べ替えが必要である
• 挿入／削除／名前変更の操作が可能な編集可能なツリー構造を実装する
• 大規模なツリーデータセット（1000 以上のノード）のパフォーマンス最適化が必要である
• ユーザーが TreeView、階層データ、ツリー構造、展開可能なノード、親子関係について言及する

コンポーネントの概要

Syncfusion TreeViewAdv コントロールは、標準の Windows Forms TreeView よりも高度な機能を備えたツリー構造で階層データを表示します。データバインディング、ドラッグ＆ドロップ、仮想化、編集、幅広いカスタマイズオプションを包括的にサポートします。

主な機能

• 高度なデータバインディング： 自己参照、データリレーション、オブジェクトリレーショナルバインディング
• ドラッグ＆ドロップ： 視覚的なフィードバックと検証を備えた完全なドラッグ＆ドロップサポート
• パフォーマンス： 20,000 以上のノードを最小限の遅延で処理する仮想化
• ノードのカスタマイズ： チェックボックス、オプションボタン、画像、カスタムスタイル
• 編集操作： データソースとの同期を伴う動的な挿入、削除、名前変更
• オンデマンド読み込み： パフォーマンス向上のための子ノードの遅延読み込み
• 豊富な外観： テーマ、カスタムスタイル、境界線、色、フォント
• 高度な機能： 検索／置換、履歴マネージャー（元に戻す／やり直し）、XML 永続化、印刷
• 複数選択： 複数ノードの選択に対応した CTRL+SHIFT キー
• コンテキストメニュー： 表示／非表示オプションを指定したメニューの関連付け

一般的なユースケース

• ファイル／フォルダーブラウザーのインターフェイス
• 組織階層の表示
• カテゴリー／サブカテゴリーのナビゲーション
• プロジェクト／タスクのツリー構造
• 設定／構成のツリー
• XML／JSON データの可視化
• データベーステーブルのリレーション
• 複数階層のメニューシステム

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• デザイナーを使用したコントロールの追加（ツールボックスからのドラッグ＆ドロップ）
• C# および VB.NET でのコントロールの手動追加
• TreeViewAdv インスタンスの作成
• NodeCollection エディターによるノードの追加
• プログラムによるノードの追加
• 基本的なノードのカスタマイズ（線、プラス／マイナス記号）
• アクティブノードの割り当て

データバインディング

📄 参照： references/data-binding.md

• 自己参照データ（親子関係を持つ単一テーブル）へのバインド
• ParentMember、ChildMember、SelfRelationRootValue プロパティ
• データリレーション（関連する複数のテーブル）へのバインド
• オブジェクトリレーショナルデータ（カスタムオブジェクト）へのバインド
• DataSource、DisplayMember、ValueMember の構成
• データソースの変更に合わせたツリーの同期

ノードのカスタマイズ

📄 参照： references/node-customization.md

• ルート線と接続線（ShowLines、ShowRootLines）
• 親ノードのプラス／マイナス記号
• 展開状態を示す ShowPlusOnExpand
• ノード選択用の CheckBoxes（ShowCheckBoxes）
• ラジオボタン形式の選択用 OptionButtons
• ノードレベルとコントロールレベルのプロパティ
• 展開／折りたたみ状態用の画像
• 左側、右側、状態画像の各ソース

外観とスタイル設定

📄 参照： references/appearance-styling.md

• 境界線のカスタマイズ（BorderStyle、BorderSingle、BorderColor）
• 2D と 3D の境界線（FixedSingle、Fixed3D）
• 境界線のスタイル（Solid、Dashed、Dotted、Inset、Outset）
• ノードの外観（フォント、色、背景）
• グローバルスタイルとノード固有のスタイル
• TreeNodeAdv のカスタマイズプロパティ
• スタイルアーキテクチャの概要
• テーマのサポートと Office 風のスタイル設定

ドラッグ アンド ドロップ

📄 読む： references/drag-and-drop.md

• ドラッグ アンド ドロップ機能の概要
• ドラッグ アンド ドロップのイベント処理（DragDrop、DragEnter、DragLeave、DragOver）
• ドラッグ操作を開始する ItemDrag イベント
• GiveFeedback イベントと QueryContinueDrag イベント
• カスタムのドラッグ フィードバックと検証
• 高度なドラッグ アンド ドロップのシナリオ
• コントロール間のドラッグ アンド ドロップのサポート

編集操作

📄 読む： references/editing-operations.md

• 動的な更新（挿入、削除、名前変更）
• データソースとの同期
• GridGroupingControl の統合
• 実行時のノード操作
• データ更新の AcceptChanges パターン
• 変更の双方向反映

並べ替え

📄 読む： references/sorting.md

• 実行時の並べ替え機能
• 並べ替えのメソッドとプロパティ
• カスタムの並べ替えロジック
• データバインディングでの並べ替え
• パフォーマンスに関する考慮事項

オンデマンド読み込み

📄 読む： references/load-on-demand.md

• LoadOnDemand 機能の概要
• パフォーマンス向上のための遅延読み込み
• BeforeExpand イベントの処理
• サブノードの動的な追加
• ノードパスを取得する GetPath メソッド
• AddSeparatorAtEnd プロパティ

パフォーマンスの最適化

📄 読む： references/performance-optimization.md

• 大規模なデータセット向けの EnableVirtualization
• 仮想化のメリット（20,000+ ノード）
• SuspendExpandRecalculate による最適化
• RecalculateExpansion プロパティ
• 大規模なツリーのベストプラクティス
• パフォーマンスのベンチマーク

高度な機能

📄 読む： references/advanced-features.md

• 検索と置換の機能
• 検索機能
• History Manager（元に戻す／やり直し操作）
• XML の保存と読み込み（永続化）
• 印刷のサポートとカスタマイズ
• 表示／非表示のオプションを備えたコンテキストメニュー
• CTRL+SHIFT キーによる複数選択

スクロールバーのカスタマイズ

📄 読む： references/scrollbar-customization.md

• ScrollBar のプロパティと設定
• 自動スクロールのサポート
• スクロールバーの外観のカスタマイズ
• スクロール動作の設定

クイックスタートの例

基本的な TreeView の設定

using Syncfusion.Windows.Forms.Tools;

namespace WinFormsTreeApp
{
    public partial class Form1 : Form
    {
        private TreeViewAdv treeViewAdv1;
        
        public Form1()
        {
            InitializeComponent();
            InitializeTreeView();
        }
        
        private void InitializeTreeView()
        {
            // Create TreeViewAdv instance
            treeViewAdv1 = new TreeViewAdv();
            treeViewAdv1.Location = new System.Drawing.Point(20, 20);
            treeViewAdv1.Size = new System.Drawing.Size(300, 400);
            
            // Create nodes
            TreeNodeAdv parentNode1 = new TreeNodeAdv("Parent 1");
            TreeNodeAdv childNode1 = new TreeNodeAdv("Child 1");
            TreeNodeAdv childNode2 = new TreeNodeAdv("Child 2");
            
            // Build hierarchy
            parentNode1.Nodes.AddRange(new TreeNodeAdv[] { childNode1, childNode2 });
            
            TreeNodeAdv parentNode2 = new TreeNodeAdv("Parent 2");
            TreeNodeAdv childNode3 = new TreeNodeAdv("Child 3");
            parentNode2.Nodes.Add(childNode3);
            
            // Add root nodes
            treeViewAdv1.Nodes.AddRange(new TreeNodeAdv[] { parentNode1, parentNode2 });
            
            // Customize appearance
            treeViewAdv1.ShowLines = true;
            treeViewAdv1.ShowRootLines = true;
            treeViewAdv1.ShowPlusMinus = true;
            
            // Add to form
            this.Controls.Add(treeViewAdv1);
        }
    }
}

データバインディングの例

// Self-referencing data binding
DataTable dataTable = CreateHierarchicalData();

treeViewAdv1.DataSource = dataTable;
treeViewAdv1.DisplayMember = "Name";
treeViewAdv1.ValueMember = "ID";
treeViewAdv1.ParentMember = "ParentID";
treeViewAdv1.ChildMember = "ID";
treeViewAdv1.SelfRelationRootValue = DBNull.Value;

一般的なパターン

パターン 1：プログラムによるノードの作成

用途： コードからツリー構造を動的に構築する場合

// Create nodes with constructor
TreeNodeAdv node = new TreeNodeAdv("Node Text");

// Set properties
node.Text = "Updated Text";
node.ShowCheckBox = true;
node.Tag = customDataObject;

// Add children
node.Nodes.Add(new TreeNodeAdv("Child"));

// Add to tree
treeViewAdv1.Nodes.Add(node);

パターン 2：自己参照データバインディング

用途： 親子関係を持つ単一のテーブルにバインドする場合

// Setup data source
treeViewAdv1.DataSource = employeeTable;
treeViewAdv1.DisplayMember = "EmployeeName";
treeViewAdv1.ValueMember = "EmployeeID";
treeViewAdv1.ParentMember = "ManagerID";
treeViewAdv1.ChildMember = "EmployeeID";
treeViewAdv1.SelfRelationRootValue = DBNull.Value; // Root nodes have null parent

パターン 3：オンデマンド読み込み

用途： 大規模なデータセットを扱い、遅延読み込みが必要な場合

// Enable load on demand
treeViewAdv1.LoadOnDemand = true;

// Handle BeforeExpand to load children
treeViewAdv1.BeforeExpand += (sender, e) => 
{
    TreeNodeAdv node = e.Node;
    
    // Check if children already loaded
    if (node.Nodes.Count == 0)
    {
        // Load children from data source
        var children = LoadChildNodesFromDatabase(node.Tag);
        
        foreach (var child in children)
        {
            TreeNodeAdv childNode = new TreeNodeAdv(child.Name);
            childNode.Tag = child;
            node.Nodes.Add(childNode);
        }
    }
};

パターン 4：ドラッグ アンド ドロップによるノードの並べ替え

用途： ユーザーがドラッグ アンド ドロップでノードを並べ替える必要がある場合

// Enable drag-drop
treeViewAdv1.AllowDrop = true;

// Handle ItemDrag
treeViewAdv1.ItemDrag += (sender, e) => 
{
    if (e.Item is TreeNodeAdv node)
    {
        treeViewAdv1.DoDragDrop(node, DragDropEffects.Move);
    }
};

// Handle DragDrop
treeViewAdv1.DragDrop += (sender, e) => 
{
    TreeNodeAdv sourceNode = (TreeNodeAdv)e.Data.GetData(typeof(TreeNodeAdv));
    TreeNodeAdv targetNode = treeViewAdv1.GetNodeAtPoint(treeViewAdv1.PointToClient(new Point(e.X, e.Y)));
    
    if (targetNode != null && sourceNode != targetNode)
    {
        sourceNode.Remove();
        targetNode.Nodes.Add(sourceNode);
        targetNode.Expand();
    }
};

パターン 5：大規模なツリーのパフォーマンス最適化

用途： 1000+ 個のノードを扱い、読み込み時間が遅い場合

// Enable virtualization
treeViewAdv1.EnableVirtualization = true;

// Optimize expand/collapse
treeViewAdv1.SuspendExpandRecalculate = true;
treeViewAdv1.RecalculateExpansion = false;

// Suspend layout during bulk operations
treeViewAdv1.BeginUpdate();
try
{
    // Add thousands of nodes
    for (int i = 0; i < 10000; i++)
    {
        treeViewAdv1.Nodes.Add(new TreeNodeAdv($"Node {i}"));
    }
}
finally
{
    treeViewAdv1.EndUpdate();
}

主要なプロパティ

データバインディングのプロパティ

• DataSource - データソースオブジェクト（DataTable、List など）
• DisplayMember - ノードテキストの表示に使用するフィールド
• ValueMember - ノード値に使用するフィールド
• ParentMember - 自己参照用の親 ID フィールド
• ChildMember - 自己参照用の子 ID フィールド
• SelfRelationRootValue - ルートノードを示す値

外観のプロパティ

• ShowLines - ノード間をつなぐ線を表示する
• ShowRootLines - ルートノード間の線を表示する
• ShowPlusMinus - 展開／折りたたみボタンを表示する
• ShowCheckBoxes - ノードにチェックボックスを表示する
• ShowOptionButtons - オプションボタン（ラジオボタン形式）を表示する
• BorderStyle - 境界線のスタイル（None、FixedSingle、Fixed3D）

動作のプロパティ

• LoadOnDemand - 子ノードの遅延読み込みを有効にする
• AllowDrop - ドラッグ アンド ドロップ操作を有効にする
• EnableVirtualization - パフォーマンス向上のために仮想化を有効にする
• SuspendExpandRecalculate - 展開／折りたたみのパフォーマンスを最適化する
• RecalculateExpansion - 読み込み時のサイズ計算を制御する

ノードのプロパティ（TreeNodeAdv）

• Text - ノードの表示テキスト
• Tag - カスタムデータオブジェクト
• Checked - チェックボックスの状態
• Expanded - 展開／折りたたみの状態
• ShowCheckBox - このノードのチェックボックスを表示
• ShowPlusMinus - このノードのプラス／マイナスを表示

主なイベント

選択イベント

• AfterSelect - ノードの選択が変更された後
• BeforeSelect - ノードの選択が変更される前
• NodeSelected - ノードが選択されたときのイベント

展開／折りたたみイベント

• BeforeExpand - ノードが展開される前（オンデマンド読み込みに使用）
• AfterExpand - ノードが展開された後
• BeforeCollapse - ノードが折りたたまれる前
• AfterCollapse - ノードが折りたたまれた後

ドラッグ＆ドロップイベント

• ItemDrag - ノードのドラッグが開始されたとき
• DragDrop - 項目がコントロール上にドロップされたとき
• DragEnter - ドラッグがコントロールの領域に入ったとき
• DragOver - ドラッグがコントロールの領域上を移動しているとき

編集イベント

• BeforeEdit - ノードの編集が開始される前
• AfterEdit - ノードの編集が完了した後

よくある使用例

使用例 1：ファイルエクスプローラー

フォルダーとファイルを含む Windows エクスプローラー風のインターフェースを構築します：

• ディレクトリの参照にはオンデマンド読み込みを使用します
• LeftImageList でフォルダー／ファイルのアイコンを追加します
• ダブルクリックでファイルを開く処理を実装します
• ファイル操作用のコンテキストメニューを実装します

使用例 2：組織図

従業員を含む会社の階層を表示します：

• 自己参照データを含む従業員テーブルにバインドします
• ノード画像として従業員の写真を表示します
• 複数選択操作用のチェックボックスを追加します
• 組織変更用のドラッグ＆ドロップを実装します

使用例 3：設定ツリー

階層構造の設定／環境設定インターフェースを作成します：

• ツリー構造で設定をカテゴリ別にグループ化します
• 単一選択の設定にはオプションボタンを使用します
• ブール値の設定にはチェックボックスを使用します
• XML 永続化を使用して設定を保存／読み込みします

使用例 4：データベーススキーマビジュアライザー

データベースのテーブルとリレーションシップを表示します：

• データベーススキーマをツリーに読み込みます
• テーブルを親ノード、列を子ノードとして表示します
• データ型を示すアイコンを追加します
• スキーマ検索用の検索／置換を有効にします

使用例 5：XML／JSON エディター

階層型データ形式用のビジュアルエディターです：

• XML／JSON をツリー構造に解析します
• ノード値のインライン編集を有効にします
• History Manager を使用して元に戻す／やり直す機能を実装します
• 変更を XML／JSON 形式に保存し直します

トラブルシューティング

問題： データバインド後にノードが表示されない

• 解決策： DataSource が null でないことを確認し、ParentMember／ChildMember が列名と一致することを確認して、SelfRelationRootValue がルートノードのパターンと一致するようにします

問題： 大規模なデータセットでパフォーマンスが遅い

• 解決策： EnableVirtualization を有効にし、遅延読み込みには LoadOnDemand を使用して、SuspendExpandRecalculate = true を設定します

問題： ドラッグ＆ドロップが機能しない

• 解決策： AllowDrop = true を設定し、ItemDrag および DragDrop のイベントハンドラーを実装して、DragDropEffects を確認します

問題： バインドされたデータソースに変更が反映されない

• 解決策： 変更後に DataTable で AcceptChanges() を呼び出し、DataSource バインドが有効であることを確認します

問題： 親ノードにプラス／マイナス記号が表示されない

• 解決策： ShowPlusMinus = true であることを確認し、ノードに子ノードがあることを確認します。LoadOnDemand の場合は ShowPlusOnExpand が設定されていることを確認します