syncfusion-winui-treegrid

Syncfusion WinUI TreeGrid の実装

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

次のような場合に、このスキルを使用します。

• 階層データまたは自己リレーションデータをツリー構造のグリッドに表示する
• 親子関係を持つデータグリッドを作成する
• 入れ子になったデータを含む、展開・折りたたみ可能な行を実装する
• グリッド形式で組織図や従業員階層を作成する
• グリッド機能を備えたファイルシステム構造を表示する
• カテゴリ階層、部品表、または入れ子になった分類を扱う
• ツリー構造のデータに高度なグリッド機能（並べ替え、フィルタリング、編集）を適用する
• 列ベースの表現で複数レベルのデータを可視化する

コンポーネントの概要

Syncfusion® WinUI TreeGrid（SfTreeGrid）は、自己リレーションデータまたは階層データをツリー構造で表示し、グリッド機能を備えたデータ指向のコントロールです。ツリービューの展開・折りたたみ可能なナビゲーションと、データグリッドの豊富な機能セットを組み合わせています。

コントロール名： SfTreeGrid
名前空間： Syncfusion.UI.Xaml.TreeGrid
NuGet パッケージ： Syncfusion.Grid.WinUI
プラットフォーム： WinUI 3（Windows App SDK）

主な機能

• データバインディング： 自己リレーションデータおよびネストされたコレクションに対応
• 列： 自動生成に対応した8種類の組み込み列
• 編集： 検証機能を備えた、すべての列タイプ向けの組み込みエディター
• 並べ替え： 単一列および複数列による並べ替え
• フィルタリング： Excel をイメージしたフィルター UI
• 選択： 行およびセルの選択モード
• ノード機能： チェックボックス、オンデマンド読み込み、展開・折りたたみ
• 行操作： ドラッグ＆ドロップ、セルの結合
• データ操作： クリップボード操作、Excel エクスポート
• スタイル設定： 条件付きスタイル設定、カスタムテンプレート
• 高度な機能： コンテキストメニュー、ツールチップ、MVVM 対応

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

はじめに

📄 参照： references/getting-started.md

• WinUI TreeGrid アプリケーションのセットアップ
• NuGet パッケージのインストール（Syncfusion.Grid.WinUI）
• 名前空間のインポートと基本的な初期化
• 最小限の XAML/C# コードで最初の TreeGrid を作成
• 簡単なレンダリング確認

データバインディング

📄 参照： references/data-binding.md

• 自己リレーションデータのバインド（ParentPropertyName、ChildPropertyName）
• ルートノードの SelfRelationRootValue 設定
• ネストされたコレクションのバインド（階層オブジェクト）
• データモデルと ViewModel の作成
• ItemsSource のバインドパターン
• ツリー構造の形成例

列と列の種類

📄 参照： references/columns.md

• 8種類の組み込み列（Text、Numeric、Date、Time、CheckBox、ComboBox、Hyperlink、Template）
• 列の自動生成と手動定義
• カスタマイズ用の AutoGeneratingColumn イベント
• データ型に基づく列タイプの選択
• TreeGridColumn の基底クラスとプロパティ

列の構成

📄 参照： references/column-configuration.md

• 列のサイズと幅のモード（Auto、Star、Fill）
• ヘッダーのカスタマイズと書式設定
• データバインディング用の MappingName
• 列の表示と順序
• 固定表示用の固定列
• セルテンプレートと編集テンプレート

編集と検証

📄 参照： references/editing.md

• 編集の有効化（AllowEditing プロパティ）
• 列レベルの編集制御
• 編集モードの設定
• CurrentCellBeginEdit イベントと CurrentCellEndEdit イベント
• 編集中のデータ検証
• プログラムによる編集操作
• カスタムエディターテンプレート

選択

📄 参照： references/selection.md

• 選択モード（Single、Multiple、Extended、None）
• 行選択とセル選択（SelectionUnit）
• SelectionChanging イベントと SelectionChanged イベント
• プログラムによる選択 API
• SelectedItem プロパティと SelectedItems プロパティ
• キーボードナビゲーションのパターン

並べ替えとフィルター処理

📄 参照: references/sorting-filtering.md

• 単一列および複数列での並べ替え
• SortColumnDescriptions コレクション
• SortColumnChanging/Changed イベント
• カスタム並べ替えロジック
• Excel に着想を得たフィルター UI（AllowFiltering）
• FilterChanging/Changed イベント
• 述語を使用したプログラムによるフィルター処理
• フィルターのカスタマイズ

行操作

📄 参照: references/row-operations.md

