syncfusion-angular-data-manager

用途

Syncfusion Angular DataManager 是 Syncfusion 的通用数据管理模块，充当 Angular 应用与任意数据源之间的桥梁。当你需要在 Syncfusion Angular 组件中进行任何数据操作、实现跨组件的通用数据绑定、配置与选择数据源、处理异步操作与错误、或通过缓存优化性能时，可将本技能作为主要参考。

具体适用场景包括：将本地 JSON 数组绑定到 Angular 组件；将 Angular 应用连接到远程 REST、OData 或 GraphQL 服务；实现数据的查询、过滤、排序和分页；执行带数据持久化的 CRUD 操作；离线工作并在重新连接后同步数据；使用 Query 类转换和过滤数据；通过中间件自定义数据通信；缓存数据以减少服务器请求；自动处理不同的数据源协议。

主要能力

10 种内置适配器：支持 JSON、OData v3/v4、REST、Web API、Web Methods、GraphQL 及自定义数据源。
Query 类：提供过滤、排序、分组、分页、搜索与聚合 API。
CRUD 操作：插入、更新、删除并自动处理，支持 keyField 与 saveChanges() 批量操作。
基于 Promise 的异步：原生 JavaScript Promise 支持，支持 async/await 与 Promise.all() 并行操作。
中间件自定义：请求前/后钩子，用于认证（如 Bearer token）与数据转换。
离线支持：无服务器连接时工作，恢复在线后同步，使用 localStorage 持久化。
缓存：降低服务器负载、提升性能，支持缓存自动清除与手动管理。
类型安全：完整 TypeScript 定义，支持泛型结果类型。

使用方式

安装包：

npm install @syncfusion/ej2-data

创建组件并导入：

import { Component, OnInit } from '@angular/core';
import { DataManager, Query, JsonAdaptor, ReturnOption } from '@syncfusion/ej2-data';

@Component({
  selector: 'app-data-demo',
  templateUrl: './data-demo.component.html',
  styleUrls: ['./data-demo.component.css']
})
export class DataDemoComponent implements OnInit {
  public orders: object[];

  ngOnInit(): void {
    // Local data
    const data = [
      { OrderID: 10248, CustomerID: 'VINET', EmployeeID: 5, ShipCity: 'Reims' },
      { OrderID: 10249, CustomerID: 'TOMSP', EmployeeID: 6, ShipCity: 'Münster' },
      { OrderID: 10250, CustomerID: 'HANAR', EmployeeID: 4, ShipCity: 'Rio de Janeiro' }
    ];

    // Create DataManager with local data
    const dataManager = new DataManager({
      json: data,
      adaptor: new JsonAdaptor()
    });

    // Execute query
    this.orders = dataManager.executeLocal(
      new Query().where('EmployeeID', 'equal', 5)
    );
  }
}

模板中展示：

<table>
  <thead>
    <tr>
      <th>Order ID</th>
      <th>Customer ID</th>
      <th>Employee ID</th>
      <th>Ship City</th>
    </tr>
  </thead>
  <tbody>
    <tr *ngFor="let order of orders">
      <td>{{ order.OrderID }}</td>
      <td>{{ order.CustomerID }}</td>
      <td>{{ order.EmployeeID }}</td>
      <td>{{ order.ShipCity }}</td>
    </tr>
  </tbody>
</table>

远程服务器与 Promise：

const dataManager = new DataManager({
  url: 'url',
  adaptor: new WebApiAdaptor()
});

// Using Promise
dataManager.executeQuery(new Query().take(10))
  .then((result: ReturnOption) => {
    this.orders = result.result;
  })
  .catch((error) => {
    console.error('Failed to fetch orders:', error);
  });

Async/Await 模式：

async fetchOrders(): Promise<void> {
  try {
    const result = await this.dataManager.executeQuery(
      new Query().take(10)
    );
    this.orders = result.result;
  } catch (error) {
    console.error('Error:', error);
  }
}

过滤与谓词：

const query = new Query()
  .where('EmployeeID', 'equal', 5)
  .where('ShipCity', 'startswith', 'Rio');

const result = dataManager.executeLocal(query);

服务端操作：

const query = new Query()
  .select(['OrderID', 'CustomerID', 'EmployeeID'])
  .where('EmployeeID', 'greaterThan', 3)
  .sortBy('OrderID')
  .take(10)
  .skip(0);

dataManager.executeQuery(query).then((result: ReturnOption) => {
  this.orders = result.result;
  this.totalRecords = result.count;
});

类型安全示例：

interface Order {
  OrderID: number;
  CustomerID: string;
  EmployeeID: number;
  ShipCity: string;
}

const dataManager: DataManager<Order> = new DataManager({
  json: orders,
  adaptor: new JsonAdaptor()
});

const result = await dataManager.executeQuery(new Query());
const typedOrders: Order[] = result.result as Order[];

关键属性包括：json（本地数据数组）、url（远程服务端点）、adaptor（数据源类型处理器）、headers（自定义 HTTP 头）、offline（启用离线模式）、enableCache（启用响应缓存）、crossDomain（启用跨域请求）、cachingPageSize（分页记录数）、timeTillExpiration（缓存 TTL 毫秒，默认无限）、ignoreOnPersist（持久化时排除的属性）、timeZoneHandling（启用时区偏移处理）。

适配器决策门（强制人工确认）

当用户提供服务 URL 但未明确指定适配器类型时，代理必须：立即停止代码生成；阅读 references/adaptor-decision-gate.md 全文；使用其中的模板向用户呈现决策门；等待用户明确确认适配器选择；之后才以确认的适配器生成 DataManager 代码。需要触发决策门的情形包括：仅提供服务 URL（如 http://myapi.com/employees）、提到「API」（含义模糊）、提到「REST 服务」（UrlAdaptor、WebApiAdaptor、ODataV4 难以区分）。已明确指定 OData v4、或后端返回 { Items, Count } 的 WebApiAdaptor 模式、或本地绑定数据时，无需触发决策门。

安全与信任边界

本技能仅生成代码，代理不执行数据操作或获取远程端点；所有 DataManager 交互仅在用户应用运行时进行。生成的代码必须将所有第三方 API 响应视为不受信输入，绝不绑定到未经验证或用户提供的 URL，并确保所有远程端点强制执行认证。绑定远程服务时的关键安全要求：仅使用 HTTPS，绝不使用未加密的 HTTP；使用字符串变量保存 URL（而非在标记中硬编码）；验证并净化响应（服务端 schema 验证、拒绝意外格式、映射到强类型模型）；监控远程调用（记录时间戳、端点、结果以形成审计线索）；安全实现 CORS（仅使用特定受信源，生产环境禁用通配符 *，要求 HTTPS）；防止间接提示注入攻击（验证端点归属、实现请求签名、消费数据前验证内容类型与 schema）。

适用场景与限制

适用场景举例：展示数据表格可从 getting-started 与数据绑定、查询过滤入手；实现 CRUD 表单可从适配器指南与 CRUD 操作入手；处理多数据源可从适配器决策树与中间件入手；优化大数据集可从高级特性、缓存与离线模式入手。性能优化建议包括：选择匹配后端的适配器、尽早过滤（尽量下推到服务端）、启用缓存、惰性加载、分页、离线模式、只选择需要的列。

限制与注意事项：本技能以代码生成与配置指导为主，不执行数据操作；远程绑定存在上述安全要求，第三方 API 响应需在使用前验证；关于定价、收费、具体平台支持细节本文资料暂未提供。