syncfusion-react-data-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React DataManager

The DataManager is a gateway component for managing local and remote data operations in React applications. It acts as an abstraction layer that enables seamless data binding, querying, CRUD operations, caching, and middleware customization without writing complex server communication code.

Use this skill whenever a user needs to:

Bind local or remote data sources to UI components
Query data (filter, sort, page, group, search)
Perform CRUD operations (insert, update, delete, batch edits)
Work with different data sources (JSON, OData, REST APIs, GraphQL, etc.)
Cache data for performance
Implement offline mode
Add custom headers or authentication
Transform request/response data
Handle complex data scenarios in React applications

DataManager是用于在React应用中管理本地和远程数据操作的网关组件。它作为抽象层，无需编写复杂的服务端通信代码即可实现流畅的数据绑定、查询、CRUD操作、缓存和中间件自定义功能。

当用户有以下需求时可使用本技能：

将本地或远程数据源绑定到UI组件
查询数据（过滤、排序、分页、分组、搜索）
执行CRUD操作（新增、更新、删除、批量编辑）
对接不同数据源（JSON、OData、REST APIs、GraphQL等）
缓存数据提升性能
实现离线模式
添加自定义请求头或身份认证逻辑
转换请求/响应数据
在React应用中处理复杂数据场景

When to Use DataManager

什么时候使用DataManager

DataManager is best for:

Flexible data management → Works with any data source (local, REST, OData, GraphQL)
Complex queries → Filtering, sorting, paging, grouping, searching
CRUD operations → With batch support and transaction patterns
Middleware customization → Pre/post request hooks
Offline support → Cache and sync when connection restored
Adaptor switching → Change data sources without code changes

Direct component binding (Grid, Scheduler, etc.) is better when:

You only need basic data binding without complex querying
Performance is critical for very large datasets
You don't need middleware customization

DataManager 最适合以下场景：

灵活的数据管理 → 适配任意数据源（本地、REST、OData、GraphQL）
复杂查询 → 过滤、排序、分页、分组、搜索
CRUD操作 → 支持批量操作和事务模式
中间件自定义 → 请求前后钩子
离线支持 → 缓存数据，网络恢复后自动同步
适配器切换 → 无需修改业务代码即可更换数据源

直接组件绑定（Grid、Scheduler等）更适合以下场景：

仅需要基础数据绑定，无需复杂查询
超大数据集对性能要求极高
不需要自定义中间件

Key Concepts

核心概念

Data Binding

数据绑定

Connect DataManager to data sources using the json property (local arrays) or url property (remote APIs). Query methods: executeLocal() for local data, executeQuery() for remote data.

通过 json 属性（本地数组）或 url 属性（远程API）将DataManager连接到数据源。查询方法：本地数据使用 executeLocal()，远程数据使用 executeQuery()。

Query Class

Query类

Build structured queries using the Query class: from(), where(), select(), sortBy(), take(), expand(), group() chained together for powerful data operations.

使用Query类构建结构化查询：可链式调用 from()、where()、select()、sortBy()、take()、expand()、group() 实现强大的数据操作能力。

Adaptors

适配器

Adaptors are interfaces that enable DataManager to communicate with different data sources:

JsonAdaptor → Local JavaScript arrays
ODataAdaptor → OData v3 services
ODataV4Adaptor → OData v4 services
UrlAdaptor → Generic REST endpoints
WebApiAdaptor → ASP.NET Web API
RemoteSaveAdaptor → Hybrid client-side queries + server-side CRUD
WebMethodAdaptor → Legacy ASP.NET ASMX services
GraphQLAdaptor → GraphQL endpoints
CustomAdaptor → Custom implementation for proprietary services

Adaptor（适配器） 是DataManager与不同数据源通信的接口：

JsonAdaptor → 本地JavaScript数组
ODataAdaptor → OData v3服务
ODataV4Adaptor → OData v4服务
UrlAdaptor → 通用REST端点
WebApiAdaptor → ASP.NET Web API
RemoteSaveAdaptor → 混合模式：客户端查询 + 服务端CRUD
WebMethodAdaptor → 传统ASP.NET ASMX服务
GraphQLAdaptor → GraphQL端点
CustomAdaptor → 为专有服务自定义实现的适配器