• 行の高さのカスタマイズ
• 行のドラッグ＆ドロップ機能
• ドラッグ＆ドロップのイベントと検証
• セルの結合機能
• セル結合の設定
• 条件付きの行スタイル設定
• 行の検証ルール

ノード機能

📄 参照: references/node-features.md

• 選択用のノードチェックボックス
• 再帰的なチェック動作
• NodeCheckStateChanging/Changed イベント
• 必要に応じた読み込み（子ノードの遅延読み込み）
• LoadOnDemandCommand
• HasChildNodes プロパティ
• 子ノードの動的な追加

データ操作

📄 参照: references/data-operations.md

• クリップボード操作（コピー／貼り付け）
• CopyOption プロパティの設定
• CopyGridCellContent イベント
• Excel へのエクスポート機能
• ExcelExportingOptions
• 選択した項目のエクスポート
• エクスポートのカスタマイズと書式設定

スタイル設定とカスタマイズ

📄 参照: references/styling-customization.md

• データに基づく条件付きスタイル設定
• セルと行のスタイル設定
• QueryCellStyle イベントと QueryRowStyle イベント
• GridLines のカスタマイズ
• GridLinesVisibility プロパティ
• UI のカスタマイズとテンプレート
• テーマとの統合

高度な機能

📄 参照: references/advanced-features.md

• コンテキストフライアウトメニュー
• カスタムコンテキストメニュー項目
• セルとヘッダーのツールチップ
• カスタムツールチップテンプレート
• MVVM パターンのサポート
• コマンドとデータバインディング
• ヘルパーメソッドとユーティリティ
• パフォーマンス最適化手法

クイックスタートの例

自己リレーショナルデータ

<Window
    x:Class="TreeGridDemo.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:treeGrid="using:Syncfusion.UI.Xaml.TreeGrid">
    
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    
    <Grid>
        <treeGrid:SfTreeGrid x:Name="treeGrid"
                            ItemsSource="{Binding Employees}"
                            ParentPropertyName="ID"
                            ChildPropertyName="ReportsTo"
                            SelfRelationRootValue="-1"
                            AutoExpandMode="RootNodesExpanded" />
    </Grid>
</Window>

public class EmployeeInfo
{
    public int ID { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Title { get; set; }
    public double Salary { get; set; }
    public int ReportsTo { get; set; }
}

public class ViewModel
{
    public ObservableCollection<EmployeeInfo> Employees { get; set; }
    
    public ViewModel()
    {
        Employees = new ObservableCollection<EmployeeInfo>
        {
            new EmployeeInfo { ID = 1, FirstName = "John", LastName = "Doe", 
                              Title = "CEO", Salary = 200000, ReportsTo = -1 },
            new EmployeeInfo { ID = 2, FirstName = "Jane", LastName = "Smith", 
                              Title = "Manager", Salary = 120000, ReportsTo = 1 },
            new EmployeeInfo { ID = 3, FirstName = "Bob", LastName = "Johnson", 
                              Title = "Developer", Salary = 80000, ReportsTo = 2 }
        };
    }
}

ネストされたコレクションデータ

public class PersonInfo
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public double Salary { get; set; }
    public ObservableCollection<PersonInfo> Children { get; set; }
}

<treeGrid:SfTreeGrid x:Name="treeGrid"
                    ItemsSource="{Binding PersonDetails}"
                    ChildPropertyName="Children" />

一般的なパターン

自己リレーショナルデータ構造

データオブジェクトが ID/ParentID を介して相互に参照する場合に使用します。

// Each employee has an ID and ReportsTo (parent ID)
ParentPropertyName = "ID"
ChildPropertyName = "ReportsTo"
SelfRelationRootValue = -1  // Root nodes have ReportsTo = -1

ネストされたコレクション構造

データオブジェクトに子コレクションが含まれる場合に使用します。

// Each person has a Children property containing child objects
ChildPropertyName = "Children"
// No ParentPropertyName needed

列の自動生成の制御

<treeGrid:SfTreeGrid AutoGenerateColumns="True" />


<treeGrid:SfTreeGrid AutoGenerateColumns="False">
    <treeGrid:SfTreeGrid.Columns>
        <treeGrid:TreeGridTextColumn MappingName="FirstName" HeaderText="First Name"/>
        <treeGrid:TreeGridNumericColumn MappingName="Salary" DisplayNumberFormat="C2"/>
    </treeGrid:SfTreeGrid.Columns>
</treeGrid:SfTreeGrid>

MVVM データバインディング

public class ViewModel : INotifyPropertyChanged
{
    private ObservableCollection<DataModel> _items;
    
