syncfusion-aspnetcore-tree-grid

Syncfusion ASP.NET Core TreeGrid

TreeGrid コンポーネントは、自己参照型の階層データを表形式で可視化します。子／親データのバインド（childMapping または idMapping を使用）、子行の展開／折りたたみ、並べ替え、フィルタリング、編集、ページング、エクスポート、仮想化に対応しています。

⚠️ セキュリティと信頼境界

• TreeGrid スキルは、リモートデータアクセスを実行しません。
• すべての外部 API とのやり取りは、このスキルの信頼境界外にある別の DataManager スキルが処理します。

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

• ASP.NET Core で階層構造または親子構造のデータ（プロジェクトのタスク、組織図、部品表など）を表示する
• ツリー構造のデータに対する CRUD 操作を実装する
• 階層レコードを横断して並べ替え、フィルタリング、検索を行う
• ツリーデータを Excel または PDF にエクスポートする
• 仮想スクロールまたは無限スクロールで大規模なデータセットを処理する

API 全体を確認するには、プロパティと設定、イベントとライフサイクル、クラスと列挙型のリファレンスファイルを参照してください。

目次

• データ構造のルール
• ドキュメントとナビゲーションのガイド
• クイックスタートの例
• 一般的なパターン

データ構造のルール

ルール 1：階層データでは childMapping が必須です

重大度：🔴 重大 - これがないとグリッドで展開／折りたたみができません

要件：

CSHTML ビュー：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children"
              treeColumnIndex="1" allowPaging="true">
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           isPrimaryKey="true" textAlign="Right" width="95"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <e-treegrid-column field="Duration" headerText="Duration" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>


<ejs-treegrid id="TreeGrid2" dataSource="@ViewBag.data">
    
</ejs-treegrid>

データ形式の C# モデル：

public class TreeGridItem
{
    public int TaskId { get; set; }
    public string TaskName { get; set; }
    public int Duration { get; set; }
    public List<TreeGridItem> Children { get; set; }  // Must match childMapping="Children"
}

// Sample data
var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,
        TaskName = "Planning",
        Duration = 5,
        Children = new List<TreeGridItem>  // ✅ CORRECT - nested Children property
        {
            new TreeGridItem { TaskId = 2, TaskName = "Identify Site", Duration = 2 },
            new TreeGridItem { TaskId = 3, TaskName = "Perform Test",   Duration = 3 }
        }
    }
};

代替方法：親 ID を使用するフラット構造：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.flatData" 
              idMapping="TaskId" parentIdMapping="ParentId" treeColumnIndex="1">
    ...
</ejs-treegrid>

var flatData = new List<TreeGridItem>
{
    new TreeGridItem { TaskId = 1, TaskName = "Planning", ParentId = null },
    new TreeGridItem { TaskId = 2, TaskName = "Identify Site", ParentId = 1 },
    new TreeGridItem { TaskId = 3, TaskName = "Perform Test",   ParentId = 1 }
};

ルール 2：データ型の一致が必須です

重大度：🟠 重要 - 型の不一致はレンダリングや並べ替えの問題を引き起こします

C# モデル - 正しい型：

public class TreeGridItem
{
    public int TaskId { get; set; }              // ✅ int type
    public string TaskName { get; set; }         // ✅ string type
    public DateTime StartDate { get; set; }      // ✅ DateTime for date columns
    public decimal Price { get; set; }           // ✅ decimal for currency
}

var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,                              // int, not string "1"
        TaskName = "Planning",
        StartDate = new DateTime(2024, 3, 15),   // DateTime, not "03/15/2024"
        Price = 1500.50m                         // decimal, not string "1500.50"
    }
};

CSHTML 列の定義 - データ型を一致させる：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children">
    <e-treegrid-columns>
        
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           type="number" textAlign="Right" width="95"></e-treegrid-column>
        
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        
        <e-treegrid-column field="StartDate" headerText="Start Date" 
                           type="date" format="yMd" textAlign="Right" width="115"></e-treegrid-column>
        
        <e-treegrid-column field="Price" headerText="Price" 
                           type="number" format="c2" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

❌ 誤り - 型の不一致による問題：

