syncfusion-blazor-treegrid

Syncfusion Blazor TreeGrid の実装

Syncfusion Blazor TreeGrid（SfTreeGrid<TValue>）は、展開／折りたたみ可能な行を備えた表形式で階層データを表示します。自己参照型のフラットデータ（IdMapping／ParentIdMapping）と、ネストされた子コレクションをサポートし、編集、フィルタリング、並べ替え、仮想化、エクスポートなど、グリッドの機能一式を利用できます。

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

• Blazor アプリで階層型／ツリー構造のデータテーブルが必要な場合
• SfTreeGrid、TreeGrid、IdMapping、ParentIdMappingについて言及された場合
• グリッドで展開／折りたたみ可能な親子行が必要な場合
• ツリー構造のデータに対するCRUD 操作が必要な場合
• 階層データのエクスポート、フィルタリング、並べ替え、ページングが必要な場合
• GraphQLAdaptor を使用して TreeGrid をGraphQL APIにバインドする必要がある場合
• グリッド形式で組織図、タスク階層、部品表、ファイルエクスプローラー形式のデータを扱う場合
• フラットな DataGrid から階層型 TreeGrid に移行する場合
• Blazor Web App、WASM、Server、または MAUI プロジェクトで TreeGrid を設定する場合

トリガーキーワード： TreeGrid、Tree Grid、SfTreeGrid、階層型グリッド、親子グリッド、IdMapping、ParentIdMapping、ツリーデータテーブル、ネストされたグリッド行、Syncfusion Blazor tree、GraphQL TreeGrid、GraphQLAdaptor TreeGrid

---

🔒 必須の主要ルール

これらのルールは、このスキルの動作を規定するものです。必須であり、厳守する必要があります。

1. 目的と責任

あなたの責任は、あらゆる自然言語によるユーザーのリクエストを解釈し、Syncfusion Blazor TreeGridのサポート対象となるすべての側面について、正確で完全かつ検証済みの情報を提供することです。対象には次の項目が含まれます。

• パブリック API
• プロパティ
• イベント
• 機能
• 動作

2. 正確性と API への準拠

このスキルは、次の要件を満たす必要があります。

• Syncfusion TreeGrid の公式にサポートされた機能のみを使用すること。
• API、メソッド、プロパティ、イベント、動作、将来の機能を決して創作しないこと。
• サポートされていないコードサンプルを決して提示しないこと。
• 常に Syncfusion コンポーネントの公式設計パターンに従うこと。

機能がサポートされていない場合は、その制限を明確に伝え、可能であればサポートされている代替案を提案してください。

3. 自然言語によるリクエストの解釈

ユーザーのリクエストが不完全な場合：

• TreeGrid の公式ベストプラクティスを使って、妥当な前提を推測してください。
• 不足している情報を、正確で関連性のある内容で補ってください。
• 必須の場合に限り、追加の説明を求めてください。

4. サポートされていないリクエストへの対応

ユーザーがサポートされていない機能を求めた場合：

• サポートされていないことを明確に伝える
• 公式の代替案または有効な回避策を提案する
• 不可能な機能を決して模倣したり、捏造したりしない

5. 設計パターンの徹底

このスキルは、次のような Syncfusion の公式パターンに従う必要があります。

• 正しいコンポーネント構造（SfTreeGrid、TreeGridColumn、TreeGridEditSettings、TreeGridEvents など）
• 適切な非同期イベントと API の使用
• 有効な設定プロパティと列挙型
• サポートされているデータバインディング方式（自己参照型、階層型、リモート、カスタムアダプター、GraphQL）
• 実際に存在するイベントパターンとイベント名

6. 品質、完全性、信頼性

このスキルは、次の要件を満たす必要があります。

• 検証済みで実際に利用できる TreeGrid の機能のみを使用する
• 実行可能で、実装にすぐ利用できるガイダンスを提供する
• ユーザーが迷わず従えるよう、明確さを保つ
• すっきりと読みやすい、プロフェッショナルな形式を維持する

7. ハルシネーション防止策

このスキルは、次のことをしてはなりません。

• 存在しない API や動作を創作する
• サポートされていないモード、機能、設定を提案する
• 不正確、誤解を招く、または検証不能なコードを提示する
• 文書化されていない内部動作を説明する

確信が持てない場合は、追加の説明を求めるか、制限を明確に伝えてください。

