syncfusion-javascript-treegrid

Syncfusion TypeScript TreeGrid

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

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

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

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

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

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

次の場合、このスキルを使用しないでください。

• 単純なフラットテーブルを表示する場合（代わりに DataGrid を使用してください）
• ツリービューコンポーネントを使用する場合（TreeView コントロールを使用してください）
• ファイルのアップロード／ダウンロードを処理する場合（別の機能です）

目次

• TreeGrid の概要
• データ構造のルール
• API リファレンス
• 機能の概要とナビゲーションガイド
• クイックスタートの例

TreeGrid の概要

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

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

データ構造のルール

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

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

要件：

import { TreeGrid } from '@syncfusion/ej2-treegrid';

// ✅ REQUIRED - childMapping matches data property name exactly
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: hierarchicalData,
    childMapping: 'subtasks',  // Must match property in data
    treeColumnIndex: 0,
    columns: [
        { field: 'taskID', headerText: 'Task ID', width: 90 },
        { field: 'taskName', headerText: 'Task Name', width: 200 }
    ]
});

// ❌ WRONG - No childMapping = No expansion possible
let treeGridObj2: TreeGrid = new TreeGrid({
    dataSource: hierarchicalData,
    // Missing childMapping - Won't work!
    columns: [...]
});

データ形式：

// ✅ CORRECT - childMapping matches 'subtasks' property
const hierarchicalData = [
  {
    taskID: 1,
    taskName: 'Planning',
    subtasks: [  // Must match childMapping value exactly
      { taskID: 2, taskName: 'Identify Site' },
      { taskID: 3, taskName: 'Perform Test' }
    ]
  }
];

// Alternative: Flat structure with parent IDs
const flatData = [
    { taskID: 1, taskName: 'Planning', parentID: null, isParent: true },
    { taskID: 2, taskName: 'Identify Site', parentID: 1, isParent: false }
];

let treeGridObj3: TreeGrid = new TreeGrid({
    dataSource: flatData,
    idMapping: 'taskID',
    parentIdMapping: 'parentID',
    hasChildMapping: 'isParent'
});

ルール 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
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: data,
    columns: [
        { field: 'taskID', headerText: 'ID', type: 'number', width: 90 },
        { field: 'taskName', headerText: 'Task', type: 'string', width: 200 },
        { field: 'startDate', headerText: 'Date', type: 'date', format: 'yMd', width: 120 }
    ]
});

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

---

API リファレンス

プロパティとメソッド

📄 参照： references/api-properties-methods.md

• プロパティの完全なリファレンス（83 プロパティ）
• カテゴリ別に整理：データと構成、動作と表示、選択、編集、エクスポート、高度な機能
• すべてのメソッド（全 108 種類）
• メソッドのシグネチャと戻り値の型
• 使用場面：構成の設定、CRUD 操作、DOM 操作、行／セルの管理

イベントとモジュール

📄 参照： references/api-events-modules.md

• イベントの完全なリファレンス（66 イベント）
• ライフサイクル別に整理されたイベント：ライフサイクルイベント、データ、編集、選択、展開／折りたたみ、エクスポート、UI 操作、ドラッグ／ドロップ
• 機能モジュール（全 15 種類）
• モジュールの注入パターンと使用方法
• 使用場面：グリッドの状態変化への応答、ユーザー操作の処理、機能読み込みの最適化

---

機能の概要とナビゲーションガイド

TreeGrid コンポーネントには、階層データの管理、表示、操作のための包括的な機能が備わっています。以下に、機能領域別に整理したナビゲーションガイドを示します。

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージの設定
• TypeScript の構成
• TreeGrid の基本的な初期化
• 最小限のデータバインディングの例
• 最初のツリー構造の設定

データの処理とバインディング

📄 参照: references/data-handling.md