// Bad model - mixing string where types should be specific
var badData = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = "1",                // ❌ String instead of int
        StartDate = "02/03/2024"     // ❌ String instead of DateTime
    }
};
// Result: Sorting fails, formatting doesn't work, expand/collapse issues

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

はじめに

📄 参照： references/getting-started.md

• NuGet によるインストール（Syncfusion.EJ2.AspNet.Core）
• _ViewImports.cshtml での TagHelper の登録
• _Layout.cshtml での CSS／スクリプト CDN の設定
• 基本的な <ejs-treegrid> の宣言
• childMapping／treeColumnIndex を使用したローカルデータのバインド
• <e-treegrid-columns> を使用した列の定義
• 起動時のページング、並べ替え、フィルタリングの有効化
• actionFailure によるエラー処理

データバインド

📄 参照： references/data-binding.md

• childMapping（ネストされたリスト）および idMapping／parentIdMapping（フラットリスト）を使用したローカルデータ
• OData／WebAPI アダプターを使用した DataManager 経由のリモートデータ
• Ajax／Fetch ベースのバインド
• expandStateMapping — 行ごとの初期展開／折りたたみ状態を制御する
• null または欠落している親参照の処理

列

📄 参照： references/columns.md

• 列の field、headerText、textAlign、width、type、format
• treeColumnIndex — 展開／折りたたみ矢印を表示する列を指定する
• 数値／日付の書式設定（N2、C2、yMd、カスタム）
• 列の固定、列の動的な表示／非表示
• チェックボックス列（showCheckbox、autoCheckHierarchy）
• 計算列／式列の valueAccessor
• 列メニュー（showColumnMenu）
• 列の並べ替え、サイズ変更、自動調整
• 列テンプレート、列の結合、ヘッダー、複雑なデータバインド

並べ替え

📄 参照： references/sorting.md

• allowSorting で有効にする
• e-treegrid-sortsettings による初期並べ替え
• 複数列の並べ替え（CTRL + クリック）
• 列ごとの並べ替えを無効にする（列の allowSorting: false）
• 並べ替えイベント（actionBegin、actionComplete）
• sortColumn／clearSorting によるプログラムからの並べ替え／解除

フィルタリング

📄 参照: references/filtering.md

• allowFilteringで有効にします
• フィルターの種類：FilterBar（デフォルト）、Menu、Excel風
• フィルター階層モード：Parent、Child、Both、None
• 述語による初期フィルター
• フィルター演算子（startswith、contains、equal、greaterthanなど）
• 列ごとにフィルターを無効化

編集

📄 参照: references/editing.md

• e-treegrid-editSettingsとisPrimaryKeyで有効にします
• 編集モード：Cell、Row、Dialog、Batch
• Add／Edit／Delete／Update／Cancelを備えたツールバー
• newRowPosition：Top、Bottom、Above、Below、Child
• 削除確認ダイアログ
• 追加時の列のデフォルト値
• 列ごとに編集を無効化
• 検証ルール
• 編集したデータをサーバーに保存

ページング

📄 参照: references/paging.md

• allowPagingで有効にします
• e-treegrid-pagesettings：pageSize、pageSizeMode（All／Root）
• ページサイズのドロップダウン、ページャーテンプレート
• dataBoundイベントでページャーを上部に表示

選択

📄 参照: references/selection.md

• Row、Cell、Bothの選択モード
• SingleとMultipleの種類（e-treegrid-selectionsettings）
• checkboxModeによるチェックボックス選択
• プログラムによる選択

集計

📄 参照: references/aggregates.md

• 組み込みの種類：Sum、Average、Min、Max、Count、Truecount、Falsecount
• フッター集計と子（親行フッター）集計
• 子の集計を表示するshowChildSummary
• カスタム集計関数
• 独自の表示に使用するfooterTemplate

行のカスタマイズ

📄 参照: references/row.md

• 条件付きスタイル設定に使用するrowDataBound
• 交互の行のスタイル設定（.e-altrow）
• 行テンプレート、詳細テンプレート
• 行のドラッグ＆ドロップ（allowRowDragAndDrop）
• 行の高さ、行の結合

セルのカスタマイズ

📄 参照: references/cell.md