8. イベント名の確認要件

重要： コード例を提示する前に、イベント名を references/events.md と照合して必ず確認してください。すべてのツリーグリッドイベントは <TreeGridEvents> コンポーネント内で定義してください。

避けるべきよくある間違い：

• ❌ OnSortChange — 存在しません。代わりに Sorting、Sorted を使用してください。
• ❌ OnFilterChange — 存在しません。代わりに Filtering、Filtered を使用してください。

ルール： 以下について、必ず references/events.md を参照してください。

• 正確なイベント名（大文字と小文字を区別）
• イベント引数の型（名前空間の解決についてはルール 11を参照）
• イベントをキャンセルできるかどうか（✅ または ❌）
• イベントが発生するタイミング（操作の前／後）

9. コードを書く前にリファレンスファイルを読む

コードを生成する前に、依頼に含まれるすべての機能を特定し、それぞれのリファレンスファイルを読んでください。このファイルのスニペットは簡略化されており、重要なルールや既知の注意点が省略されています。リファレンスファイルが正式な情報源です。

⚠️ 該当するリファレンスファイルをすべて読んでください。クエリから最も明らかなものだけではありません。

10. 名前空間と型の解決ルール

ルール 1： CS0104「参照があいまいです」エラーを避けるため、常に完全修飾名前空間を使用してください。型は Syncfusion.Blazor.TreeGrid と Syncfusion.Blazor.Grids の両方の名前空間に存在します。

ルール 2： 以下の項目に関する CS0103「参照がありません」エラーを防ぐため、_Imports.razor またはコンポーネントに @using Syncfusion.Blazor.Grids; を必ず含めてください。

• イベント引数の型（ActionEventArgs、RowDataBoundEventArgs、BeforeCopyPasteEventArgs など）
• Action 列挙型（Action.Sorting、Action.Save など）
• コンポーネントクラス（TreeGridPageSettings、TreeGridFilterSettings、TreeGridSelectionSettings など）
• イベントハンドラーのサポートクラス

ルール 3： 以下のイベント引数の型は Syncfusion.Blazor.TreeGrid に属します。@using Syncfusion.Blazor.TreeGrid; を追加してください（Syncfusion.Blazor.Grids ではありません）。

• RowExpandingEventArgs<TValue>、RowExpandedEventArgs<TValue>
• RowCollapsingEventArgs<TValue>、RowCollapsedEventArgs<TValue>
• CheckBoxChangeEventArgs<TValue>

型の参照：

型	名前空間	例
FilterType	TreeGrid	Syncfusion.Blazor.TreeGrid.FilterType.Excel
EditMode	TreeGrid	Syncfusion.Blazor.TreeGrid.EditMode.Row
CopyHierarchyType	TreeGrid	Syncfusion.Blazor.TreeGrid.CopyHierarchyType.Both
Action	Grids	Syncfusion.Blazor.Grids.Action.Save
TextAlign	Grids	Syncfusion.Blazor.Grids.TextAlign.Right
ColumnType	Grids	Syncfusion.Blazor.Grids.ColumnType.Date
EditType	Grids	Syncfusion.Blazor.Grids.EditType.DatePickerEdit
SelectionMode	Grids	Syncfusion.Blazor.Grids.SelectionMode.Row
SelectionType	Grids	Syncfusion.Blazor.Grids.SelectionType.Multiple
ClipMode	Grids	Syncfusion.Blazor.Grids.ClipMode.Ellipsis
GridLine	Grids	Syncfusion.Blazor.Grids.GridLine.Horizontal
AggregateType	Grids	Syncfusion.Blazor.Grids.AggregateType.Sum
CellSelectionMode	Grids	Syncfusion.Blazor.Grids.CellSelectionMode.Box

---

コンポーネントの概要

<SfTreeGrid DataSource="@TreeData"
            IdMapping="TaskId"
            ParentIdMapping="ParentId"
            TreeColumnIndex="1"
            AllowSorting="true"
            AllowFiltering="true"
            AllowPaging="true">
    <TreeGridColumns>
        <TreeGridColumn Field="TaskId" HeaderText="ID" Width="80" IsPrimaryKey="true" />
        <TreeGridColumn Field="TaskName" HeaderText="Task Name" Width="200" />
        <TreeGridColumn Field="Duration" HeaderText="Duration" Width="100" />
        <TreeGridColumn Field="Progress" HeaderText="Progress" Width="100" />
    </TreeGridColumns>
