syncfusion-javascript-query-builder

在 TypeScript 中实现 QueryBuilder

QueryBuilder 是 Syncfusion 的强大组件，可通过可视化 UI 构建动态、复杂的查询。本技能为在 TypeScript 应用程序中实现、配置和自定义 QueryBuilder 提供全面指导。

控件概述

QueryBuilder 是一个高级 UI 组件，用户无需编写代码即可构建复杂的筛选条件。它支持：

• 多种数据类型（字符串、数字、日期、布尔值）
• 多种运算符（等于、包含、介于等）
• 使用 AND/OR 条件对规则进行分组
• 嵌套组层级结构
• 用于自定义 UI 的模板
• 拖放交互（重新排列、克隆、锁定规则）
• JSON 导入/导出和 SQL 生成
• RTL 支持和完整的键盘无障碍功能
• 符合 WCAG 2.1 AA 标准

文档和导航指南

入门

另请参阅：references/getting-started.md

• 安装和 npm 包设置
• 配置 Syncfusion 依赖项
• CSS 导入和主题设置
• QueryBuilder 基本初始化
• 带类型的列定义
• 运行第一个 QueryBuilder 应用程序

列和架构定义

另请参阅：references/columns-definition.md

• 列定义和架构结构
• 根据数据自动生成列
• 字段映射和标签
• 支持的数据类型（字符串、数字、日期、布尔值）
• 各数据类型对应的运算符
• 数字/日期的步进值和格式属性
• 自定义列配置模式

数据绑定

另请参阅：references/data-binding.md

• 使用 JavaScript 数组进行本地数据绑定
• 使用 DataManager 进行远程数据绑定
• DataSource 赋值模式
• 用于预定义查询的 RuleModel 结构
• 使用初始规则进行绑定
• 动态数据更新和刷新
• DataManager 配置

规则和组管理

另请参阅：references/rules-and-groups.md

• 规则模型结构（condition、rules、field、operator、value）
• 创建单个筛选规则
• 使用 AND/OR 逻辑对规则分组
• 以编程方式添加和删除规则
• 添加和删除组
• 规则验证和约束
• 嵌套组层级结构

筛选和搜索操作

另请参阅：references/filtering-search.md

• 创建和删除筛选条件
• 查询执行方法
• 自定义筛选条件模式
• 在条件中使用搜索功能
• ShowButtons 配置（删除规则、插入/删除组）
• 基于 UI 和以编程方式进行筛选
• 处理筛选更改事件

模板和自定义

另请参阅：references/templates-customization.md

• 值模板自定义
• 运算符模板自定义
• 字段模板自定义
• 创建自定义 HTML 模板
• 模板渲染和绑定
• CSS 类自定义
• 动态模板渲染模式

拖放和规则交互

另请参阅：references/drag-drop-clone-lock.md

• 规则的拖放功能
• 在组内克隆规则
• 锁定规则以防止修改
• 分隔符和连接符行为
• 在组之间移动规则
• 处理拖放事件
• 视觉反馈和样式

导入/导出和持久化

另请参阅：references/import-export.md

• 将规则导出为 JSON 格式
• 从 JSON 导入规则
• SQL 查询生成
• JSON 序列化模式
• 格式转换（规则转为 SQL/JSON）
• 数据持久化策略
• 状态管理

无障碍功能和 RTL

另请参阅：references/accessibility-rtl.md

• 符合 WCAG 2.1 AA 标准
• 键盘导航模式
• ARIA 属性和标签
• 屏幕阅读器支持
• RTL（从右到左）语言支持
• 焦点管理和指示器
• 本地化和国际化

高级功能和故障排查

另请参阅：references/advanced-features.md

• 全局和本地配置选项
• 模型绑定模式
• 高级验证策略
• 性能优化技巧
• 事件处理和回调
• 状态持久化模式
• 常见问题和故障排查
• 复杂场景的最佳实践

API 参考

另请参阅：references/api.md

• 完整的属性参考，包含类型和默认值
• 所有公共方法，包含参数和返回类型
• 所有事件，包含事件参数接口
• 关键模型接口（RuleModel、ColumnsModel、ShowButtonsModel、ValueModel、TemplateColumn、Validation）
• 事件参数接口（ActionEventArgs、ChangeEventArgs、RuleChangeEventArgs、DragEventArgs、DropEventArgs）
• SQL/查询输出接口（ParameterizedSql、ParameterizedNamedSql）
• 初始化、SQL 导出、规则管理、克隆/锁定和拖放的用法示例