• セルごとのカスタマイズに使用するqueryCellInfo
• セルのカスタム属性
• テキストの自動折り返し（allowTextWrap）
• クリップモード（Clip、Ellipsis、EllipsisWithTooltip）
• グリッド線

エクスポート（Excel）

📄 参照: references/excel-export.md

• Excelへのエクスポート（allowExcelExport、excelExport()）
• エクスポート時に折りたたみ状態を保持
• エクスポート時のカスタム集計
• ヘッダー／フッター、セルスタイルのカスタマイズ
• サーバーサイドのエクスポートオプション

PDF エクスポート

📄 参照: references/pdf-export.md

• PDFへのエクスポート（allowPdfExport、pdfExport()）
• PDFエクスポートのオプションと設定
• ページの向き（Portrait、Landscape）
• カスタムヘッダー、フッター、スタイル設定
• PDFのセルスタイルのカスタマイズ
• サーバーサイドのPDFエクスポート

印刷

📄 参照: references/print.md

• allowPrintingで印刷を有効にします
• ツールバーボタンまたは外部ボタンから印刷
• 現在のページのみを印刷（printMode: 'CurrentPage'）
• 印刷時の列の表示／非表示
• 大規模なデータセットの処理
• ページ設定

クリップボード

📄 参照: references/clipboard.md

• Ctrl+CとCtrl+Shift+Hでクリップボードにコピー
• 外部ボタンを使ったコピー
• コピーの階層モード（Parent、Child、Both、None）
• ドラッグして入力するオートフィル機能
• Ctrl+Vによる貼り付け機能
• 型変換の制限事項

スクロール

📄 参照: references/scrolling.md

• 基本的なスクロールとレスポンシブ設定
• スティッキーヘッダー、行／列の仮想化、無限スクロール
• 大規模なデータセット向けのパフォーマンス最適化

アダプティブレイアウト

📄 参照: references/adaptive.md

• モバイル端末とタブレット端末向けのレスポンシブUI（enableAdaptiveUI）
• 小さな画面でフィルタリングと編集に使用するアダプティブダイアログモード
• タッチ操作向けの展開／折りたたみ動作の最適化
• モバイルダイアログに合わせた列選択機能
• モバイルでの読みやすさを高める垂直行表示モード
• レスポンシブなTreeGridデザインのベストプラクティス

行と列の固定

📄 参照： references/frozen.md

• frozenRows、frozenColumns、または isFrozen プロパティを使用して行と列を固定します
• 左右の位置を指定して固定方向を制御します
• 他の機能との制限事項と互換性に関する考慮事項

スタイルと外観

📄 参照： references/styling-and-appearance.md

• すべての要素に CSS クラスを適用して Tree Grid のスタイルをカスタマイズします
• ヘッダー、行、セル、選択範囲、サマリーの CSS 上書き例
• Syncfusion Theme Studio を使用したカスタムテーマのオプション

イミュータブルモード

📄 参照： references/immutable.md

• enableImmutableMode="true" を設定して有効にします
• 大規模なデータセットのパフォーマンスを最適化します
• 比較には主キーが必要です
• 変更された行のみを選択的に再描画します
• 一括操作でパフォーマンスが向上します
• 制限事項と回避策

ツールバー

📄 参照： references/toolbar.md

• 組み込みのツールバー項目（Add、Edit、Delete、Update、Cancel、Search、ExcelExport、PdfExport など）
• テキスト、アイコン、ツールチップ、配置を指定したカスタムツールバー項目
• イベント引数を使用するツールバーのクリックハンドラー
• 組み込み項目の ID パターンと識別方法
• 行の選択状態に応じてツールバー項目を動的に無効化します
• ツールバーのデザインとレイアウトに関するベストプラクティス
• ツールバーボタンとの編集モードの連携

コンテキストメニュー

📄 参照： references/context-menu.md

• データ操作と列操作用のデフォルトのコンテキストメニュー項目
• 階層を考慮した機能を備えたカスタムコンテキストメニュー項目
• ターゲットセレクター（.e-content、.e-headercell）を使用したコンテキストに応じた表示
• 行と列の情報を含むコンテキストメニューのクリックハンドラー
• 行の状態（親／子）に応じて項目を動的に有効化／無効化します
• TreeGrid 用の階層対応の展開／折りたたみメニュー
• 高度なシナリオ：親のみを対象とする操作、条件付きメニュー項目
• TreeGrid 固有のコンテキストメニュー設計に関するベストプラクティス