CRUD Operations

CRUD操作

insert() → Add records to data source
update() → Modify existing records (keyField as first parameter)
remove() → Delete records (keyField as first parameter)
saveChanges() → Batch multiple operations into single request

insert() → 向数据源新增记录
update() → 修改现有记录（第一个参数为keyField）
remove() → 删除记录（第一个参数为keyField）
saveChanges() → 将多个操作合并为单个请求批量提交

Middleware & Customization

中间件与自定义

applyPreRequestMiddlewares() → Modify request before sending (auth tokens, headers)
applyPostRequestMiddlewares() → Transform response before binding (formatting, filtering)
Custom adaptors for proprietary APIs
Error handlers for request failures

applyPreRequestMiddlewares() → 发送请求前修改请求（添加认证令牌、请求头）
applyPostRequestMiddlewares() → 绑定数据前转换响应（格式化、过滤）
为专有API自定义适配器
请求失败的错误处理

Caching & Performance

缓存与性能

enableCache → Prevent re-requesting previously loaded pages
Offline mode → Store data locally, sync when connection restored
Load on demand → Lazy load data as user scrolls (virtual scrolling)
Deferred operations → Promise-based async/await patterns

enableCache → 避免重复请求已加载的分页数据
离线模式 → 本地存储数据，网络恢复后同步
按需加载 → 用户滚动时懒加载数据（虚拟滚动）
异步操作 → 基于Promise的async/await模式

Documentation & Navigation Guide

文档与导航指南

Choose the reference file based on your current task:

根据当前任务选择对应的参考文件：

Getting Started Setup

入门配置

📄 Read: references/getting-started.md

Installation steps (npm)
Project setup & imports
Basic DataManager initialization
First query execution
Environment setup
Common errors & fixes

📄 阅读： references/getting-started.md

安装步骤（npm）
项目配置与导入
基础DataManager初始化
首次查询执行
环境配置
常见错误与修复

Data Binding Strategies

数据绑定策略

📄 Read: references/data-binding.md

Local data binding with json property
Remote data binding with url property
executeLocal() for client-side queries
executeQuery() for server requests
Switching between data sources
Response format handling
When to use each approach

📄 阅读： references/data-binding.md

使用json属性绑定本地数据
使用url属性绑定远程数据
客户端查询使用executeLocal()
服务端请求使用executeQuery()
数据源切换
响应格式处理
不同方案的适用场景

Query Operations & Filtering

查询操作与过滤

📄 Read: references/querying-and-filtering.md

Query class fundamentals
Filtering with where() and Predicate
Sorting (ascending/descending)
Pagination with take() and skip()
Field projection with select()
Related data loading with expand()
Grouping data by field(s)
Complex multi-condition queries
Chaining query operations

📄 阅读： references/querying-and-filtering.md

Query类基础
使用where()和Predicate过滤
排序（升序/降序）
使用take()和skip()实现分页
使用select()实现字段投影
使用expand()加载关联数据
按字段分组
复杂多条件查询
链式查询操作

CRUD Operations & Batch Edits

CRUD操作与批量编辑

📄 Read: references/crud-operations.md

insert() → Add new records
update() → Modify existing records
remove() → Delete records
keyField in CRUD method parameters
saveChanges() for batch operations
Batch insert/update/remove
Transaction patterns
Data validation before operations
Response handling

📄 阅读： references/crud-operations.md

insert() → 新增记录
update() → 修改现有记录
remove() → 删除记录
CRUD方法参数中的keyField
批量操作使用saveChanges()
批量新增/更新/删除
事务模式
操作前数据校验
响应处理

Choosing & Using Adaptors

适配器选择与使用

📄 Read: references/adaptors-guide.md

