syncfusion-angular-treegrid（syncfusion Angular treegrid 搜索）

Syncfusion Angular TreeGrid

Complete guide to implementing and customizing the Syncfusion Angular TreeGrid component for hierarchical data visualization.

⚠️ Security & Trust Boundary

• The TreeGrid skill does not perform any remote data access.
• All external API interaction is handled by a separate DataManager skill outside this skill’s trust boundary.

Table of Contents

• When to Use This Skill
• Data Structure Rules
• Documentation Navigation Guide
• Quick Start Example
• Common Patterns
• Best Practices
• Key Props Summary
• Module Injection

When to Use This Skill

Use this skill when you need to:

• Display hierarchical or tree-structured data in a grid format
• Implement advanced data manipulation (sorting, filtering, searching, editing)
• Configure pagination, virtual scrolling for large datasets
• Add export functionality (PDF, Excel)
• Customize appearance with themes and CSS
• Handle selection, aggregates, and state management
• Support mobile/responsive design
• Implement row/column freezing

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
<ejs-treegrid
  [dataSource]='data'
  childMapping='subtasks'>  // Property name is case-sensitive
</ejs-treegrid>

// ❌ WRONG - Will not work
<ejs-treegrid
  [dataSource]='data'>
  <!-- No expansion possible without childMapping -->
</ejs-treegrid>

Data Format:

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

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

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

Rule 2: Data Type Matching is MANDATORY

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

Requirement:

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

Documentation Navigation Guide

Getting Started & Setup

📄 Read: references/getting-started-guide.md

• Complete installation and setup
• Module configuration
• Project initialization
• First TreeGrid component

API Quick Reference

📄 Read: references/properties.md

• 70+ properties in organized tables
• Data binding, display, behavior, features
• Settings objects and modules
• Column properties quick reference

📄 Read: references/methods.md

• 60+ methods in organized tables
• Data management, selection, expand/collapse
• Filtering, sorting, export, editing
• DOM access and utility methods

📄 Read: references/events.md

• 56+ events in organized tables
• Cancelable events and async patterns
• Data, action, selection, edit events
• Export, print, and query events

Recommended for developers who need quick property/method/event lookup

Data Binding

📄 Read: references/data-binding.md

• Local and remote data binding
• ORM and custom adaptor implementation
• Loading data from various sources

Adaptors for Remote Data

📄 Read: references/adaptors.md

