syncfusion-react-treegrid（syncfusion React treegrid 搜索）

Syncfusion React TreeGrid

A comprehensive skill for implementing and customizing Syncfusion's React TreeGrid component. TreeGrid visualizes self-referential hierarchical data in a tabular layout with expand/collapse functionality, enterprise features like virtual scrolling, and comprehensive export options.

Table of Contents

• When to Use This Skill
• TreeGrid Overview
• Data Structure Rules
• Documentation Navigation Guide
• Quick Start Example

When to Use This Skill

Use this skill when you need to:

• Display hierarchical or tree-structured data (organizational charts, file systems, bill of materials)
• Configure columns with proper data binding and formatting
• Implement data editing (cell, row, dialog, batch, template modes)
• Add sorting, filtering, and searching capabilities
• Handle row and cell operations (selection, templates, spanning)
• Optimize performance with virtual scrolling or infinite scrolling
• Configure paging and scrolling strategies
• Export data to PDF, Excel, or CSV formats
• Implement state persistence and aggregation
• Customize appearance with themes and styling
• Support accessibility and internationalization (RTL, localization)

TreeGrid Overview

The TreeGrid is optimized for displaying self-referential hierarchical data with:

• Auto-expand/collapse functionality for collapsible rows
• Enterprise features: virtual scrolling, aggregates, state persistence
• Adaptive UI for mobile and small screens
• Comprehensive export: PDF, Excel, CSV formats
• Full accessibility: WCAG compliance, keyboard navigation, ARIA support
• Internationalization: RTL support, locale customization

Data Structure Rules

Rule 1: childMapping is MANDATORY for Hierarchical Data

Severity: 🔴 CRITICAL - Grid will not expand/collapse without this

Requirement:

// ✅ 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>

Data Format:

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

Exception: Use idMapping + parentIdMapping for flat parent-child structure:

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

Rule 2: Data Type Matching is MANDATORY

Severity: 🟠 IMPORTANT - Type mismatches cause rendering/sorting issues

Requirement:

// ✅ 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
  }
];

Complete Props Reference

📄 Property and Methods: references/programmatic-api.md

📄 Events Reference 📖 references/events-reference.md

• Complete event reference guide
• Data events (actionBegin, actionComplete, actionFailure)
• Editing events (cellEdit, cellSave, beforeEdit)
• Selection events (rowSelected, rowDeselected, cellSelected)
• Expand/collapse events
• Column events (drag, drop, resize, hide, show)
• Row events and utilities

Documentation Navigation Guide

Data Binding

📖 references/data-binding.md

• Local vs. remote data sources
• Self-referential parent-child relationships
• DataManager integration
• ExpandStateMapping for initial expand state
• Complex data binding for nested objects

Column Configuration

📖 references/column.md

• Column definitions and field mapping
• Tree column index setup
• Data types and formatting
• Column templates and custom rendering
• Headers and styling
• Foreign key columns

Row Operations

📖 references/row.md

• Row templates and custom rendering
• Row height configuration
• Row spanning
• Detail templates for nested content
• Row drag-and-drop
• Indent and outdent operations

Cell Operations

📖 references/cell.md

• Cell editing
• Cell templates, styling and attributes
• Cell selection
• Cell formatting

Editing

📖 references/editing.md

• Cell editing mode
• Row editing mode
• Dialog editing
• Batch editing
• Template editing
• Validation rules and custom validators
• Command column editing
• Server-side persistence

Sorting

📖 references/sorting.md

• Single and multi-column sorting
• Initial sort order configuration
• Custom sort comparers
• Sorting with templates
• Programmatic sorting

Filtering

📖 references/filtering.md

• Filter bar mode
• Filter menu mode
• Excel-like filtering
• Custom filters
• Programmatic filtering
• Filter templates

Searching

📖 references/searching.md

• Global search across all columns
• Search highlight
• Programmatic search
• Search with templates

Selection

📖 references/selection.md

• Row selection (single and multiple)
• Cell selection
• Checkbox selection
• Selection mode configuration
• Programmatic selection
• Selection change events

Display & Layout (Performance & Presentation)

📄 Paging 📖 references/paging.md

• Pager configuration and options
• Page size settings
• Initial page settings
• Pager template customization
• Programmatic pagination

📄 Scrolling 📖 references/scrolling.md

• Vertical and horizontal scrolling
• Scroll height configuration
• Scroll position control
• Sticky headers
• Responsive scrolling

📄 Frozen Rows and Columns 📖 references/frozen-rows-columns.md

• Freeze header rows
• Freeze columns
• Freeze direction
• Lock columns
• IsFrozen property usage