検索

📄 参照： references/searching.md

• TreeGrid の階層データ全体を対象とした全文検索を有効にします
• 検索ツールバー項目を追加して、入力中にリアルタイムで絞り込みます
• 検索対象のフィールドを設定します（すべての列、または特定の列のサブセット）
• 演算子（contains、startsWith、endsWith、equal、notEqual）を使用して検索します
• 外部入力コントロールからプログラムで検索を実行します
• 階層を検索し、子の一致時に親行を自動的に展開します
• 検索をクリアして、すべての行を表示する状態に戻します
• カスタムロジックのために検索イベント（actionBegin、actionComplete）を処理します
• 大規模な階層データセットの検索に関するベストプラクティス

読み込みアニメーション

📄 参照： references/loading-animation.md

• 読み込みインジケーターの種類：スピナー（デフォルト）とシマーアニメーション
• 読み込みアニメーションが表示されるタイミング（初回描画、並べ替え、フィルタリング、ページング、検索）
• DataManager を使用した、読み込みアニメーション付きのリモートデータバインディング
• 読み込みインジケーターをプログラムで制御します（表示／非表示）
• アクションイベントを使用して読み込み動作をカスタマイズします
• 読み込み状態の UX に関するベストプラクティス
• モバイル環境と低速ネットワーク向けの最適化

グローバル化とローカライズ

📄 参照： references/global-local.md

• locale プロパティを使用した、カルチャ固有の数値と日付の書式設定
• UI 文字列（ツールバー、ダイアログ、ページャー、フィルター、展開／折りたたみのテキスト）のローカライズ
• アラビア語、ヘブライ語などの右から左（RTL）レイアウトへの対応
• CLDR データの読み込みとカルチャの設定
• 通貨、日付、数値列に使用する書式コード（C2、yMd、N2）
• ロケールをまたいだ対応と、言語の動的な切り替え
• グローバルアプリケーションに関するベストプラクティス

状態管理

📄 参照: references/state-management.md

• enablePersistence を使用して、セッションをまたいで TreeGrid の状態を保持します
• 並べ替え、フィルタリング、ページング、列の設定を保存して復元します
• ページの再読み込み後も、親行の展開／折りたたみ状態を保持します
• LocalStorage による自動永続化と、手動での状態取得に対応します
• プログラムから TreeGrid の状態を既定値にリセットします
• 機密データ向けのカスタムなサーバー側状態永続化
• 階層データの状態管理に関するベストプラクティス

アクセシビリティ

📄 参照: references/accessibility.md

• WCAG 2.1 準拠
• キーボードナビゲーション
• ARIA 属性
• スクリーンリーダーのサポート

プロパティと設定

📄 参照: references/properties-configuration.md

• 用途別に整理された 145 以上の TreeGrid プロパティを確認できます
• データ設定（dataSource、childMapping、idMapping、parentIdMapping、expandStateMapping）
• UI レイアウト（height、width、rowHeight、treeColumnIndex）
• グリッドの外観（gridLines、enableAltRow、enableRtl、enableHover、clipMode）
• 機能の切り替え表（ページング、並べ替え、フィルタリング、編集、選択など）
• パフォーマンスの調整（仮想化、無限スクロール、不変モード、永続化）
• イベントコールバックとハンドラー
• 高度な設定オブジェクト（EditSettings、PageSettings、FilterSettings、SelectionSettings など）

イベントとライフサイクル

📄 参照: references/events-methods.md

• ライフサイクルイベント（created、load、dataBound、beforeDataBound、dataSourceChanged）
• アクションイベント（actionBegin、actionComplete、actionFailure）
• 展開／折りたたみイベント（expanding、expanded、collapsing、collapsed）
• 編集イベント（beginEdit、cellEdit、cellSave、cellSaved、batchAdd、batchDelete、beforeBatchSave）
• 選択イベント（rowSelected、rowSelecting、rowDeselected、checkboxChange）
• ドラッグ＆ドロップイベント（rowDragStart、rowDrop、columnDragStart、columnDrop）
• カスタムレンダリングイベント（queryCellInfo、rowDataBound、detailDataBound）
• エクスポートイベント（beforeExcelExport、excelExportComplete、beforePdfExport、pdfQueryCellInfo）
• 各カテゴリのイベントシグネチャと例を網羅しています

