syncfusion-vue-data-manager

Syncfusion Vue DataManager：综合指南

何时使用此技能

在以下情况下，请参考此技能：

• 设置 DataManager，用于 Vue 2、Vue 3 或 Quasar
• 绑定数据（本地数组或远程 API）
• 使用 Query 类查询和筛选数据
• 执行 CRUD 操作（插入、更新、删除）
• 选择适配器（提供 10 种类型）
• 通过中间件／标头添加身份验证
• 使用缓存优化性能
• 使用数据持久化离线工作
• 获取 Composition API 与 Options API 的模式指导

---

🛑 强制人工确认关卡：适配器决策（请先阅读）

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

当用户提供服务 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，并确保所有远程端点都强制执行身份验证。

⚠️ 关键安全要求

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

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

第三方 API 响应可能引入安全风险。 始终验证端点的合法性、对请求进行身份验证，并在将数据绑定到 UI 组件之前验证数据。

核心概念概览

概念	适用场景	参考文档
设置	安装和初始配置	setup-vue-2.md, setup-vue-3.md, setup-quasar.md
数据绑定	连接数据源	data-binding.md
查询	筛选、排序、分页	querying.md
CRUD	插入、更新、删除记录	crud-operations.md
适配器	选择数据源类型	adaptors-guide.md
缓存	性能优化	caching.md
中间件	身份验证、转换	middleware.md
请求头	自定义 HTTP 请求头	how-to-headers.md
参数	发送额外的查询参数	how-to-parameters.md
离线	无网络连接时工作	how-to-offline.md

---

📊 框架与 API 覆盖情况

功能	Vue 2	Vue 3	Quasar	Composition	Options
设置	✅	✅	✅	-	✅
Composition API	-	✅	✅	✅	-
本地数据	✅	✅	✅	✅	✅
远程数据	✅	✅	✅	✅	✅
10 种适配器	✅	✅	✅	✅	✅
CRUD	✅	✅	✅	✅	✅
查询	✅	✅	✅	✅	✅
缓存	✅	✅	✅	✅	✅
中间件	✅	✅	✅	✅	✅

---

🚀 快速入门

Vue 3 Composition API（推荐）

import { onMounted, ref } from 'vue';
import { DataManager, Query, ODataV4Adaptor } from '@syncfusion/ej2-data';

export default {
  setup() {
    const items = ref([]);

    onMounted(async () => {
      const dm = new DataManager({
        url: 'url',
        adaptor: new ODataV4Adaptor()
      });

      try {
        const result = await dm.executeQuery(new Query().take(10));
        items.value = result.result;
      } catch (error) {
        console.error('Error:', error);
      }
    });

    return { items };
  }
}

Vue 2 Options API

import { DataManager, Query, ODataV4Adaptor } from '@syncfusion/ej2-data';

export default {
  data() {
    return { items: [] };
  },
  mounted() {
    const dm = new DataManager({
      url: 'url',
      adaptor: new ODataV4Adaptor()
    });

    dm.executeQuery(new Query().take(10))
      .then((result) => {
        this.items = result.result;
      })
      .catch((error) => {
        console.error('Error:', error);
      });
  }
}

---

📖 文档导航

🛑 适配器决策关卡（人工审批——远程 URL 的首要必经步骤）

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

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

入门指南（选择你的框架）

刚开始使用 DataManager？从这里开始：

📄 setup-vue-2.md — 使用 Options API 的 Vue 2

• Vue CLI 安装
• Vue 2 生命周期模式
• 第一个 DataManager 示例

📄 setup-vue-3.md — 使用 Composition API 和 Options API 的 Vue 3

• Vite 项目设置
• reactive() 与 ref()
• onMounted 生命周期
• 性能提示

📄 setup-quasar.md — Quasar 框架

• Quasar CLI 初始化
• Boot 文件配置
• Q-Grid 集成
• 构建优化

---

核心功能

了解数据绑定：

📄 data-binding.md

• 本地数据绑定（json 属性）
• 远程数据绑定（url + 适配器）
• 按 HTTP 状态码处理错误
• Promise 模式

操作数据（CRUD）：

📄 crud-operations.md

• insert() — 添加新记录
• update() — 修改现有记录
• remove() — 删除记录
• 使用 saveChanges() 执行批量操作
• update/remove 方法中的 keyField

查询与筛选：

📄 querying.md

• from() — 指定资源
• select() — 选择字段
• where() — 筛选条件
• orderBy() — 排序
• take/skip — 分页
• search() — 全文搜索
• group() — 数据分组

---

数据适配器（10 种）

选择合适的适配器：

📄 adaptors-guide.md

• JsonAdaptor — 本地内存数组
• ODataAdaptor — OData v3 服务
• ODataV4Adaptor — OData v4 端点
• UrlAdaptor — 通用 REST API
• WebApiAdaptor — ASP.NET Web API（Items、Count 格式）
• WebMethodAdaptor — ASP.NET Web 方法
• RemoteSaveAdaptor — 客户端查询 + 服务端 CRUD
• GraphQLAdaptor — GraphQL 端点
• CustomDataAdaptor — 自定义请求/响应
• CustomAdaptor — 扩展内置适配器