• ローカルデータバインディング（階層構造と自己参照構造）
• childMapping を使用した階層データ（ネストされた配列）
• idMapping/parentIdMapping を使用した自己参照データ（フラットデータ）
• DataManager とアダプターを使用したリモートデータバインディング
• 子レコードを遅延読み込みするオンデマンド読み込み
• クライアント側の処理に対応したオフラインモード
• 機能を拡張するカスタムアダプター
• Fetch API を使用した AJAX バインディング
• パフォーマンスを最適化するイミュータブルモード
• DataManager を介したエラー処理と CRUD 操作

列の設定と機能

📄 参照: references/columns.md

• 列の基本（フィールドバインディング、型、主キー、列ごとの操作制御）
• 列の型（string、number、date、datetime、boolean）と書式設定
• ヘッダーのカスタマイズ（テキスト、テンプレート、カスタム HTML）
• 列テンプレートと値アクセサー（カスタム書式設定、計算列）
• ドット記法による複雑なデータバインディング（ネストされたオブジェクト、階層データ）
• 最小幅・最大幅の制約を使用した列のサイズ変更
• ドラッグ＆ドロップまたはプログラム API による列の並べ替え
• 列の表示制御（列ごとの表示／非表示）
• 並べ替え、フィルター、自動幅調整を実行する列メニュー
• エンドユーザーが表示を管理できる列選択メニュー
• セルを水平方向に結合する列スパン
• メディアクエリに応じて表示／非表示になるレスポンシブ列
• コンテンツの幅に合わせた列の自動調整
• 列の固定：isFrozen を指定した列を固定し、スクロール中も表示したままにします
• 固定方向：列を左側または右側に固定します（freeze: 'Left'|'Right'）
• 4 ゾーンレイアウトでの固定：frozenRows と frozenColumns を組み合わせ、マスター詳細グリッドを作成します

行の機能とテンプレート

📄 参照: references/row-features.md

• 行の選択モード（単一、複数）
• チェックボックスによる選択
• 行の詳細／テンプレートの展開
• 行のドラッグ＆ドロップ
• 行のインデントとスパン
• 行の高さの設定
• 行の固定：垂直スクロール中も上部の N 行を表示したままにします（frozenRows）
• 行と列の固定：マスター詳細グリッド用の 4 ゾーンレイアウトを作成します
• 階層構造での行の固定：固定された親行で展開／折りたたみが機能します
• 詳細テンプレートでの固定：固定行とマスター詳細パターンを組み合わせます

編集操作

📄 参照: references/editing.md

• CRUD 操作の設定（作成、読み取り、更新、削除）
• 編集モード（セル、行、ダイアログ、一括）とユースケース
• 編集の種類とコンポーネント（テキスト、数値、ドロップダウン、日付、チェックボックス）
• create/write/read パターンを使用したカスタム編集テンプレート
• フィールドの検証（必須、型、カスタムルール）
• ツールバーの操作と削除確認ダイアログ
• 組み込みおよびカスタムのボタンを備えたコマンド列
• デフォルト値と列編集の無効化
• URL Adaptor と Remote Save Adaptor を使用したサーバーへの永続化
• サーバー側の CRUD 操作ハンドラー（挿入、更新、削除、一括）

並べ替え機能

📄 参照: references/sorting.md

• 並べ替えの基本：列ヘッダーをクリックして昇順／降順を切り替えます
• 初期並べ替え：sortSettings を使用して、読み込み時のデフォルトの並べ替え列を設定します
• 複数列の並べ替え：CTRL+Click で複数の列を基準に並べ替えます
• 並べ替えの設定：特定の列の並べ替えを無効にし、デフォルトの順序を設定します
• 並べ替え方法：プログラムから並べ替え、または並べ替えを解除します（sortByColumn、clearSorting）
• 並べ替えイベント：並べ替えの開始／完了に応答します（actionBegin、actionComplete）
• 並べ替え UI：並べ替え方向を示す列ヘッダーアイコン
• タッチ操作：タッチデバイスでの複数列並べ替えポップアップ
• よくあるパターン：並べ替えとフィルターの組み合わせ、階層データの並べ替え動作

検索とクイック検索

📄 参照: references/searching.md