Which adaptor to use (decision tree)
JsonAdaptor for local arrays
OData adaptors (v3 & v4)
REST API adaptors (Url, WebApi)
RemoteSaveAdaptor hybrid approach
Legacy ASMX (WebMethodAdaptor)
GraphQL endpoint integration
Custom adaptor implementation
CORS & crossDomain configuration
Platform-specific response handling

📄 阅读： references/adaptors-guide.md

如何选择适配器（决策树）
本地数组使用JsonAdaptor
OData适配器（v3和v4）
REST API适配器（Url、WebApi）
RemoteSaveAdaptor混合方案
传统ASMX服务（WebMethodAdaptor）
GraphQL端点集成
自定义适配器实现
CORS与跨域配置
平台专属响应处理

Middleware & Request Customization

中间件与请求自定义

📄 Read: references/middleware-customization.md

Pre-request middleware for auth tokens
Custom header injection
Request transformation
Post-request middleware for response mapping
Error handler functions
Data validation & filtering in middleware
Custom adaptor implementation
Middleware execution order & timing

📄 阅读： references/middleware-customization.md

前置请求中间件添加认证令牌
自定义请求头注入
请求转换
后置请求中间件做响应映射
错误处理函数
中间件中的数据校验与过滤
自定义适配器实现
中间件执行顺序与时机

Caching & Offline Mode

缓存与离线模式

📄 Read: references/caching-offline-mode.md

enableCache property for performance
When cache clears (sort, filter, CRUD)
Offline mode implementation
Local storage persistence
Sync strategies after reconnection
Cache size & memory management
Best practices & performance patterns

📄 阅读： references/caching-offline-mode.md

enableCache属性提升性能
缓存清空时机（排序、过滤、CRUD）
离线模式实现
本地存储持久化
重连后的同步策略
缓存大小与内存管理
最佳实践与性能模式

Advanced Features & Patterns

高级功能与模式

📄 Read: references/advanced-features.md

Load on demand & pagination patterns
Virtual scrolling setup
Lazy loading data
Deferred operations (Promise API)
Async/await with DataManager
State persistence across sessions
Memory management
Error handling strategies
Performance optimization tips
Common pitfalls & solutions

📄 阅读： references/advanced-features.md

按需加载与分页模式
虚拟滚动配置
数据懒加载
异步操作（Promise API）
DataManager结合async/await使用
跨会话状态持久化
内存管理
错误处理策略
性能优化技巧
常见陷阱与解决方案

Quick Start Example

快速入门示例

tsx

import React, { useEffect, useState } from 'react';
import { DataManager, WebApiAdaptor, Query } from '@syncfusion/ej2-data';

export default function DataManagerDemo() {
  const [items, setItems] = useState([]);

  useEffect(() => {
    // Create DataManager with remote data source
    const dataManager = new DataManager({
      url: 'url',
      adaptor: new WebApiAdaptor(),
      crossDomain: true
    });

    // Execute query with filtering, sorting, paging
    dataManager.executeQuery(
      new Query()
        .where('Freight', 'greaterthan', 500) // Filter
        .sortBy('OrderDate') // Sort
        .take(10) // Pagination
    ).then((e) => {
      setItems(e.result); // Bind results
    });
  }, []);

  return (
    <div>
      <h2>Orders</h2>
      <ul>
        {items.map((item) => (
          <li key={item.OrderID}>{item.CustomerID} - ${item.Freight}</li>
        ))}
      </ul>
    </div>
  );
}

tsx

import React, { useEffect, useState } from 'react';
import { DataManager, WebApiAdaptor, Query } from '@syncfusion/ej2-data';

export default function DataManagerDemo() {
  const [items, setItems] = useState([]);

  useEffect(() => {
    // Create DataManager with remote data source
    const dataManager = new DataManager({
      url: 'url',
      adaptor: new WebApiAdaptor(),
      crossDomain: true
    });

    // Execute query with filtering, sorting, paging
    dataManager.executeQuery(
      new Query()
        .where('Freight', 'greaterthan', 500) // Filter
        .sortBy('OrderDate') // Sort
        .take(10) // Pagination
    ).then((e) => {
      setItems(e.result); // Bind results
    });
  }, []);

  return (
    <div>
      <h2>Orders</h2>
      <ul>
        {items.map((item) => (
          <li key={item.OrderID}>{item.CustomerID} - ${item.Freight}</li>
        ))}
      </ul>
    </div>
  );
}

