syncfusion-angular-treegrid

Syncfusion Angular TreeGrid

階層データを可視化する Syncfusion Angular TreeGrid コンポーネントの実装とカスタマイズに関する完全ガイドです。

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

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

目次

• このスキルを使用する場合
• データ構造のルール
• ドキュメントの参照ガイド
• クイックスタートの例
• 一般的なパターン
• ベストプラクティス
• 主要な Props の概要
• モジュールの注入

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

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

• 階層データやツリー構造のデータをグリッド形式で表示する
• 高度なデータ操作（並べ替え、フィルタリング、検索、編集）を実装する
• 大規模なデータセット向けにページネーションや仮想スクロールを設定する
• エクスポート機能（PDF、Excel）を追加する
• テーマや CSS で外観をカスタマイズする
• 選択、集計、状態管理を処理する
• モバイル／レスポンシブデザインに対応する
• 行／列の固定を実装する

データ構造のルール

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

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

要件：

// ✅ REQUIRED - Must match data property name exactly
<ejs-treegrid 
  [dataSource]='data'
  childMapping='subtasks'>  // Property name is case-sensitive
</ejs-treegrid>

// ❌ WRONG - Will not work
<ejs-treegrid 
  [dataSource]='data'>
  
</ejs-treegrid>

データ形式：

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

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

// Alternative: Flat structure with parent IDs
<ejs-treegrid 
  [dataSource]='flatData'
  idMapping='TaskID'
  parentIdMapping='ParentID'
  hasChildMapping='isParent'>
</ejs-treegrid>

ルール 2：データ型を一致させる必要があります

重要度：🟠 重要 - 型の不一致は描画や並べ替えの問題を引き起こします

要件：

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

// Column definition must match data types
<e-columns>
  <e-column field='TaskID' headerText='ID' type='number'></e-column>
  <e-column field='TaskName' headerText='Task' type='text'></e-column>
  <e-column field='StartDate' headerText='Date' type='date' format='yMd'></e-column>
</e-columns>

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

ドキュメントの参照ガイド

はじめにとセットアップ

📄 参照： references/getting-started-guide.md

• インストールとセットアップの全手順
• モジュールの設定
• プロジェクトの初期化
• 最初の TreeGrid コンポーネント

API クイックリファレンス

📄 参照： references/properties.md

• 整理された表にまとめた 70 以上のプロパティ
• データバインディング、表示、動作、機能
• 設定オブジェクトとモジュール
• 列プロパティのクイックリファレンス

📄 参照： references/methods.md

• 整理された表にまとめた 60 以上のメソッド
• データ管理、選択、展開／折りたたみ
• フィルタリング、並べ替え、エクスポート、編集
• DOM アクセスとユーティリティメソッド

📄 参照： references/events.md

• 整理された表にまとめた 56 以上のイベント
• キャンセル可能なイベントと非同期パターン
• データ、操作、選択、編集のイベント
• エクスポート、印刷、クエリのイベント

推奨：プロパティ、メソッド、イベントをすばやく参照する必要がある開発者向けです。

データバインディング

📄 参照： references/data-binding.md

• ローカルおよびリモートのデータバインディング
• ORM とカスタムアダプターの実装
• さまざまなソースからのデータ読み込み

リモートデータ用アダプター

📄 参照： references/adaptors.md

• バックエンド連携用の 7 種類のアダプター
• UrlAdaptor、ODataV4Adaptor、WebApiAdaptor、GraphQLAdaptor
• カスタムアダプターと RemoteSaveAdaptor
• バックエンドの設定例（C#、Node.js）
• リクエスト／レスポンス形式の仕様
• エラー処理とアダプターの比較

Observable データ

📄 参照： references/observables.md

• RxJS Observable との連携
• 非同期データバインディングのパターン
• Observable ベースのイベント処理
• 非同期オペレーターとパイプライン

列の設定

📄 参照： references/column.md

• 列の定義と幅の管理
• カスタム列テンプレートと描画
• 列の並べ替えと固定

列の結合

📄 参照： references/column-spanning.md

• 複数列にまたがる結合の設定
• 列をまたぐセルの結合
• 動的な結合範囲の計算

コマンド列

📄 参照： references/command-column.md

• アクションボタン付きのコマンド列
• 編集、削除、キャンセルボタン
• カスタムコマンドの実装

列メニュー

📄 参照： references/column-menu.md

• 列ヘッダーのコンテキストメニュー
• 並べ替え、グループ化、フィルターメニュー項目
• カスタム列メニューオプション

列選択

📄 参照： references/column-chooser.md