設定クラスと列挙型のリファレンス

📄 参照: references/classes-enums-reference.md

• 列挙型：CopyHierarchyType、EditMode、FilterHierarchyMode、FilterType、PageSizeMode、RowPosition、WrapMode
• 設定クラス：EditSettings、PageSettings、SortSettings、FilterSettings、SelectionSettings、RowDropSettings、InfiniteScrollSettings
• 列の設定：TreeGridColumn クラス、StackedHeaderCell クラス
• 流れるような API を実現するビルダーパターンとタグヘルパーのアプローチ
• 各設定クラスのすべてのプロパティ定義

クイックスタートの例

ローカルデータ、列、並べ替え、フィルタリング、ページングを使用する最小構成の TreeGrid：

_ViewImports.cshtml

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml（<head> 内）

<link rel="stylesheet" href="~/ej2/ej2version/fluent2.css" />

<script src="~/ej2/ej2version/dist/ej2.min.js"></script>

_Layout.cshtml（<body> の末尾）

<ejs-scripts></ejs-scripts>

Index.cshtml

@{
    var data = TreeGridItems.GetTreeData();
}

<ejs-treegrid id="TreeGrid" dataSource="@data" childMapping="Children"
              treeColumnIndex="1" allowSorting="true" allowFiltering="true" allowPaging="true">
    <e-treegrid-pagesettings pageSize="5"></e-treegrid-pagesettings>
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID" isPrimaryKey="true"
                           textAlign="Right" width="95"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <e-treegrid-column field="StartDate" headerText="Start Date"
                           textAlign="Right" format="yMd" type="date" width="115"></e-treegrid-column>
        <e-treegrid-column field="Duration" headerText="Duration"
                           textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

Index.cshtml.cs（または Controller）

public class TreeGridItems
{
    public int TaskId { get; set; }
    public string TaskName { get; set; }
    public DateTime StartDate { get; set; }
    public int Duration { get; set; }
    public List<TreeGridItems> Children { get; set; }

    public static List<TreeGridItems> GetTreeData()
    {
        return new List<TreeGridItems>
        {
            new TreeGridItems
            {
                TaskId = 1, TaskName = "Planning",
                StartDate = new DateTime(2021, 6, 7), Duration = 5,
                Children = new List<TreeGridItems>
                {
                    new TreeGridItems { TaskId = 2, TaskName = "Plan timeline", StartDate = new DateTime(2021, 6, 7), Duration = 5 },
                    new TreeGridItems { TaskId = 3, TaskName = "Plan budget",   StartDate = new DateTime(2021, 6, 7), Duration = 5 }
                }
            }
        };
    }
}

よく使われるパターン

childMapping と idMapping の使い分け

• childMapping：データがネストされている（各親が Children リストを持つ）場合 → childMapping="Children" をバインドします
• idMapping + parentIdMapping：データが親 ID 参照を含むフラットな形式の場合 → idMapping="TaskId" parentIdMapping="ParentId" をバインドします

ツールバーで編集を有効にする

<ejs-treegrid id="TreeGrid" dataSource="@data" childMapping="Children"
              treeColumnIndex="1" toolbar="@(new List<string>() {"Add","Edit","Delete","Update","Cancel"})">
    <e-treegrid-editsettings allowAdding="true" allowEditing="true"
                             allowDeleting="true" mode="Row"></e-treegrid-editsettings>
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID"
                           isPrimaryKey="true" width="90"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

いずれかの列で必ず isPrimaryKey="true" を設定してください。編集および削除操作に必要です。

主なエラーの回避方法

• ページングと仮想化を同時に有効にしないでください
• isFrozen と frozenColumns を同時に設定しないでください
• showCheckbox 列はツリー列にのみ定義してください
• textAlign="Right" はツリー列には適用できません
• idMapping と childMapping を同時に有効にしないでください