</SfTreeGrid>

主な概念：

• IdMapping — 各行を一意に識別するプロパティ名
• ParentIdMapping — 親行の ID を指定するプロパティ名（null/0 = ルート）
• TreeColumnIndex — 展開／折りたたみアイコンを表示する列のインデックス（0 始まり）

---

ナビゲーションガイド

セットアップと使用開始

• 参照： references/getting-started.md
  • NuGet のインストール、_Imports.razor、Program.cs、テーマ／スクリプトの設定、基本的なグリッド、IdMapping／ParentIdMapping／TreeColumnIndex、すべて展開／折りたたみ、OnActionFailure

データバインディング

• 参照: references/data-binding.md
  • 自己参照型のフラットデータ、階層型のネストされた子要素、リモート URL/OData/Web API、SfDataManager、オンデマンド読み込み
• 参照: references/custom-binding.md
  • DataAdaptor のオーバーライド、Read/ReadAsync、挿入／更新／削除、ページングと並べ替えのサポート、自己参照型のみ
• 参照: references/graphql.md
  • Hot Chocolate サーバー、GraphQLAdaptor、GraphQLAdaptorOptions、DataManagerRequestInput、CRUD ミューテーション、連鎖削除、CORS

列とセル

• 参照: references/columns.md
  • ColumnType、Format、TextAlign、固定、並べ替え、サイズ変更、列選択、複数段ヘッダー、列メニュー、外部キー
• 参照: references/cell.md
  • QueryCellInfo、CustomAttributes、ClipMode、GridLines、ツールチップ

並べ替え、フィルタリング、検索

• 参照: references/sorting.md
  • AllowSorting、複数列の並べ替え、SortComparer、SortColumnAsync、ClearSortingAsync、階層を保持
• 参照: references/filtering.md
  • AllowFiltering、FilterType（FilterBar/Menu/Excel/CheckBox）、階層モード、演算子、FilterByColumnAsync。⚠️ FilterTemplate のルールについては filtering.md を参照してください
• 参照: references/searching.md
  • ツールバー検索、SearchAsync、GridSearchSettings、階層モード、強調表示／クリア

編集

• 参照: references/editing.md
  • 編集モード（Cell/Row/Dialog/Batch）、編集の種類、コマンド列、検証、テンプレート編集、EF Core。⚠️ ValidationRules については editing.md を参照してください。<TreeGridEvents> を使用する場合は、必ず @using Syncfusion.Blazor.Grids を追加してください

行と選択

• 参照: references/rows.md
  • RowDataBound、行／詳細テンプレート、ドラッグ＆ドロップ、行の高さ、行の結合
• 参照: references/selection.md
  • 行／セル／両方のモード、チェックボックス列、切り替え、ドラッグ選択、プログラムによる選択、タッチ

ページングと仮想化

• 参照: references/paging.md
  • AllowPaging、TreeGridPageSettings、PageSize、ページャーの位置／テンプレート、プログラムによるページ移動
• 参照: references/virtualization.md
  • EnableVirtualization、EnableColumnVirtualization、ページングとの比較、制限事項

ツールバー、メニュー、テンプレート

• 参照: references/toolbar.md
  • 組み込み項目とカスタム項目、EnableToolbarItemsAsync、OnToolbarClick
• 参照: references/context-menu.md
  • ContextMenuItems、カスタム項目、ContextMenuItemClicked、条件付き表示／非表示
• 参照: references/templates.md
  • 列／ヘッダー／行／詳細／ツールバーのテンプレート、読み込みインジケーター

エクスポートとスクロール

• 参照: references/exporting.md
  • ExportToExcelAsync、ExportToPdfAsync、PrintAsync、カスタムデータ／ヘッダー、テーマ
• 参照: references/scrolling.md
  • 固定行／列（FrozenRows、IsFrozen、FreezeDirection）、AllowFreezeLineMoving、EnableStickyHeader、ScrollIntoViewAsync

高度な機能

• 読む： references/aggregates.md
  • TreeGridAggregateColumn（Field＋Typeが必須）、AggregateType、FooterTemplate、ShowChildSummary、カスタム LINQ、ページ範囲に関する制限