• 列の表示切り替え UI
• 列の動的な表示／非表示
• 列選択ダイアログの設定

行の設定

📄 参照： references/row.md

• 行テンプレートと詳細行
• 行のドラッグ＆ドロップ機能
• 行の結合とカスタマイズ

セルレベルの機能

📄 参照： references/cell.md

• セルのスタイル設定と書式設定
• セルテンプレートとツールチップ
• カスタム CSS と HTML コンテンツ

モジュールシステムとアーキテクチャ

📄 参照： references/modules.md

• モジュールのインポートと依存関係
• 必須のサービスプロバイダー
• Angular のバージョン互換性
• ライブラリのセットアップと初期化

編集

📄 参照： references/editing.md

• セル、インライン、ダイアログ、行、バッチ編集
• データ検証とエラー処理
• カスタムエディターと検証ルール

並べ替え

📄 参照： references/sorting.md

• 単一列および複数列の並べ替え
• カスタム並べ替え比較関数
• 並べ替え順序とキーボードナビゲーション

フィルタリング

📄 参照： references/filtering.md

• フィルターバーとメニューモード
• Excel のようなフィルタリング
• カスタムフィルターと述語

検索

📄 参照： references/searching.md

• 全体検索と列レベルの検索
• 大文字と小文字を区別する検索
• テキストのハイライト表示

選択

📄 参照： references/selection.md

• 行、セル、チェックボックスの選択モード
• 選択イベントと API
• プログラムによる選択

ページング

📄 参照： references/paging.md

• ページネーションの設定
• サーバーサイドページング
• ページナビゲーション API

スクロール

📄 参照： references/scrolling.md

• 大規模なデータセット向けの仮想スクロール
• 無限スクロールと遅延読み込み
• 高さ／幅の管理とスクロール位置

固定列

📄 参照： references/frozen-columns.md

• 行と列の固定
• 固定表示の設定
• パフォーマンスの最適化

集計

📄 参照： references/aggregates.md

• 集計計算（Sum、Avg、Min、Max、Count）
• フッターテンプレートと子集計
• 集計イベント

エクスポートと印刷

📄 参照： references/print.md

• 印刷機能とモード
• ページ設定と列の表示状態
• カスタム印刷テンプレート

📄 参照： references/pdf-export.md

• スタイル設定付き PDF エクスポート
• ヘッダー、フッター、透かし
• サーバーサイドエクスポート

📄 参照： references/excel-export.md

• Excel エクスポートの設定
• セルのスタイル設定と書式設定
• セルの結合とカスタムデータ

📄 参照： references/csv-export.md

• CSV エクスポートの設定
• エクスポート用のカスタムデータ書式設定
• 動的なファイル名設定
• エクスポートイベントとコールバック
• 選択したレコードのエクスポート

ユーザーインターフェイスと操作

📄 参照： references/toolbar.md

• 組み込みツールバー項目
• カスタムツールバー項目と配置
• ツールバーイベントの処理

📄 参照： references/clipboard.md

• コピー／貼り付け操作
• カスタムクリップボード形式
• クリップボードイベントの処理

📄 参照： references/context-menu.md

• コンテキストメニューの設定
• 組み込みおよびカスタムのメニュー項目
• メニューイベントの処理

外観とレスポンシブ対応

📄 参照： references/adaptive.md

• レスポンシブデザインとアダプティブデザイン
• モバイル向けの最適化
• ブレークポイントとデバイス検出

📄 参照： references/styling.md

• 組み込みテーマ（Material、Bootstrap、Fabric、Tailwind）
• CSS のカスタマイズとオーバーライド
• 行／セルの条件付きスタイル設定

パフォーマンス

📄 参照： references/performance-optimization.md

• 仮想スクロールと遅延読み込み
• 大規模なデータセット向けのページネーション
• 列の仮想化とレンダリングの最適化
• クエリの最適化戦略

状態管理

📄 参照： references/state-persistence.md

• グリッドの状態の保存と復元
• LocalStorage との連携
• カスタム状態管理

外部キー

📄 参照： references/foreign-keys.md

• 外部キー列の設定
• 外部キー値の表示テキストのマッピング
• 外部キーフィールド用のドロップダウンエディター
• 外部キーの連鎖関係
• 外部キーデータのリモートデータバインディング

行のドラッグ＆ドロップ

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

• 階層構造でのドラッグ＆ドロップ操作
• 親子関係の更新
• 循環階層の防止
• ドロップイベントの検証と制約
• ドラッグ操作中の視覚的フィードバック

検証