📄 Virtual Scrolling & Infinite Scrolling 📖 references/virtual-scrolling-infinite-scrolling.md

• Virtual scrolling for large datasets
• Infinite scrolling configuration
• Row height for virtual scroll
• ViewportIndex and ViewportStartIndex
• Performance optimization with virtual scroll

Aggregates

📖 references/aggregates.md

• Standard aggregates (Sum, Average, Min, Max, Count)
• Custom aggregates
• Footer aggregates
• Group aggregates
• Hierarchical aggregates for child data

State Persistence

📖 references/state-persistence.md

• Global state persistence
• Local state persistence
• ExpandState tracking
• Persist sort, filter, and paging
• State restoration on reload

Toolbar

📖 references/toolbar.md

• Built-in toolbar items
• Custom toolbar items
• Toolbar item types (Button, Separator, Dropdown)
• Toolbar item click handling
• Toolbar template customization

Context Menu

📖 references/context-menu.md

• Built-in context menu items
• Custom context menu items
• Menu item click handling
• Copy/Edit/Delete operations
• Header context menu

Adaptive View

📖 references/adaptive-view.md

• Adaptive UI for small screens
• Full-screen dialogs
• Horizontal row rendering
• Responsive column adjustments
• Mobile optimization

Loading Animation

📖 references/loading-animation.md

• Loading indicator display
• Custom loading spinner
• Loading state management
• Spinner animation control

Export & Print

📄 PDF Export 📖 references/pdf-export.md

• PDF export configuration
• Export options (columns, format)
• Headers and footers
• Page orientation and size
• Server-side export
• Exporting hierarchical data

📄 Excel Export 📖 references/excel-export.md

• Excel export configuration
• Export options (columns, formatting)
• Cell styling in export
• Headers and footers
• Server-side export
• Exporting hierarchical levels

📄 Print 📖 references/print.md

• Print configuration
• Print with custom layout
• Print specific ranges
• Print hierarchy levels
• Print preview

Clipboard

📖 references/clipboard.md

• Copy cell content to clipboard
• Copy entire rows
• Paste operations
• Copy hierarchy with levels
• Clipboard event handling

Column Features (Advanced)

📄 Column Reorder 📖 references/column-reorder.md

• Enable column drag-and-drop reordering
• Prevent specific columns from reordering
• Reorder events and callbacks
• Programmatic column reordering

📄 Column Resize 📖 references/column-resize.md

• Enable column drag resize
• Auto-fit columns to content
• Column width constraints (min/max)
• Resize events
• Programmatic width changes
• Save/restore column widths

📄 Column Menu 📖 references/column-menu.md

• Built-in column menu items
• Sort, filter, and column chooser from menu
• Custom menu items
• Menu events and handlers
• Conditional menu items

📄 Column Chooser 📖 references/column-chooser.md

• Toggle column visibility
• Column chooser dialog configuration
• Show/hide columns programmatically
• Column visibility events
• Save/restore column visibility

📄 Command Column 📖 references/command-column.md

• Built-in command buttons (Edit, Delete, Save, Cancel)
• Custom command buttons
• Command click handlers
• Icon customization
• Row action patterns

Server Integration

📖 references/server-integration.md

• Remote data binding with DataManager
• Server-side CRUD operations
• Server-side filtering and sorting
• Server-side paging
• Custom request/response handling
• Error handling strategies
• Batch operations

Validation Patterns

📖 references/validation-patterns.md

• Column validation rules
• Custom validation logic
• Cross-field validation
• Async validation (API calls)
• Server-side validation
• Dialog form validation
• Conditional validation
• Error message display

Performance Optimization

📖 references/performance-optimization.md

• Virtual scrolling for large datasets (100k+ rows)
• Infinite scrolling with caching
• Bundle size optimization
• Disabling unnecessary features
• Server-side operations optimization
• Memoization and rendering optimization
• Template optimization
• Event handler optimization
• Benchmarking and performance monitoring
• Performance checklist

Customization

📖 references/styling-appearance.md

• CSS class customization
• Theme selection (Material, Bootstrap, Fluent, Tailwind)
• CSS variable overrides
• Component-specific styling
• Dark mode support
• Row styling
• Cell styling

Globalization

📖 references/globalization.md

• Internationalization (i18n)
• Localization (l10n) for UI text
• Right-to-left (RTL) support
• Date formatting per locale
• Number formatting per locale
• Currency localization

Accessibility

📖 references/accessibility.md

• WCAG 2.1 Level AA compliance
• Keyboard navigation (all shortcuts)
• ARIA attributes and screen reader support
• Expand/collapse keyboard shortcuts
• Editing keyboard navigation
• Selection shortcuts

Quick Start Example

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>
  );
}

Core Configuration