• 検索の基本：ツールバーの検索ボックスを有効にして、テキストベースの絞り込みを行います
• 初期検索：読み込み時のデフォルトの検索値と設定を指定します
• 検索演算子：contains、startswith、endswith、equal、notequalによる照合
• 検索設定：検索可能な列とignoreCaseの動作を設定します
• 外部検索ボタン：カスタムUIからプログラムで検索を実行します
• 特定の列を検索：検索対象を特定の列フィールドのみに限定します
• 検索メソッド：プログラムで検索するにはsearch()メソッドを使用します
• 一般的なパターン：検索＋並べ替え、検索＋フィルターの組み合わせ

フィルタリングオプション

📄 参照: references/filtering.md

• フィルタリングの基本と設定
• フィルター階層モード（Parent、Child、Both、None）
• filterSettings.columnsによる初期フィルター
• フィルター演算子と式
• カスタムテンプレートを使用したフィルターバー
• カスタムコンポーネントを使用したフィルターメニュー
• Excel風のフィルターインターフェース
• 発音区別符号と特殊文字の処理
• プログラムによるフィルタリングメソッド

集計とサマリー

📄 参照: references/aggregation.md

• 集計の種類（sum、average、count、min、max、custom）
• フッターへの集計値の表示
• グループ単位の集計
• カスタム集計テンプレート

Excelエクスポート

📄 参照: references/excel-export.md

• 階層構造を保持した基本的なExcelエクスポート
• エクスポートオプション：折りたたまれた状態の保持、非表示列の出力、エクスポート時の列の表示／非表示
• ファイル名のカスタマイズとカスタムデータソース
• セルのスタイル設定：条件付き書式（excelQueryCellInfoイベント）、テーマの適用
• スタイル設定可能なヘッダーとフッター、ハイパーリンク、配置
• サーバーサイドエクスポート：ASP.NET MVCの設定、serverExcelExportメソッド
• CSVエクスポート（サーバーサイド）：serverCsvExportメソッド
• excelAggregateQueryCellInfoイベントを使用したカスタム集計のエクスポート

PDFエクスポート

📄 参照: references/pdf-export.md

• 階層レイアウトを使用した基本的なPDFエクスポート
• エクスポートオプション：非表示列の出力、列の表示／非表示、ページの向き、ページサイズ
• ファイル名とフォントのカスタマイズ（標準フォント＋カスタムフォント）
• セルのスタイル設定：条件付き書式（pdfQueryCellInfoイベント）、テーマの適用
• ヘッダーとフッター：テキスト、線、ページ番号、配置を指定した画像
• サーバーサイドエクスポート：ASP.NET MVCの設定、serverPdfExportメソッド
• BeginCellLayoutイベントを使用したヘッダーの回転（サーバーサイドのみ）

パフォーマンスの最適化

📄 参照: references/performance.md

• パフォーマンスに関するベストプラクティス
• 変更検出の戦略
• データの遅延読み込みパターン
• メモリ管理
• 監視と最適化の手法

スタイルと外観

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

• テーマ設定：Material、Bootstrap、Fabric、HighContrast、Tailwind
• CSSのカスタマイズ：カスタムCSSクラスでデフォルトのスタイルを上書きします
• アダプティブUI：enableAdaptiveUIを有効にして、レスポンシブダイアログを備えたモバイル向けインターフェースを実現します
• CSSクラスのリファレンス：TreeGridのCSSクラス（ルート、ヘッダー、本文、ページャー、サマリー）の完全な一覧
• CSSクラスのカスタマイズ：対象を絞ったCSSで特定のセクションを上書きします

選択と操作

📄 参照： references/selection-and-interaction.md