• 7 adaptor types for backend integration
• UrlAdaptor, ODataV4Adaptor, WebApiAdaptor, GraphQLAdaptor
• Custom adaptors and RemoteSaveAdaptor
• Backend configuration examples (C#, Node.js)
• Request/response format specifications
• Error handling and adaptor comparison

Observables Data

📄 Read: references/observables.md

• RxJS observables integration
• Async data binding patterns
• Observable-based event handling
• Async operators and pipelines

Column Configuration

📄 Read: references/column.md

• Column definition and width management
• Custom column templates and rendering
• Column reordering and freezing

Column Spanning

📄 Read: references/column-spanning.md

• Multi-column spanning configuration
• Cell spanning across columns
• Dynamic span calculation

Command Columns

📄 Read: references/command-column.md

• Command column with action buttons
• Edit, Delete, and Cancel buttons
• Custom command implementations

Column Menu

📄 Read: references/column-menu.md

• Column header context menu
• Sort, group, and filter menu items
• Custom column menu options

Column Chooser

📄 Read: references/column-chooser.md

• Column visibility toggle UI
• Show/hide columns dynamically
• Column chooser dialog configuration

Row Configuration

📄 Read: references/row.md

• Row templates and detail rows
• Row drag-drop functionality
• Row spanning and customization

Cell-Level Features

📄 Read: references/cell.md

• Cell styling and formatting
• Cell templates and tooltips
• Custom CSS and HTML content

Module System & Architecture

📄 Read: references/modules.md

• Module imports and dependencies
• Required service providers
• Angular version compatibility
• Library setup and initialization

Editing

📄 Read: references/editing.md

• Cell, inline, dialog, row, and batch editing
• Data validation and error handling
• Custom editors and validation rules

Sorting

📄 Read: references/sorting.md

• Single and multi-column sorting
• Custom sort comparers
• Sort order and keyboard navigation

Filtering

📄 Read: references/filtering.md

• Filter bar and menu modes
• Excel-like filtering
• Custom filters and predicates

Searching

📄 Read: references/searching.md

• Global and column-level search
• Case-sensitive searching
• Text highlighting

Selection

📄 Read: references/selection.md

• Row, cell, and checkbox selection modes
• Selection events and APIs
• Programmatic selection

Paging

📄 Read: references/paging.md

• Pagination configuration
• Server-side paging
• Page navigation APIs

Scrolling

📄 Read: references/scrolling.md

• Virtual scrolling for large datasets
• Infinite scroll and lazy loading
• Height/width management and scroll positioning

Frozen Columns

📄 Read: references/frozen-columns.md

• Freeze rows and columns
• Fixed visibility configuration
• Performance optimization

Aggregations

📄 Read: references/aggregates.md

• Summary calculations (Sum, Avg, Min, Max, Count)
• Footer templates and child aggregates
• Aggregate events

Export & Print

📄 Read: references/print.md

• Print functionality and modes
• Page setup and column visibility
• Custom print templates

📄 Read: references/pdf-export.md

• PDF export with styling
• Headers, footers, and watermarks
• Server-side export

📄 Read: references/excel-export.md

• Excel export configuration
• Cell styling and formatting
• Merged cells and custom data

📄 Read: references/csv-export.md

• CSV export configuration
• Custom data formatting for export
• Dynamic file naming
• Export events and callbacks
• Selected records export

User Interface & Interaction

📄 Read: references/toolbar.md

• Built-in toolbar items
• Custom toolbar items and alignment
• Toolbar event handling

📄 Read: references/clipboard.md

• Copy/paste operations
• Custom clipboard formats
• Clipboard event handling

📄 Read: references/context-menu.md

• Context menu configuration
• Built-in and custom menu items
• Menu event handling

Appearance & Responsiveness

📄 Read: references/adaptive.md

• Responsive and adaptive design
• Mobile optimization
• Breakpoints and device detection

📄 Read: references/styling.md

• Built-in themes (Material, Bootstrap, Fabric, Tailwind)
• CSS customization and overrides
• Row/cell conditional styling

Performance

📄 Read: references/performance-optimization.md

• Virtual scrolling and lazy loading
• Pagination for large datasets
• Column virtualization and rendering optimization
• Query optimization strategies

State Management

📄 Read: references/state-persistence.md

• Save and restore grid state
• LocalStorage integration
• Custom state management

Foreign-key

📄 Read: references/foreign-keys.md

• Foreign key column configuration
• Display text mapping for FK values
• Dropdown editors for FK fields
• Cascading foreign key relationships
• Remote data binding for FK data

Row Drag and Drop

📄 Read: references/row-drag-drop.md

• Hierarchical drag-and-drop operations
• Parent-child relationship updates
• Circular hierarchy prevention
• Drop event validation and constraints
• Visual feedback during drag operations

Validation

📄 Read: references/validation.md

• Built-in and custom validation rules
• Async validation against server
• Cross-field validation patterns
• Server-side validation strategies
• Error display and highlighting
• Conditional validation rules

Globalization

📄 Read: references/globalization.md

• Localization and language support
• RTL (Right-to-Left) support
• Cultural formatting and date/number formats

Loading Animation

📄 Read: references/loading-animation.md

• Loading spinner configuration
• Custom loading templates
• Loading animation customization

Accessibility & Compliance

📄 Read: references/accessibility.md

• WCAG 2.1 Level AA conformance
• ARIA labels and attributes
• Keyboard navigation and screen reader support
• Focus management and visual indicators
• Accessibility testing guidance

Quick Start Example

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

Best Practices

1. Performance Optimization

- Use virtual scrolling for large datasets (10,000+ records) - Implement server-side operations (sorting, filtering, paging) - Use frozen columns sparingly to avoid layout shifts

1. Data Management

- Always provide a primary key (isPrimaryKey='true') - Use ChildMapping for hierarchical data - Implement proper error handling for API calls

1. User Experience

- Provide loading indicators during data fetch - Implement search and filter for data discovery - Show validation messages for editing errors - Support keyboard navigation and accessibility

1. Customization

- Use themes for consistent styling - Create reusable cell templates for common patterns - Style conditional rows for user guidance - Implement responsive design for mobile devices

1. State Management

- Enable state persistence for user preferences - Save sort, filter, and column settings

Key Props Summary

Module Injection

Must inject required services:

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