快速入门示例

下面是一个 QueryBuilder 入门用的最简示例：

import { QueryBuilder, ColumnsModel, RuleModel } from '@syncfusion/ej2-querybuilder';

// Define your data
const employeeData = [
  {
    EmployeeID: 1,
    FirstName: 'Nancy',
    Title: 'Sales Representative',
    HireDate: '22/07/2001',
    City: 'Seattle',
    Country: 'USA'
  },
  {
    EmployeeID: 2,
    FirstName: 'Andrew',
    Title: 'Vice President',
    HireDate: '21/04/2003',
    City: 'Tacoma',
    Country: 'USA'
  }
];

// Define columns matching your data
const columnData: ColumnsModel[] = [
  { field: 'EmployeeID', label: 'Employee ID', type: 'number' },
  { field: 'FirstName', label: 'First Name', type: 'string' },
  { field: 'Title', label: 'Title', type: 'string' },
  { field: 'HireDate', label: 'Hire Date', type: 'date', format: 'dd/MM/yyyy' },
  { field: 'City', label: 'City', type: 'string' },
  { field: 'Country', label: 'Country', type: 'string' }
];

// Optional: Define initial rules
const initialRules: RuleModel = {
  condition: 'and',
  rules: [
    {
      label: 'Employee ID',
      field: 'EmployeeID',
      type: 'number',
      operator: 'equal',
      value: 1
    },
    {
      label: 'Title',
      field: 'Title',
      type: 'string',
      operator: 'startswith',
      value: 'Sales'
    }
  ]
};

// Create QueryBuilder instance
const queryBuilder = new QueryBuilder({
  width: '100%',
  dataSource: employeeData,
  columns: columnData,
  rule: initialRules
});

// Render to DOM
queryBuilder.appendTo('#querybuilder');

常见模式

模式 1：使用单条规则的基本筛选

对于简单的筛选场景，请使用不含分组的单条规则：

const rule: RuleModel = {
  condition: 'and',
  rules: [{
    field: 'FirstName',
    type: 'string',
    operator: 'startswith',
    value: 'A'
  }]
};

模式 2：使用分组实现 AND/OR 逻辑

适用于组合多个条件的复杂筛选：

const rule: RuleModel = {
  condition: 'and',
  rules: [
    { field: 'City', operator: 'equal', value: 'Seattle' },
    {
      condition: 'or',
      rules: [
        { field: 'Title', operator: 'contains', value: 'Sales' },
        { field: 'Title', operator: 'contains', value: 'Manager' }
      ]
    }
  ]
};

模式 3：动态添加规则

根据用户操作以编程方式添加规则：

const newRule = [{
  field: 'Country',
  operator: 'equal',
  value: 'USA'
}];
queryBuilder.addRules(newRule, 'group0');

模式 4：导出为 JSON 以便存储

保存当前查询状态以便持久化：

const rules = queryBuilder.getRules();
const jsonQuery = JSON.stringify(rules);
// Store in database or local storage

核心概念

• RuleModel： 表示单个筛选条件，包含字段、运算符和值
• Condition： 用于组合多条规则的逻辑运算符（AND/OR）
• GroupModel： 用于存放带有 AND/OR 条件的规则的容器
• Operators： 比较方法（等于、包含、介于等）
• Data Types： 支持的列类型（字符串、数字、日期、布尔值）
• Templates： 用于字段、运算符和值的自定义 UI 元素
• State： 规则和分组的当前配置

常见用例

1. 高级搜索筛选器 - 让用户为数据搜索构建复杂查询
2. 报告生成 - 为报告参数创建动态筛选器
3. 数据导出 - 使用可视化 UI 在导出前筛选数据
4. 日志分析 - 构建复杂查询以分析系统日志
5. 客户细分 - 根据多项条件筛选客户
6. 权限规则 - 使用复杂条件定义访问规则
7. 通知规则 - 创建动态警报条件
8. ETL 工作流 - 在转换前筛选源数据

---

需要了解某项功能的帮助？ 请查看上方的参考文件，获取有关列、数据绑定、模板等内容的详细指南！