• セルと行の選択モード
• チェックボックスによる選択
• マウスとキーボードでの操作
• コンテキストメニューの統合
• クリップボード操作（コピー、切り取り、貼り付け）
• 選択タイプ：単一または複数の行／セルの選択
• 選択モード：行選択、セル選択、両方のモード
• 行選択：初期選択、条件付き選択、選択した行のプログラムによる取得
• セル選択：フロー選択モードとボックス選択モード
• ヘッダーの全選択オプションを備えたチェックボックス選択
• プログラムによる選択の制御（selectRow、selectRows、getSelectedRecords）
• 選択の切り替え：選択済みの行をもう一度クリックして選択解除
• タッチ操作：タッチデバイスでの複数選択ポップアップ
• 選択イベントとイベントハンドラー（rowSelected、cellSelected）
• 選択した行に対する一括操作（削除、アーカイブなど）

コンテキストメニュー

📄 参照： references/context-menu.md

• コンテキストメニューの基本：ContextMenu モジュールの注入で有効化
• デフォルトのメニュー項目：AutoFit、Edit、Delete、Export、Sort、Page、Indent、Outdent
• カスタムメニュー項目：text、target、id プロパティを指定してカスタム項目を定義
• カスタム項目のアクション：contextMenuClick イベントハンドラーで処理
• 動的な有効化／無効化：contextMenuOpen イベントを使用して項目の利用可否を切り替え
• 対象別メニュー：target プロパティを使用して、ヘッダー、行、またはコンテンツ領域にメニューを表示
• 一般的なシナリオ：行の展開／折りたたみ、レコードの編集／削除、エクスポート操作

ページングの設定

📄 参照： references/paging.md

• Page モジュールの注入と allowPaging プロパティによるページングの設定
• ページサイズモード：All（合計件数）と Root（親の件数のみ）
• ページサイズのドロップダウン：ユーザーが1ページあたりの行数を動的に変更可能
• ページナビゲーションコントロールを備えたカスタムページャーテンプレート
• ページャーの配置：ページャーを下部から上部へ移動
• プログラムによるページ移動（goToPage、goToNextPage、goToPreviousPage）
• ページ変更イベント（requestType: 'paging' を含む actionComplete）
• 画面幅に応じたレスポンシブなページサイズ
• データ読み込みや UI 更新のためのページ変更の追跡

スクロールとパフォーマンス

📄 参照： references/scrolling.md

• 基本的なスクロール：固定の高さ／幅を持つコンテナーと自動スクロールバー
• レスポンシブなスクロール：親コンテナー内で高さ／幅を100%に設定
• 固定ヘッダー：enableStickyHeader を使用して、スクロール中も列ヘッダーを表示
• 行へのスクロール：特定の行へ移動、または選択した行を表示範囲内へスクロール
• 行の仮想化：10,000行以上のデータセットで表示中の行のみを描画（enableVirtualization）
• 列の仮想化：100列以上のグリッドで表示中の列のみを描画（enableColumnVirtualization）
• 無限スクロール：ユーザーの下方向へのスクロールに応じてバッファーページを読み込み（enableInfiniteScrolling）
• 無限スクロールのキャッシュモード：読み込み済みのページをキャッシュし、再取得を回避
• パフォーマンスの比較：ページング、仮想スクロール、無限スクロールを使い分ける場面
• 仮想スクロールと無限スクロール：クライアント側のデータには仮想スクロール、サーバー側のデータには無限スクロール
• 制限事項：仮想スクロール／無限スクロールは一括編集、詳細テンプレート、行テンプレートをサポートしません

高度な機能と操作

📄 参照： references/advanced-features.md

• 印刷：ツールバーの印刷ボタン、印刷モード（All／CurrentPage）、印刷時の列の表示／非表示
• ツールバー：組み込み項目、カスタムツールバーボタン、ツールバー項目の有効化／無効化
• クリップボード：コピー／貼り付けのショートカット、階層モード、一括編集での AutoFill
• 状態の永続化：永続化の有効化、localStorage の取得／設定、永続化されるプロパティ

読み込みアニメーション

📄 参照： references/loading-animation.md

• スピナーとシマーの読み込みインジケータータイプ
• データ操作中に自動表示
• リモートデータソースの読み込み

グローバルロケールとアクセシビリティ

📄 参照： references/global-local-accessibility.md

