syncfusion-react-data-manager

Syncfusion React DataManager

DataManager 是一个网关组件，用于管理 React 应用中的本地和远程数据操作。它充当抽象层，让你无需编写复杂的服务器通信代码，即可轻松实现数据绑定、查询、CRUD 操作、缓存和中间件自定义。

在以下情况下使用此技能：

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

---

🛑 必须经过人工确认：适配器选择（请先阅读）

这是此技能中最重要的规则，不得跳过或绕过。

当用户提供服务 URL，但未明确指定适配器类型时，Agent 必须：

1. 立即停止生成代码
2. 阅读： references/adaptor-decision-gate.md（完整文件）
3. 使用该文件中的模板向用户展示确认步骤
4. 等待用户明确确认适配器选择
5. 只有在此之后，才能使用已确认的适配器生成 DataManager 代码

确认步骤触发条件 — 示例

用户提示	是否需要确认？
"Build an employee app using this service URL (http://myapi.com/employees)"	✅ 是 — 未指定适配器
"Connect GridComponent to http://myserver/api/data"	✅ 是 — “API”含义不明确
"Use OData v4 endpoint at https://myserver/odata/employees"	❌ 否 — 已明确说明 OData v4
"My backend returns { Items, Count } at https://myserver/api/orders"	❌ 否 — 已确认 WebApiAdaptor 模式
"I have a REST service at http://custom-url"	✅ 是 — REST 含义不明确（UrlAdaptor、WebApiAdaptor 或 ODataV4）
"Bind the grid to local list data"	❌ 否 — 本地绑定，无需适配器

📄 完整的确认步骤模板、适配器速查表、消除歧义的问题和安全规则： → references/adaptor-decision-gate.md

---

⚠️ 安全与信任边界

• 此技能仅生成代码，Agent 不会执行数据操作或获取远程端点 — 所有 DataManager 交互都只会在用户应用运行时发生。
• 生成的代码必须将所有第三方 API 响应视为不可信输入，绝不能绑定到未经验证或由用户提供的 URL，并确保对所有远程端点强制执行身份验证。

何时使用 DataManager

DataManager 适用于：

• 灵活的数据管理 → 适用于任何数据源（本地、REST、OData、GraphQL）
• 复杂查询 → 筛选、排序、分页、分组、搜索
• CRUD 操作 → 支持批处理和事务模式
• 中间件自定义 → 请求前/后的钩子
• 离线支持 → 连接恢复后缓存并同步
• 切换适配器 → 无需更改代码即可更换数据源

以下情况下，直接绑定到组件（Grid、Scheduler 等）更合适：

• 只需基本数据绑定，无需复杂查询
• 超大型数据集对性能要求很高
• 不需要自定义中间件

⚠️ 关键安全要求

绑定到远程服务时，必须实施以下保护措施：

1. 仅使用 HTTPS — 切勿使用未加密的 HTTP 连接；对所有传输中的数据进行加密
2. 将 URL 用作字符串变量 — 将端点赋值给私有字符串属性，而非硬编码在标记中；这样便于集中验证和维护
3. 验证并清理响应 — 实施服务器端架构验证；拒绝格式异常的响应；将响应映射到强类型模型
4. 监控远程调用 — 记录所有外部 API 请求的时间戳、端点和结果，以便进行安全审计
5. 安全地实施 CORS — 仅使用特定的可信来源；在生产环境中切勿使用通配符 *；要求使用 HTTPS
6. 防止间接提示词注入攻击 — 验证端点所有权；实施请求签名；在使用数据前验证响应内容类型和架构

第三方 API 响应可能带来安全风险。 在绑定到 UI 组件前，务必确认端点的合法性、验证请求身份并验证数据。

核心概念

数据绑定

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

Query 类

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

适配器

适配器是一种接口，使 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 操作

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

中间件与自定义

• applyPreRequestMiddlewares() → 发送前修改请求（身份验证令牌、标头）
• applyPostRequestMiddlewares() → 绑定前转换响应（格式化、筛选）
• 用于专有 API 的自定义适配器
• 用于处理请求失败的错误处理程序

缓存与性能

• enableCache → 避免重复请求已加载的页面
• 离线模式 → 在本地存储数据，并在连接恢复后同步
• 按需加载 → 随着用户滚动延迟加载数据（虚拟滚动）
• 延迟操作 → 基于 Promise 的 async/await 模式

文档与导航指南

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

🛑 适配器选择关卡（人工审批 — 远程 URL 的强制首要步骤）

📄 阅读： references/adaptor-decision-gate.md

