syncfusion-winui-treeview

WinUI TreeView の実装

Windows App SDK アプリケーションで階層データを表示する Syncfusion® WinUI TreeView（SfTreeView）コントロールの包括的なガイドです。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• 階層データを表示する場合（ファイル、フォルダー、カテゴリなど）
• WinUI アプリケーションでファイルエクスプローラーやフォルダーブラウザーを実装する場合
• 組織図や報告体制を作成する場合
• 展開／折りたたみ可能なノードを使ったカテゴリナビゲーションを構築する場合
• 単一または複数の選択モードでノード選択を有効にする場合
• ツリーノードのインライン編集をサポートする場合
• ノードの並べ替えや移動にドラッグ＆ドロップを実装する場合
• 大規模な階層データをオンデマンドで読み込む場合
• テンプレートやスタイルでツリーの外観をカスタマイズする場合
• 階層データに対するCRUD 操作を処理する場合

TreeView コントロールは、親子関係やネストされたデータ構造の視覚化に優れています。

コンポーネントの概要

SfTreeView は、ノードを展開または折りたたむことで、階層構造のデータを表示するデータ指向のコントロールです。フォルダー構造、組織階層、またはネストされた関係の表示によく使われます。

主な機能

• 2 つのデータモード： バインドモード（データバインディング）と非バインドモード（手動でノードを作成）
• 柔軟な選択： キーボード修飾キーを使った拡張選択など、複数の選択モード
• インライン編集： カスタムテンプレートを使ってノードのコンテンツを編集
• ドラッグ＆ドロップ： ツリー内でノードを並べ替えたり移動したりできます
• オンデマンド読み込み： 親ノードの展開時に子ノードを遅延読み込み
• チェックボックス： 複数選択に対応した組み込みのチェックボックス
• コンテキストメニュー： ノード操作用のフライアウトメニューを追加
• アニメーション： スムーズな展開／折りたたみアニメーション
• MVVM サポート： コマンドとデータバインディングを全面的にサポート
• カスタマイズ： テンプレートを使って外観を完全に制御

TreeView を選ぶ場面

次のような場合は TreeView を選んでください。

• 親子データを階層的に視覚化する
• 省スペースな表示のためにセクションを展開／折りたたみする
• 複数階層のネスト（2 階層以上）がある
• ユーザーに馴染みのあるツリーナビゲーションパターンを使う

次の場合は、別のコントロールを検討してください。

• フラットなリスト → ListView または DataGrid を使用
• 単純なグループ化データ → グループ化機能付きの ListView を使用
• ネットワーク／グラフの関係 → カスタムの視覚化を使用

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

はじめに

📄 参照： references/getting-started.md

初期設定と最初の TreeView の作成は、ここから始めてください。

• NuGet パッケージ（Syncfusion.TreeView.WinUI）のインストール
• XAML ページへの TreeView の追加
• 非バインドノードを使った基本的な TreeView の実装
• 階層データを使った簡単なバインドモードの例
• 名前空間のインポートとコントロールの初期化
• プロジェクトの構成

データ管理

📄 参照： references/data-binding.md

TreeView をデータモデルにバインドする方法を説明します。

• バインドモードと非バインドモードの比較
• ItemsSource を使った階層データソースのバインド
• 自己関連バインディング用の ChildPropertyName
• 複雑な階層構造用の HierarchyPropertyDescriptors
• ItemTemplate と ExpanderTemplate の構成
• ObservableCollection と INotifyPropertyChanged
• NodePopulationMode（OnDemand と Instant）
• 変更追跡用の NotificationSubscriptionMode

📄 参照： references/drag-drop-crud.md

ノードの操作と CRUD 操作について説明します。

• ドラッグ＆ドロップの有効化（AllowDragging、AllowDrop）
• ドラッグ＆ドロップのイベントとカスタマイズ
• プログラムによるノードの追加
• 階層からのノードの削除
• ノードのコンテンツの更新
• オンデマンド読み込みの実装
• コンテキストメニューの操作

ユーザー操作機能

📄 読む： references/selection.md

ノード選択機能を実装します：

• SelectionMode のオプション（None、Single、SingleDeselect、Multiple、Extended）
• マウスとタッチによる UI 選択
• プログラムによる選択（SelectedItem、SelectedItems）
• 選択イベント（SelectionChanging、SelectionChanged）
• 選択時のキーボードナビゲーション
• Ctrl／Shift キーを使った複数選択
• 選択のカスタマイズとスタイル設定

📄 読む： references/expand-collapse.md

ノードの展開と折りたたみを制御します：

• AutoExpandMode のオプション
• プログラムによる展開と折りたたみ
• ExpandAction の設定（シングルタップ／ダブルタップ）
• IsExpanded プロパティの使用
• 展開／折りたたみイベント
• すべて展開／すべて折りたたむシナリオ
• 展開状態の維持

📄 読む： references/editing.md

ツリーノードのインライン編集を有効にします：

