syncfusion-react-treegrid

Syncfusion React TreeGrid

Syncfusion の React TreeGrid コンポーネントを実装およびカスタマイズするための包括的なスキルです。TreeGrid は、自己参照型の階層データを展開／折りたたみ機能を備えた表形式で可視化し、仮想スクロールなどのエンタープライズ機能や、包括的なエクスポートオプションを提供します。

目次

• このスキルを使用する場面
• TreeGrid の概要
• データ構造のルール
• ドキュメントのナビゲーションガイド
• クイックスタートの例

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

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

• 階層データやツリー構造のデータ（組織図、ファイルシステム、部品表）を表示する
• 適切なデータバインディングと書式設定で列を構成する
• データ編集（セル、行、ダイアログ、バッチ、テンプレートモード）を実装する
• 並べ替え、フィルタリング、検索機能を追加する
• 行やセルの操作（選択、テンプレート、結合）を処理する
• 仮想スクロールや無限スクロールでパフォーマンスを最適化する
• ページングとスクロールの方式を構成する
• データを PDF、Excel、CSV 形式でエクスポートする
• 状態の永続化と集計を実装する
• テーマとスタイルで外観をカスタマイズする
• アクセシビリティと国際化（RTL、ローカライズ）に対応する

TreeGrid の概要

TreeGrid は、自己参照型の階層データを表示するために最適化されており、次の機能を備えています。

• 折りたたみ可能な行の自動展開／折りたたみ機能
• エンタープライズ機能：仮想スクロール、集計、状態の永続化
• モバイルや小さな画面に対応するアダプティブ UI
• 包括的なエクスポート：PDF、Excel、CSV 形式
• 完全なアクセシビリティ：WCAG 準拠、キーボードナビゲーション、ARIA サポート
• 国際化：RTL サポート、ロケールのカスタマイズ

データ構造のルール

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

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

要件：

// ✅ REQUIRED - Must match data property name exactly
<TreeGridComponent 
  dataSource={data}
  childMapping='subtasks'>
  <ColumnsDirective>
    {/* Columns */}
  </ColumnsDirective>
</TreeGridComponent>

// ❌ WRONG - Will not work
<TreeGridComponent 
  dataSource={data}>
  {/* No childMapping = No expansion possible */}
</TreeGridComponent>

データ形式：

// ✅ CORRECT - childMapping matches 'subtasks' property
const data = [
  {
    TaskID: 1,
    TaskName: 'Parent',
    subtasks: [  // Must match childMapping value exactly
      { TaskID: 2, TaskName: 'Child' }
    ]
  }
];

例外：フラットな親子構造には idMapping + parentIdMapping を使用します。

// Alternative: Flat structure with parent IDs
<TreeGridComponent 
  dataSource={flatData}
  idMapping='TaskID'
  parentIdMapping='ParentID'
  hasChildMapping='isParent'>
</TreeGridComponent>

---

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

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

要件：

// ✅ CORRECT - Type matches column definition
const data = [
  {
    TaskID: 1,              // number type
    TaskName: 'Planning',   // string type
    StartDate: new Date(),  // Date object for date columns
  }
];

// Column definition must match data types
<ColumnsDirective>
  <ColumnDirective field='TaskID' headerText='ID' type='number'></ColumnDirective>
  <ColumnDirective field='TaskName' headerText='Task' type='string'></ColumnDirective>
  <ColumnDirective field='StartDate' headerText='Date' type='date' format='yMd'></ColumnDirective>
</ColumnsDirective>

// ❌ WRONG - Type mismatch
const data = [
  {
    TaskID: '1',            // String instead of number
    StartDate: '02/03/2024' // String instead of Date object
  }
];

Props の完全なリファレンス

📄 プロパティとメソッド： references/programmatic-api.md

📄 イベントリファレンス 📖 references/events-reference.md

• イベントの完全なリファレンスガイド
• データイベント（actionBegin、actionComplete、actionFailure）
• 編集イベント（cellEdit、cellSave、beforeEdit）
• 選択イベント（rowSelected、rowDeselected、cellSelected）
• 展開／折りたたみイベント
• 列イベント（ドラッグ、ドロップ、サイズ変更、非表示、表示）
• 行イベントとユーティリティ

---

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

データバインディング

📖 references/data-binding.md

• ローカルとリモートのデータソース
• 自己参照型の親子関係
• DataManager の統合
• 初期展開状態の ExpandStateMapping
• ネストされたオブジェクトの複雑なデータバインディング

列の構成

📖 references/column.md

• 列の定義とフィールドのマッピング
• ツリー列のインデックス設定
• データ型と書式設定
• 列のテンプレートとカスタムレンダリング
• ヘッダーとスタイル設定
• 外部キー列

行の操作

📖 references/row.md