    public ObservableCollection<DataModel> Items
    {
        get => _items;
        set
        {
            _items = value;
            OnPropertyChanged();
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged([CallerMemberName] string name = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
    }
}

展開／折りたたみの制御

// Auto-expand modes
AutoExpandMode = AutoExpandMode.AllNodesExpanded;  // All expanded
AutoExpandMode = AutoExpandMode.RootNodesExpanded; // Only root
AutoExpandMode = AutoExpandMode.None;              // All collapsed

// Programmatic control
treeGrid.ExpandNode(node);
treeGrid.CollapseNode(node);
treeGrid.ExpandAllNodes();
treeGrid.CollapseAllNodes();

主なプロパティ

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

• ItemsSource - データソース（IEnumerable）

  • 使用する場合：データバインディングに常に必要です
  • 理由：表示するデータを提供します

• ChildPropertyName - 子コレクションまたは親参照を含むプロパティ

  • 使用する場合：すべてのツリー構造で必要です
  • 理由：ツリーの関係を定義します

• ParentPropertyName - 一意の識別子を含むプロパティ（自己リレーショナルデータのみ）

  • 使用する場合：自己リレーショナルデータの場合のみ
  • 理由：親ノードを識別します

• SelfRelationRootValue - ルートノードを示す値（自己リレーショナルデータのみ）

  • 使用する場合：自己リレーショナルデータの場合
  • 理由：どのノードがルートかを識別します（デフォルト：null）

表示プロパティ

• AutoGenerateColumns - プロパティから列を自動生成します（デフォルト：true）

  • 使用する場合：列を手動で制御するには false に設定します
  • 理由：列定義を自動生成するか、明示的に定義するかを選択できます

• AutoExpandMode - 初期の展開状態

  • 使用する場合：ツリーの初期表示を制御します
  • 理由：データを探索する際のユーザー体験を向上させます

• ColumnWidthMode - 列幅の計算方法

  • 使用する場合：列のサイズ設定の動作を制御します
  • 理由：自動、Star、または固定幅を指定できます

機能プロパティ

• AllowEditing - セルの編集を有効にします（デフォルト：false）

  • 使用する場面：編集可能なグリッドが必要な場合
  • 理由：データをその場で変更できます

• AllowFiltering - フィルター UI を有効にします（デフォルト：false）

  • 使用する場面：大規模なデータセットをフィルタリングする必要がある場合
  • 理由：Excel 形式のデータフィルタリングを利用できます

• SelectionMode - 行またはセルの選択タイプ

  • 使用する場面：選択動作を制御する場合
  • 理由：単一、複数、拡張、またはなしを指定できます

• SelectionUnit - 行またはセルを選択します

  • 使用する場面：選択の粒度を定義する場合
  • 理由：行単位とセル単位の選択を切り替えられます

一般的なユースケース

組織階層

従業員がマネージャーに報告する会社の組織構造を表示します：

ParentPropertyName = "EmployeeID"
ChildPropertyName = "ManagerID"

ファイルシステムブラウザー

フォルダーとファイルをツリー構造で表示します：

ChildPropertyName = "SubItems"  // Nested collection

カテゴリ管理

商品カテゴリとサブカテゴリを表示します：

ChildPropertyName = "SubCategories"

部品表（BOM）

製品のアセンブリとコンポーネントを表示します：

ParentPropertyName = "PartID"
ChildPropertyName = "ParentPartID"

タスク／プロジェクト管理

タスクとサブタスクを表示します：

ChildPropertyName = "SubTasks"

地理的階層

国 > 州 > 都市を表示します：

ChildPropertyName = "Children"

トラブルシューティング

ツリー構造が形成されない

• ParentPropertyName と ChildPropertyName が正しく設定されていることを確認します
• SelfRelationRootValue がデータのルートを示す値と一致していることを確認します
• データの関連付けが正しく定義されていることを確認します

列が表示されない

• AutoGenerateColumns = True を設定するか、列を手動で定義します
• MappingName がプロパティ名と完全に一致していることを確認します（大文字と小文字は区別されます）
• データソースが ItemsSource にバインドされていることを確認します

大規模なデータセットでのパフォーマンスの問題

• 遅延読み込みを行うには、オンデマンド読み込みを有効にします
• オンデマンドモードを使用して、子ノードの読み込みを遅らせます
• 非常に大きなツリーでは、データ仮想化を検討します

編集できない

• TreeGrid で AllowEditing = True を設定します
• 列レベルの AllowEditing プロパティを確認します
• データオブジェクトが INotifyPropertyChanged を実装していることを確認します

---

次のステップ： はじめにガイドを読み、要件に応じて機能別リファレンスを確認します。