• AllowEditing による編集の有効化
• EditTemplate と EditTemplateSelector
• 編集モードの開始（F2 キー）
• 編集の確定とキャンセル
• 編集イベント（ItemBeginEdit、ItemEndEdit）
• 編集中の検証
• バインドモードと非バインドモードにおける編集の違い

📄 読む： references/interactivity.md

TreeView にインタラクティブな機能を追加します：

• チェックボックスのサポートと設定
• コンテキストフライアウトメニュー
• インタラクションイベント（ItemTapped、ItemDoubleTapped、ItemHolding）
• キーボードショートカットとナビゲーション
• タッチジェスチャ
• スクロール動作
• アニメーション設定（IsAnimationEnabled）

高度な機能

📄 読む： references/mvvm-patterns.md

TreeView で MVVM アーキテクチャを実装します：

• 階層データに対する MVVM パターン
• TreeView のコマンド
• データバインディングのベストプラクティス
• ツリー構造向けの ViewModel 設計
• ObservableCollections の処理
• イベントからコマンドへの変換
• TreeView の ViewModel の単体テスト

カスタマイズ

📄 読む： references/appearance-customization.md

視覚的な外観をカスタマイズします：

• ノードのコンテンツ用 ItemTemplate
• 展開／折りたたみアイコン用 ExpanderTemplate
• 項目の高さのカスタマイズ（ItemHeight、QueryNodeSize）
• TreeLines の設定
• インデントと間隔
• アイコンと画像の追加
• 選択時／ホバー時の状態のスタイル設定
• テーマとの統合

クイックスタートの例

ファイル構造を表示する、最小限の TreeView の例です：

XAML：

<Page xmlns:treeView="using:Syncfusion.UI.Xaml.TreeView">
    
    <Page.DataContext>
        <local:FileViewModel />
    </Page.DataContext>
    
    <treeView:SfTreeView x:Name="treeView"
                          Width="400"
                          Height="500"
                          ChildPropertyName="SubFiles"
                          ItemsSource="{Binding Files}">
        <treeView:SfTreeView.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal">
                    <TextBlock Text="📁" Margin="0,0,5,0" />
                    <TextBlock Text="{Binding FileName}" 
                               VerticalAlignment="Center" />
                </StackPanel>
            </DataTemplate>
        </treeView:SfTreeView.ItemTemplate>
    </treeView:SfTreeView>
    
</Page>

ViewModel（C#）：

public class FileViewModel : INotifyPropertyChanged
{
    public ObservableCollection<FileNode> Files { get; set; }
    