• 行テンプレートとカスタムレンダリング
• 行の高さの設定
• 行の結合
• ネストされたコンテンツの詳細テンプレート
• 行のドラッグ＆ドロップ
• インデントとインデント解除の操作

セルの操作

📖 references/cell.md

• セル編集
• セルのテンプレート、スタイル、属性
• セルの選択
• セルの書式設定

編集

📖 references/editing.md

• セル編集モード
• 行編集モード
• ダイアログ編集
• バッチ編集
• テンプレート編集
• 検証ルールとカスタムバリデーター
• コマンド列の編集
• サーバー側での永続化

並べ替え

📖 references/sorting.md

• 単一列および複数列での並べ替え
• 初期の並べ替え順序の設定
• カスタムの並べ替え比較関数
• テンプレートを使用した並べ替え
• プログラムによる並べ替え

フィルタリング

📖 references/filtering.md

• フィルターバーモード
• フィルターメニューモード
• Excel 風のフィルタリング
• カスタムフィルター
• プログラムによるフィルタリング
• フィルターテンプレート

検索

📖 references/searching.md

• すべての列を対象としたグローバル検索
• 検索結果のハイライト表示
• プログラムによる検索
• テンプレートを使用した検索

選択

📖 references/selection.md

• 行の選択（単一および複数）
• セルの選択
• チェックボックスによる選択
• 選択モードの設定
• プログラムによる選択
• 選択変更イベント

表示とレイアウト（パフォーマンスと表示）

📄 ページング 📖 references/paging.md

• ページャーの設定とオプション
• ページサイズの設定
• 初期ページの設定
• ページャーテンプレートのカスタマイズ
• プログラムによるページネーション

📄 スクロール 📖 references/scrolling.md

• 垂直および水平スクロール
• スクロール高さの設定
• スクロール位置の制御
• ヘッダーの固定
• レスポンシブスクロール

📄 行と列の固定 📖 references/frozen-rows-columns.md

• ヘッダー行の固定
• 列の固定
• 固定方向
• 列のロック
• IsFrozen プロパティの使用

📄 仮想スクロールと無限スクロール 📖 references/virtual-scrolling-infinite-scrolling.md

• 大規模なデータセット向けの仮想スクロール
• 無限スクロールの設定
• 仮想スクロール時の行の高さ
• ViewportIndex と ViewportStartIndex
• 仮想スクロールによるパフォーマンスの最適化

集計

📖 references/aggregates.md

• 標準集計（Sum、Average、Min、Max、Count）
• カスタム集計
• フッター集計
• グループ集計
• 子データの階層集計

状態の永続化

📖 references/state-persistence.md

• グローバル状態の永続化
• ローカル状態の永続化
• ExpandState の追跡
• 並べ替え、フィルター、ページングの永続化
• 再読み込み時の状態復元

ツールバー

📖 references/toolbar.md

• 組み込みツールバー項目
• カスタムツールバー項目
• ツールバー項目の種類（Button、Separator、Dropdown）
• ツールバー項目のクリック処理
• ツールバーテンプレートのカスタマイズ

コンテキストメニュー

📖 references/context-menu.md

• 組み込みコンテキストメニュー項目
• カスタムコンテキストメニュー項目
• メニュー項目のクリック処理
• コピー／編集／削除操作
• ヘッダーのコンテキストメニュー

アダプティブビュー

📖 references/adaptive-view.md

• 小さい画面向けのアダプティブ UI
• 全画面ダイアログ
• 水平方向の行表示
• レスポンシブな列の調整
• モバイル向けの最適化

読み込みアニメーション

📖 references/loading-animation.md

• 読み込みインジケーターの表示
• カスタム読み込みスピナー
• 読み込み状態の管理
• スピナーアニメーションの制御

エクスポートと印刷

📄 PDF エクスポート 📖 references/pdf-export.md

• PDF エクスポートの設定
• エクスポートオプション（列、形式）
• ヘッダーとフッター
• ページの向きとサイズ
• サーバーサイドでのエクスポート
• 階層データのエクスポート

📄 Excel エクスポート 📖 references/excel-export.md

• Excel エクスポートの設定
• エクスポートオプション（列、書式設定）
• エクスポート時のセルのスタイル設定
• ヘッダーとフッター
• サーバーサイドでのエクスポート
• 階層レベルのエクスポート

📄 印刷 📖 references/print.md

• 印刷の設定
• カスタムレイアウトでの印刷
• 特定範囲の印刷
• 階層レベルの印刷
• 印刷プレビュー

クリップボード

📖 references/clipboard.md

• セルの内容をクリップボードにコピー
• 行全体のコピー
• 貼り付け操作
• レベルを含む階層のコピー
• クリップボードイベントの処理

列の機能（高度）

📄 列の並べ替え 📖 references/column-reorder.md