• ローカライズ：文化圏に応じた翻訳に L10n.load() を使用し、ロケールプロパティを設定します
• 依存コンポーネントのローカライズ：DatePicker、Form Validator、Grid
• 国際化：数値と日付の書式設定に loadCldr、setCulture、setCurrencyCode を使用します
• 右から左への表示（RTL）：アラビア語、ペルシア語、ウルドゥー語では enableRtl プロパティを有効にします
• アクセシビリティ基準への準拠：WCAG 2.2、Section 508、スクリーンリーダーのサポート基準
• WAI-ARIA 属性：role=treegrid、aria-selected、aria-expanded、aria-sort、aria-busy、aria-label
• キーボード操作：キーボードショートカット一式とアクセシビリティチェッカーによる検証

テストとテストヘルパー

📄 参照： references/testing-and-helpers.md

• ヘルパー API リファレンス：DOM 要素へのアクセスとプロパティ操作のための 20 種類以上のヘルパーメソッド
• Cypress のセットアップ：プロジェクトの初期化、Syncfusion パッケージのインストール、Cypress の設定
• TreeGridHelper の初期化：要素 ID を指定してヘルパーをインポートし、インスタンス化します
• setModel/getModel の使用：TreeGrid プロパティを動的に設定、取得します
• invoke 関数の使用：TreeGrid のメソッド（collapseAll、expandAll、print、export）をプログラムで呼び出します
• 要素アクセスのテスト：ヘッダー、フッター、ページャー、ダイアログ、フィルター、コンテンツの各要素を取得します
• テストケースの作成：プロパティへのアクセス、メソッドの呼び出し、UI 操作の完全な例
• Cypress の実行：インタラクティブモード、ヘッドレスモード、ブラウザーの選択、spec ファイルの指定
• ベストプラクティス：CSS セレクターの代わりにヘルパーを使用し、適切な待機時間を設け、データのセットアップとクリーンアップを行います

---

クイックスタートの例

vanilla Inject パターンを使った、最小構成の TypeScript TreeGrid セットアップを示します。

import { TreeGrid, Page, Edit } from '@syncfusion/ej2-treegrid';

// Data interface for type safety
interface TreeGridData {
  taskID: number;
  taskName: string;
  startDate: Date;
  endDate: Date;
  duration: number;
  progress: number;
  subtasks?: TreeGridData[];
}

// Sample hierarchical data
const data: TreeGridData[] = [
  {
    taskID: 1,
    taskName: 'Planning',
    startDate: new Date('02/03/2017'),
    endDate: new Date('02/07/2017'),
    duration: 5,
    progress: 100,
    subtasks: [
      {
        taskID: 2,
        taskName: 'Identify Site location',
        startDate: new Date('02/03/2017'),
        endDate: new Date('02/04/2017'),
        duration: 2,
        progress: 100
      },
      {
        taskID: 3,
        taskName: 'Perform soil test',
        startDate: new Date('02/04/2017'),
        endDate: new Date('02/05/2017'),
        duration: 1,
        progress: 100
      }
    ]
  }
];

// Inject required modules
TreeGrid.Inject(Page, Edit);

// Initialize TreeGrid
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: data,
    childMapping: 'subtasks',
    allowPaging: true,
    pageSettings: { pageSize: 10 },
    editSettings: { allowEditing: true, allowAdding: true, allowDeleting: true, mode: 'Row' },
    treeColumnIndex: 1,
    columns: [
        { field: 'taskID', headerText: 'Task ID', isPrimaryKey: true, width: 90, textAlign: 'Right' },
        { field: 'taskName', headerText: 'Task Name', width: 180, textAlign: 'Left' },
        { field: 'startDate', headerText: 'Start Date', width: 90, textAlign: 'Right', type: 'date', format: 'yMd' },
        { field: 'duration', headerText: 'Duration', width: 80, textAlign: 'Right' },
        { field: 'progress', headerText: 'Progress (%)', width: 80, textAlign: 'Right' }
    ]
});

treeGridObj.appendTo('#TreeGrid');