📄 参照： references/validation.md

• 組み込みの検証ルールとカスタム検証ルール
• サーバーに対する非同期検証
• フィールド間検証のパターン
• サーバー側の検証戦略
• エラーの表示と強調表示
• 条件付き検証ルール

国際化

📄 参照： references/globalization.md

• ローカライズと言語サポート
• RTL（右から左）への対応
• 文化に応じた書式設定と日付／数値形式

読み込みアニメーション

📄 参照： references/loading-animation.md

• 読み込みスピナーの設定
• カスタム読み込みテンプレート
• 読み込みアニメーションのカスタマイズ

アクセシビリティとコンプライアンス

📄 参照： references/accessibility.md

• WCAG 2.1 レベル AA への適合
• ARIA ラベルと属性
• キーボード操作とスクリーンリーダーのサポート
• フォーカス管理と視覚的なインジケーター
• アクセシビリティのテストに関するガイダンス

クイックスタートの例

import { Component, ViewChild } from '@angular/core';
import { TreeGridComponent } from '@syncfusion/ej2-angular-treegrid';
import { PageService, SortService, FilterService, EditService } from '@syncfusion/ej2-angular-treegrid';

@Component({
  selector: 'app-treegrid',
  template: `
    <ejs-treegrid 
      #treegrid
      [dataSource]='data'
      [childMapping]='childMapping'
      [allowPaging]='true'
      [allowSorting]='true'
      [allowFiltering]='true'
      <e-columns>
        <e-column field='TaskID' headerText='Task ID' width='90' isPrimaryKey='true'></e-column>
        <e-column field='TaskName' headerText='Task Name' width='200'></e-column>
      </e-columns>
    </ejs-treegrid>
  `,
  providers: [PageService, SortService, FilterService, EditService]
})
export class AppComponent {
  @ViewChild('treegrid') treegrid!: TreeGridComponent;

  public data: Object[] = [
    {
      TaskID: 1,
      TaskName: 'Planning',
      subtasks: [
        { TaskID: 2, TaskName: 'Scope', Duration: 4, Progress: 100 },
        { TaskID: 3, TaskName: 'Budget', Duration: 4, Progress: 100 }
      ]
    }
  ];
  
  public childMapping: string = 'subtasks';
  
  public editSettings = { mode: 'Cell', allowEditing: true, allowDeleting: true, allowAdding: true };
}

ベストプラクティス

1. パフォーマンスの最適化

   • 大規模なデータセット（10,000 件以上のレコード）には仮想スクロールを使用します
   • サーバー側の処理（並べ替え、フィルタリング、ページング）を実装します
   • レイアウトのずれを避けるため、固定列は必要最小限にします

2. データ管理

   • 必ず主キー（isPrimaryKey='true'）を指定します
   • 階層データには ChildMapping を使用します
   • API 呼び出しには適切なエラー処理を実装します

3. ユーザーエクスペリエンス

   • データの取得中に読み込みインジケーターを表示します
   • データを見つけやすくするため、検索とフィルターを実装します
   • 編集エラーに対する検証メッセージを表示します
   • キーボード操作とアクセシビリティに対応します

4. カスタマイズ

   • 一貫したスタイル設定にはテーマを使用します
   • よく使うパターンには再利用可能なセルテンプレートを作成します
   • ユーザーを支援するため、条件付きで行にスタイルを適用します
   • モバイルデバイス向けにレスポンシブデザインを実装します

5. 状態管理

   • ユーザー設定を保持するため、状態の永続化を有効にします
   • 並べ替え、フィルター、列の設定を保存します

主要な Props の概要

Prop	型	デフォルト	使用例
dataSource	DataManager|Object[]	null	グリッドのデータソースを設定
childMapping	string	null	子レコードのプロパティ（明示的に設定する必要があります）
allowPaging	boolean	false	ページネーションを有効化
allowSorting	boolean	false	並べ替えを有効化
allowFiltering	boolean	false	フィルタリングを有効化
editSettings	EditSettings	{}	編集モードを設定
enableVirtualization	boolean	false	仮想スクロールを有効化

モジュールのインジェクション

必要なサービスをインジェクションする必要があります：

import { PageService, SortService, FilterService, EditService, ExcelExportService, PdfExportService,
  PrintService, AggregateService, ToolbarService } from '@syncfusion/ej2-angular-treegrid';

@Component({
  providers: [
    PageService, 
    SortService, 
    FilterService, 
    EditService,
    ExcelExportService,
    PdfExportService,
    PrintService,
    AggregateService,
    ToolbarService
  ]
})