• 列のドラッグ＆ドロップによる並べ替えを有効にする
• 特定の列が並べ替えられないようにする
• 並べ替えイベントとコールバック
• プログラムによる列の並べ替え

📄 列のサイズ変更 📖 references/column-resize.md

• 列のドラッグによるサイズ変更を有効にする
• コンテンツに合わせて列を自動調整する
• 列幅の制約（最小／最大）
• サイズ変更イベント
• プログラムによる幅の変更
• 列幅の保存／復元

📄 列メニュー 📖 references/column-menu.md

• 組み込みの列メニュー項目
• メニューからの並べ替え、フィルタリング、列の選択
• カスタムメニュー項目
• メニューイベントとハンドラー
• 条件付きメニュー項目

📄 列選択メニュー 📖 references/column-chooser.md

• 列の表示／非表示を切り替える
• 列選択ダイアログの設定
• プログラムによる列の表示／非表示
• 列の表示状態イベント
• 列の表示状態の保存／復元

📄 コマンド列 📖 references/command-column.md

• 組み込みのコマンドボタン（編集、削除、保存、キャンセル）
• カスタムコマンドボタン
• コマンドクリックハンドラー
• アイコンのカスタマイズ
• 行アクションのパターン

サーバー連携

📖 references/server-integration.md

• DataManager を使用したリモートデータバインディング
• サーバー側の CRUD 操作
• サーバー側のフィルタリングと並べ替え
• サーバー側のページング
• カスタムのリクエスト／レスポンス処理
• エラー処理の方針
• バッチ操作

検証パターン

📖 references/validation-patterns.md

• 列の検証ルール
• カスタム検証ロジック
• フィールド間の検証
• 非同期検証（API 呼び出し）
• サーバー側の検証
• ダイアログフォームの検証
• 条件付き検証
• エラーメッセージの表示

パフォーマンスの最適化

📖 references/performance-optimization.md

• 大規模なデータセット（10 万行以上）向けの仮想スクロール
• キャッシュを使用した無限スクロール
• バンドルサイズの最適化
• 不要な機能の無効化
• サーバー側操作の最適化
• メモ化とレンダリングの最適化
• テンプレートの最適化
• イベントハンドラーの最適化
• ベンチマークとパフォーマンスの監視
• パフォーマンスチェックリスト

カスタマイズ

📖 references/styling-appearance.md

• CSS クラスのカスタマイズ
• テーマの選択（Material、Bootstrap、Fluent、Tailwind）
• CSS 変数の上書き
• コンポーネント固有のスタイル設定
• ダークモードのサポート
• 行のスタイル設定
• セルのスタイル設定

グローバリゼーション

📖 references/globalization.md

• 国際化（i18n）
• UI テキストのローカライズ（l10n）
• 右から左への（RTL）表示のサポート
• ロケールに応じた日付の書式設定
• ロケールに応じた数値の書式設定
• 通貨のローカライズ

アクセシビリティ

📖 references/accessibility.md

• WCAG 2.1 レベル AA 準拠
• キーボード操作（すべてのショートカット）
• ARIA 属性とスクリーンリーダーのサポート
• 展開／折りたたみのキーボードショートカット
• 編集時のキーボード操作
• 選択用ショートカット

クイックスタートの例

import React from 'react';
import { TreeGridComponent, ColumnsDirective, ColumnDirective, Inject, Page } from '@syncfusion/ej2-react-treegrid';
import { DataManager, UrlAdaptor } from '@syncfusion/ej2-data';

interface ITreeData {
  TaskID?: number;
  TaskName?: string;
  parentID: number | null;
  Children?: ITreeData[];
}

export default function App() {
  const data: ITreeData[] = [
    {
      TaskID: 1,
      TaskName: 'Planning',
      parentID: null,
      Children: [{ TaskID: 2, TaskName: 'Plan timeline', parentID: 1 }]
    }
  ];

  return (
    <TreeGridComponent
      dataSource={data}
      childMapping="Children"
      treeColumnIndex={1}
      height="auto"
      allowPaging={true}
    >
      <ColumnsDirective>
        <ColumnDirective field="TaskID" headerText="Task ID" width={80} />
        <ColumnDirective field="TaskName" headerText="Task Name" width={160} />
      </ColumnsDirective>
      <Inject services={[Page]} />
    </TreeGridComponent>
  );
}

コア設定

プロパティ	型	デフォルト	説明
dataSource	Array | DataManager	[]	TreeGrid のデータソース
childMapping	string	null	子レコードのプロパティ名（例：「Children」）
idMapping	string	null	一意の ID のプロパティ名（フラットデータ）
parentIdMapping	string	null	親 ID のプロパティ名（フラットデータ）
hasChildMapping	string	null	遅延読み込みインジケーターのプロパティ
treeColumnIndex	number	0	ツリー展開アイコンを表示する列のインデックス
expandStateMapping	string	null	初期展開状態のプロパティ