包含决策树和对比矩阵。

---

高级功能

性能优化：

📄 caching.md

• enableCache 属性
• 缓存的工作原理
• 自动清除规则
• 何时启用/禁用

请求自定义：

📄 middleware.md

• applyPreRequestMiddlewares() — 修改请求
• applyPostRequestMiddlewares() — 转换响应
• 添加自定义标头
• 注入身份验证令牌

---

操作指南

常见任务的快速解决方案：

📄 how-to-headers.md

• 添加静态标头
• 为每个请求添加动态标头
• JWT/Bearer 身份验证
• 内容协商

📄 how-to-parameters.md

• 发送额外的查询参数
• 自定义 API 格式
• 不同的适配器参数样式

📄 how-to-offline.md

• 启用离线模式
• localStorage 持久化
• 同步策略
• 冲突解决

🔒 安全警告： localStorage 和 sessionStorage 会在浏览器中以未加密的形式存储数据。切勿在持久化的 TreeGrid 状态中存储敏感数据（密码、令牌、个人身份信息、支付信息、用户机密、身份验证凭据）。状态持久化仅适用于 UI 状态（展开/折叠状态、页码、排序顺序、列可见性、筛选选择）。对于敏感配置或用户数据，请改用安全的服务端会话存储。

---

🎯 常见模式

本地数据绑定

// Vue 3 Composition API
import { ref } from 'vue';
import { DataManager, Query, JsonAdaptor } from '@syncfusion/ej2-data';

const items = ref([]);

const data = [
  { OrderID: 10248, CustomerID: 'VINET', Freight: 32.38 },
  { OrderID: 10249, CustomerID: 'TOMSP', Freight: 11.61 }
];

const dm = new DataManager({ json: data, adaptor: new JsonAdaptor() });
items.value = dm.executeLocal(new Query().take(10));

带错误处理的远程数据

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

dataManager.executeQuery(new Query().take(10))
  .then((result) => {
    console.log('Success:', result.result);
  })
  .catch((error) => {
    const statusCode = error.status;
    if (statusCode === 401) {
      console.error('Unauthorized - please login');
    } else if (statusCode === 404) {
      console.error('Data not found');
    } else if (statusCode === 0) {
      console.error('Network error');
    }
  });

使用 Vue 3 Composition API 进行筛选

import { ref, computed } from 'vue';
import { Query } from '@syncfusion/ej2-data';

const dm = new DataManager({ json: allData });
const searchText = ref('');

const filteredData = computed(() => {
  if (!searchText.value) return allData;
  
  return dm.executeLocal(
    new Query().where('CustomerID', 'contains', searchText.value)
  );
});

身份验证中间件

🔒 安全警告： localStorage 和 sessionStorage 会在浏览器中以未加密的形式存储数据。切勿在持久化的 TreeGrid 状态中存储敏感数据（密码、令牌、个人身份信息、支付信息、用户机密、身份验证凭据）。状态持久化仅适用于 UI 状态（展开/折叠状态、页码、排序顺序、列可见性、筛选选择）。对于敏感配置或用户数据，请改用安全的服务端会话存储。

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

// Apply middleware to add auth token
dataManager.applyPreRequestMiddlewares([
  async (context) => {
    const token = localStorage.getItem('auth_token');
    context.request.headers['Authorization'] = `send_token`;
  }
]);

---

🔧 DataManager 配置

const dataManager = new DataManager({
  // Data source
  url: 'url',        // Remote endpoint
  json: localArray,                            // Local array
  
  // Adaptor selection
  adaptor: new WebApiAdaptor(),              // Adaptor type
  
  // Headers & auth
  headers: [...],
  
  // Network settings
  crossDomain: true,                          // Enable CORS
  offline: false,                             // Offline mode
  enableCache: true,                          // Caching
  
  // Persistence
  enablePersistence: true,                    // Enable state persistence
  id: 'dataManager_vue',                      // Persistence ID
  ignoreOnPersist: ['temp', 'debug'],        // Properties to exclude
  timeZoneHandling: true                      // Timezone offset handling
});

---

❌ 常见错误与解决方案

错误	原因	解决方案
401 未授权	缺少/过期的身份验证令牌	使用新令牌添加中间件
404 未找到	端点 URL 错误	验证 API 端点 URL
0（网络错误）	无互联网连接	启用离线模式
跨源错误	未启用 CORS	设置 crossDomain: true

---

✅ 最佳实践

1. 始终设置适配器 — 为后端选择正确的适配器
2. 在 CRUD 方法中传入 keyField — update/delete 中的必需首个参数
3. 使用 async/await — 比 .then()/.catch() 更易读
4. 添加错误处理 — 捕获 HTTP 错误
5. 启用缓存 — 减少服务端请求
6. 使用中间件 — 全局添加身份验证
7. 测试两种 API — Composition 和 Options 模式
8. 处理网络错误 — 状态码 0 表示无互联网连接
9. 使用类型化接口 — 支持 TypeScript

---