Common Use Cases

常见使用场景

Case 1: Display local data with filtering → Use JsonAdaptor + Query + where() for client-side filtering

Case 2: Fetch server data with authentication → Use WebApiAdaptor + applyPreRequestMiddlewares() for token injection

Case 3: Work offline, sync later → Use enableCache + offline mode + saveChanges() for batch sync

Case 4: Complex nested data relationships → Use ODataV4Adaptor or RemoteSaveAdaptor + expand() for related data

Case 5: GraphQL backend → Use GraphQLAdaptor with custom query builder

Case 6: Legacy ASP.NET ASMX service → Use WebMethodAdaptor with appropriate response mapping

场景1：展示带过滤的本地数据 → 使用JsonAdaptor + Query + where()实现客户端过滤

场景2：带身份认证的服务端数据拉取 → 使用WebApiAdaptor + applyPreRequestMiddlewares()注入令牌

场景3：离线工作，后续同步 → 使用enableCache + 离线模式 + saveChanges()批量同步

场景4：复杂嵌套数据关系 → 使用ODataV4Adaptor或RemoteSaveAdaptor + expand()加载关联数据

场景5：GraphQL后端 → 使用GraphQLAdaptor配合自定义查询构建器

场景6：传统ASP.NET ASMX服务 → 使用WebMethodAdaptor配合对应响应映射

Key Props & Options

核心属性与配置

Property	Type	Purpose
json	Array	Local JavaScript array of objects
url	string	Remote server endpoint URL
adaptor	Adaptor	JsonAdaptor, ODataAdaptor, WebApiAdaptor, etc.
enableCache	boolean	Cache pages to prevent redundant requests
offline	boolean	Enable offline mode with local storage
crossDomain	boolean	CORS requests to different domain

属性	类型	用途
json	Array	本地JavaScript对象数组
url	string	远程服务端端点URL
adaptor	Adaptor	JsonAdaptor、ODataAdaptor、WebApiAdaptor等
enableCache	boolean	缓存分页数据避免重复请求
offline	boolean	开启本地存储离线模式
crossDomain	boolean	跨域请求其他域名资源

Comparison: DataManager vs Direct Binding

对比：DataManager vs 直接绑定

Feature	DataManager	Direct Binding
Flexible adaptors	✓ Easy switching	✗ Fixed to one source
Complex queries	✓ Query class with chaining	✗ Limited filtering
CRUD operations	✓ Full support + batch	✗ Basic operations
Middleware	✓ Pre/post hooks	✗ None
Caching	✓ Built-in	✗ Manual implementation
Offline mode	✓ Built-in	✗ Manual implementation
Performance (small datasets)	≈ Same	✓ Slightly faster
Performance (large datasets)	✓ Lazy loading support	✗ All at once

Use DataManager when building data-driven applications with flexibility, caching, and middleware needs.

Use direct binding for simple, one-off displays without complex queries or offline support.

功能	DataManager	直接绑定
灵活适配器	✓ 易切换	✗ 固定单一数据源
复杂查询	✓ 支持链式调用Query类	✗ 过滤能力有限
CRUD操作	✓ 完整支持+批量操作	✗ 仅基础操作
中间件	✓ 请求前后钩子	✗ 无
缓存	✓ 内置	✗ 需要手动实现
离线模式	✓ 内置	✗ 需要手动实现
性能（小数据集）	≈ 相当	✓ 略快
性能（大数据集）	✓ 支持懒加载	✗ 一次性加载全部

选择DataManager 当你构建数据驱动应用，需要灵活性、缓存和中间件能力时。

选择直接绑定 当你仅需要简单的一次性展示，无需复杂查询或离线支持时。