• 触发条件： 用户提供了服务 URL，但未明确指定适配器
• 关卡展示模板（可直接复制粘贴）
• 完整的适配器对比表（ODataV4 / OData / WebAPI / URL / GraphQL / Custom）
• 适配器速查表及代码示例
• 用于消除歧义的后续问题
• 关卡确认后适用的安全规则
• 阶段 1 和阶段 3 的集成说明（在组件映射 JSON 中标记含义不明确的 URL）
• 可自动通过关卡的关键词（无需用户确认）

快速入门设置

📄 阅读： references/getting-started.md

• 安装步骤（npm）
• 项目设置与导入
• 初始化 DataManager 基础配置
• 执行第一个查询
• 环境设置
• 常见错误与修复方法

数据绑定策略

📄 阅读： references/data-binding.md

• 使用 json 属性进行本地数据绑定
• 使用 url 属性进行远程数据绑定
• 使用 executeLocal() 执行客户端查询
• 使用 executeQuery() 发送服务端请求
• 在不同数据源之间切换
• 处理响应格式
• 各种方式的适用场景

查询操作与筛选

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

• Query 类基础知识
• 使用 where() 和 Predicate 进行筛选
• 排序（升序／降序）
• 使用 take() 和 skip() 分页
• 使用 select() 投影字段
• 使用 expand() 加载关联数据
• 按字段分组数据
• 复杂的多条件查询
• 链式调用查询操作

CRUD 操作与批量编辑

📄 阅读： references/crud-operations.md

• insert() → 添加新记录
• update() → 修改现有记录
• remove() → 删除记录
• CRUD 方法参数中的 keyField
• 使用 saveChanges() 执行批量操作
• 批量插入／更新／删除
• 事务模式
• 操作前的数据验证
• 处理响应

选择和使用适配器

📄 阅读： references/adaptors-guide.md

• 选择哪种适配器（决策树）
• 用于本地数组的 JsonAdaptor
• OData 适配器（v3 和 v4）
• REST API 适配器（Url、WebApi）
• RemoteSaveAdaptor 混合方案
• 旧版 ASMX（WebMethodAdaptor）
• 集成 GraphQL 端点
• 自定义适配器实现
• CORS 与 crossDomain 配置
• 平台特定的响应处理

中间件与请求自定义

📄 阅读： references/middleware-customization.md

• 用于身份验证令牌的请求前中间件
• 注入自定义标头
• 请求转换
• 用于响应映射的请求后中间件
• 错误处理函数
• 在中间件中进行数据验证与筛选
• 自定义适配器实现
• 中间件执行顺序与时机

缓存与离线模式

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

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

高级功能与模式

📄 阅读： references/advanced-features.md

• 按需加载与分页模式
• 虚拟滚动设置
• 延迟加载数据
• 延迟操作（Promise API）
• 将 async/await 与 DataManager 搭配使用
• 跨会话状态持久化
• 内存管理
• 错误处理策略
• 性能优化技巧
• 常见问题与解决方案

快速入门示例

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

常见使用场景

场景 1：显示并筛选本地数据 → 使用 JsonAdaptor + Query + where() 在客户端进行筛选

场景 2：通过身份验证获取服务端数据 → 使用 WebApiAdaptor + applyPreRequestMiddlewares() 注入令牌

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

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

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

场景 6：旧版 ASP.NET ASMX 服务 → 使用 WebMethodAdaptor 并进行适当的响应映射

关键属性和选项

属性	类型	用途
json	Array	本地 JavaScript 对象数组
url	string	远程服务端点 URL
adaptor	Adaptor	JsonAdaptor、ODataAdaptor、WebApiAdaptor 等
enableCache	boolean	缓存页面，避免冗余请求
offline	boolean	使用本地存储启用离线模式
crossDomain	boolean	向不同域发起 CORS 请求

对比：DataManager 与直接绑定

功能	DataManager	直接绑定
灵活的适配器	✓ 可轻松切换	✗ 固定为单一数据源
复杂查询	✓ 可通过 Query 类链式调用	✗ 筛选功能有限
CRUD 操作	✓ 全面支持 + 批处理	✗ 基本操作
中间件	✓ 前置/后置钩子	✗ 无
缓存	✓ 内置	✗ 手动实现
离线模式	✓ 内置	✗ 手动实现
性能（小型数据集）	≈ 相同	✓ 稍快
性能（大型数据集）	✓ 支持延迟加载	✗ 一次性加载全部数据

在构建需要灵活性、缓存和中间件的 DataManager 数据驱动型应用时，使用 DataManager。

对于没有复杂查询或离线支持需求的简单、一次性展示，请使用直接绑定。