    public FileViewModel()
    {
        Files = new ObservableCollection<FileNode>
        {
            new FileNode 
            { 
                FileName = "Documents",
                SubFiles = new ObservableCollection<FileNode>
                {
                    new FileNode { FileName = "Resume.docx" },
                    new FileNode { FileName = "CoverLetter.pdf" }
                }
            },
            new FileNode 
            { 
                FileName = "Downloads",
                SubFiles = new ObservableCollection<FileNode>()
            }
        };
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
}

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

よく使われるパターン

パターン 1：アイコン付きファイルエクスプローラー

<treeView:SfTreeView ItemsSource="{Binding Items}"
                      ChildPropertyName="Children">
    <treeView:SfTreeView.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <FontIcon Glyph="{Binding Icon}" 
                          FontSize="16" 
                          Margin="0,0,8,0" />
                <TextBlock Text="{Binding Name}" />
            </StackPanel>
        </DataTemplate>
    </treeView:SfTreeView.ItemTemplate>
</treeView:SfTreeView>

パターン 2：チェックボックスを使った複数選択

<treeView:SfTreeView SelectionMode="Multiple"
                      CheckBoxMode="Recursive">
    
</treeView:SfTreeView>

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

<treeView:SfTreeView LoadOnDemandCommand="{Binding LoadChildrenCommand}">
    
</treeView:SfTreeView>

パターン 4：プログラムによる選択

// Single selection
treeView.SelectedItem = viewModel.RootNode.Children[0];

// Multiple selection
treeView.SelectedItems.Add(node1);
treeView.SelectedItems.Add(node2);

// Select all nodes
treeView.SelectAll();

パターン 5：コンテキストメニューの操作

<treeView:SfTreeView ItemHolding="OnItemHolding">
    
</treeView:SfTreeView>

private void OnItemHolding(object sender, ItemHoldingEventArgs e)
{
    var flyout = new MenuFlyout();
    flyout.Items.Add(new MenuFlyoutItem { Text = "Rename" });
    flyout.Items.Add(new MenuFlyoutItem { Text = "Delete" });
    flyout.ShowAt(e.Element);
}

主なプロパティとメソッド

基本プロパティ

プロパティ	型	説明
ItemsSource	object	バインドする階層データコレクション
ChildPropertyName	string	子項目を含むプロパティ名
SelectionMode	SelectionMode	選択動作（None、Single、Multiple、Extended）
SelectedItem	object	現在選択されている項目
SelectedItems	ObservableCollection	選択された項目のコレクション
AllowEditing	bool	インライン編集を有効にする
AllowDragging	bool	ドラッグ＆ドロップを有効にする
AutoExpandMode	AutoExpandMode	自動展開の動作（None、AllNodes、RootNodes）
IsAnimationEnabled	bool	展開／折りたたみのアニメーションを有効にする
CheckBoxMode	CheckBoxMode	チェックボックスの動作（None、Recursive）
LoadOnDemand	bool	子ノードの遅延読み込みを有効にする

主要なメソッド

メソッド	説明
ExpandAll()	ツリー内のすべてのノードを展開します
CollapseAll()	すべてのノードを折りたたみます
ExpandNode(TreeViewNode)	指定したノードを展開します
CollapseNode(TreeViewNode)	指定したノードを折りたたみます
SelectAll()	すべてのノードを選択します
ClearSelection()	すべての選択を解除します
BringIntoView(TreeViewNode)	ノードが表示されるようにスクロールします

重要なイベント

イベント	説明
SelectionChanged	選択が変更されたときに発生します
ItemTapped	ノードがタップされたときに発生します
ItemDoubleTapped	ノードがダブルタップされたときに発生します
NodeExpanding	ノードが展開される前に発生します
NodeExpanded	ノードが展開された後に発生します
NodeCollapsing	ノードが折りたたまれる前に発生します
NodeCollapsed	ノードが折りたたまれた後に発生します
ItemBeginEdit	編集が開始されたときに発生します
ItemEndEdit	編集が終了したときに発生します

一般的な使用例

使用例 1：ファイルシステムブラウザー

コンピューターのフォルダーやファイルを、展開／折りたたみ、ファイルアイコン、コンテキストメニュー操作（名前の変更、削除、コピー）とともに表示します。

使用する場面： ドキュメント管理、ファイルピッカー、アセットブラウザー

必要な主な機能：

• 階層データを使用するバインドモード
• アイコンを含むカスタム ItemTemplate
• コンテキストフライアウトメニュー
• ファイル移動用のドラッグ＆ドロップ

使用例 2：組織図

部署、チーム、従業員を含む会社の階層構造を表示し、選択して詳細を確認できるようにします。

使用する場面： 人事アプリケーション、組織の可視化、報告系統

必要な主な機能：

• 従業員データを使用するバインドモード
• 初期表示用の AutoExpandMode
• 単一選択モード
• 従業員カード用のカスタムテンプレート

使用例 3：製品カテゴリーブラウザー

展開可能なカテゴリーとサブカテゴリーを使った、Eコマースのカテゴリー ナビゲーションです。

使用する場面： Eコマース、コンテンツ管理、製品カタログ

必要な主な機能：

• 大規模なカタログ向けのオンデマンド読み込み
• 単一選択
• カテゴリー用のカスタムスタイル
• ナビゲーション用のクリックイベント

使用例 4：設定パネル

グループ化されたオプションと展開可能なセクションを備えた、階層型の設定インターフェイスです。

使用する場面： アプリケーション設定、環境設定 UI、構成パネル

必要な主な機能：

• 手動でノードを設定する非バインドモード
• 利便性を高める AutoExpandMode
• 設定コントロール用のカスタム ItemTemplate
• 展開状態の維持

使用例 5：プロジェクトエクスプローラー（IDE風）

Visual Studio のように、プロジェクト、フォルダー、ファイルを含むソリューション構造を表示します。

使用する場面： 開発者向けツール、IDE、コードエディター

必要な主な機能：

• ソリューションモデルを使用するバインドモード
• 名前変更用のインライン編集
• 再編成用のドラッグ＆ドロップ
• ファイル操作用のコンテキストメニュー
• 一括操作用の複数選択

パフォーマンスに関するヒント

• 大規模な階層（ノード数 1000 以上）では、NodePopulationMode に OnDemand を使用します
• 必要な場合に限り、NotificationSubscriptionMode を CollectionChanged に設定します
• パフォーマンスを向上させるため、Binding の代わりに x:Bind を使用します
• ItemTemplate の複雑さを抑えます
• 子要素が多い深い階層では、LoadOnDemand を使用します
• 非常に大規模でフラットなセクションでは、仮想化を検討します

トラブルシューティング早見表

問題	解決策
ノードが展開されない	ChildPropertyName がプロパティ名と正確に一致しているか確認します
選択が機能しない	SelectionMode を Single または Multiple に設定します
データが更新されない	データモデルに INotifyPropertyChanged を実装します
子要素が読み込まれない	NotificationSubscriptionMode を CollectionChanged に設定します
パフォーマンスが低い	OnDemand モードと LoadOnDemand を有効にします
編集が有効にならない	AllowEditing="True" を設定し、EditTemplate を定義します
ドラッグ＆ドロップが機能しない	AllowDragging と AllowDrop の両方を true に設定します

関連コンポーネント

• ListView - 階層構造のないフラットなリスト向け
• DataGrid - 階層構造をサポートする表形式のデータ向け（TreeGrid）
• Expander - シンプルな展開／折りたたみセクション向け

---

次のステップ： 必要に応じて、上記リンク先のリファレンスドキュメントをお読みください。TreeView を初めて使用する場合は、getting-started.md から始めてください。