• 読む： references/clipboard.md
  • コピー（Ctrl+C/Ctrl+Shift+H）、CopyAsync、貼り付け（Box＋Batch）、CopyHierarchyMode、BeforeCopyPaste
• 読む： references/autofill.md
  • EnableAutoFill＋セル／ボックス選択＋Batch 編集、制限事項
• 読む： references/adaptive-layout.md
  • EnableAdaptiveUI、全画面ダイアログ、縦方向の行モード
• 読む： references/state-management.md
  • EnablePersistence、永続化されるプロパティ、手動の状態管理メソッド

イベント

• 読む： references/events.md
  • TreeGridEvents<TValue>、OnActionBegin／OnActionComplete、RowDataBound、QueryCellInfo、アクションのキャンセル

---

クイックスタートの例

1. NuGet をインストール： Syncfusion.Blazor.TreeGrid

2. _Imports.razor に登録：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.TreeGrid

3. wwwroot/index.html または App.razor に CSS を追加：

<link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" />

4. Program.cs に追加：

builder.Services.AddSyncfusionBlazor();

5. 最小限のコンポーネント：

@using Syncfusion.Blazor.TreeGrid

<SfTreeGrid DataSource="@TreeData" IdMapping="Id" ParentIdMapping="ParentId" TreeColumnIndex="1">
    <TreeGridColumns>
        <TreeGridColumn Field="Id" HeaderText="ID" Width="80" IsPrimaryKey="true" />
        <TreeGridColumn Field="Name" HeaderText="Name" Width="200" />
        <TreeGridColumn Field="Status" HeaderText="Status" Width="120" />
    </TreeGridColumns>
</SfTreeGrid>

@code {
    public class TaskItem
    {
        public int Id { get; set; }
        public int? ParentId { get; set; }
        public string Name { get; set; }
        public string Status { get; set; }
    }

    private List<TaskItem> TreeData = new()
    {
        new TaskItem { Id = 1, ParentId = null, Name = "Project Alpha", Status = "In Progress" },
        new TaskItem { Id = 2, ParentId = 1,    Name = "Design Phase",  Status = "Done" },
        new TaskItem { Id = 3, ParentId = 1,    Name = "Development",   Status = "In Progress" },
        new TaskItem { Id = 4, ParentId = 3,    Name = "Backend API",   Status = "Pending" },
    };
}

---

よく使われるパターン

高機能な TreeGrid（並べ替え＋フィルタリング＋ページング＋編集）

<SfTreeGrid @ref="TreeGridRef"
            DataSource="@TreeData"
            IdMapping="Id"
            ParentIdMapping="ParentId"
            TreeColumnIndex="1"
            AllowSorting="true"
            AllowFiltering="true"
            AllowPaging="true"
            Toolbar="@(new List<string> { "Add", "Edit", "Delete", "Update", "Cancel" })">
    <TreeGridEditSettings AllowAdding="true"
                          AllowEditing="true"
                          AllowDeleting="true"
                          Mode="Syncfusion.Blazor.TreeGrid.EditMode.Row" />
    <TreeGridPageSettings PageSize="10" />
    <TreeGridColumns>
        <TreeGridColumn Field="Id" IsPrimaryKey="true" Visible="false" />
        <TreeGridColumn Field="Name" HeaderText="Task" Width="220" />
        <TreeGridColumn Field="Duration" HeaderText="Days" Width="100" />
        <TreeGridColumn Field="Progress" HeaderText="%" Width="100" />
    </TreeGridColumns>
</SfTreeGrid>

@code {
    private SfTreeGrid<TaskItem> TreeGridRef;
    // ... data and model
}

Excel と PDF へのエクスポート

<SfTreeGrid @ref="TreeGridRef" AllowExcelExport="true" AllowPdfExport="true"
            Toolbar="@(new List<string> { "ExcelExport", "PdfExport" })">
    <TreeGridEvents TValue="TaskItem" OnToolbarClick="ToolbarClickHandler" />
    ...
</SfTreeGrid>

@code {
    private SfTreeGrid<TaskItem> TreeGridRef;

    private async Task ToolbarClickHandler(Syncfusion.Blazor.Navigations.ClickEventArgs args)
    {
        if (args.Item.Id.Contains("excelexport"))
            await TreeGridRef.ExportToExcelAsync();
        else if (args.Item.Id.Contains("pdfexport"))
            await TreeGridRef.ExportToPdfAsync();
    }
}