syncfusion-react-query-builder

实现 Syncfusion React Query Builder

本指南全面介绍如何实现和自定义 Syncfusion React Query Builder 组件。Query Builder 是一款功能强大的 UI 组件，可用于创建和管理复杂的筛选条件，支持基于规则的查询、多种数据类型、SQL 生成以及丰富的自定义选项。

组件概览

Query Builder 组件提供了一个图形界面，用于创建和编辑复杂的筛选规则。它会输出结构化 JSON，可将其转换为 SQL、Mongo 查询或自定义谓词，以筛选数据。主要功能包括：

• 规则管理： 创建、编辑、删除规则和组，以及将规则和组嵌套
• 多种数据类型： 支持字符串、数字、日期、布尔值和自定义类型
• 运算符支持： 内置 16 种以上运算符（等于、包含、介于、属于等）
• 查询转换： 转换为 SQL、Mongo 查询或参数化查询
• 自定义： 自定义模板、主题和样式
• 无障碍功能： 符合 WCAG 标准，支持键盘导航和屏幕阅读器
• 高级功能： 拖放、状态持久化、克隆、锁定

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本组件初始化
• CSS 导入和主题
• 创建第一个 Query Builder
• 列定义基础
• 运行应用程序

列和运算符

📄 阅读： references/columns-and-operators.md

• 使用 ColumnsModel 定义列架构
• 根据数据源自动生成列
• 配置标签和字段映射
• 各数据类型支持的运算符
• 设置 step 和 format 属性
• 列验证配置

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地数据数组
• 使用 DataManager 连接远程数据
• 集成 ODataV4Adaptor
• 动态更新数据
• 在 Query Builder 中使用 DataManager
• 处理数据源变更

规则和筛选

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

• 了解规则结构（RuleModel）
• 使用 addRules 以编程方式创建规则
• 使用 addGroups 创建组
• 删除规则和组
• 管理嵌套规则层级
• 拖放管理规则
• 配置显示按钮

查询转换

📄 阅读： references/query-conversion.md

• 使用 getSqlFromRules 将规则转换为 SQL
• 使用 getMongoQuery 生成 Mongo 查询
• 创建参数化 SQL 查询
• 生成命名参数 SQL
• 转换用于 DataManager 的谓词
• 从 SQL 查询导入规则
• 处理 SQL 转换中的本地化

模板和自定义

📄 阅读： references/templates-and-customization.md

• 创建自定义标题模板
• 向模板注入自定义组件
• 使用 CSS 类和 cssClass 属性设置样式
• 集成 Theme Studio
• 自定义运算符定义
• 使用 actionBegin 事件进行自定义

高级功能

📄 阅读： references/advanced-features.md

• 显示模式（水平和垂直布局）
• 使用 cloneRule/cloneGroup 克隆规则和组
• 锁定规则和组以实现只读访问
• 使用独立连接符进行视觉区分
• 限制组操作
• RTL（从右到左）支持
• 使用 enablePersistence 持久化状态
• 排序方向配置
• 显示摘要视图
• 无障碍功能和键盘导航

API 参考

📄 阅读： references/api-reference.md

• 完整的属性列表，包含类型和默认值
• 所有方法及其参数和返回类型
• 事件处理程序和事件参数
• 模型接口（RuleModel、ColumnsModel、ShowButtonsModel）
• 返回类型定义和数据结构
• 属性使用模式

快速入门示例

import { ColumnsModel, QueryBuilderComponent, RuleModel } from '@syncfusion/ej2-react-querybuilder';
import React from 'react';

function App() {
  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: 'Country', label: 'Country', type: 'string' }
  ];

  const initialRules: RuleModel = {
    condition: 'and',
    rules: [
      {
        field: 'EmployeeID',
        label: 'Employee ID',
        operator: 'equal',
        type: 'number',
        value: 1001
      }
    ]
  };

  return (
    <QueryBuilderComponent 
      width="100%" 
      columns={columnData} 
      rule={initialRules}
    />
  );
}

export default App;

常见模式

模式 1：将筛选结果检索为 SQL

let qryBldrObj: QueryBuilderComponent;

function generateSQL() {
  const sqlQuery = qryBldrObj.getSqlFromRules();
  console.log('Generated SQL:', sqlQuery);
  // Send to backend for execution
}

模式 2：以编程方式添加规则

function addFilter() {
  qryBldrObj.addRules([
    {
      field: 'Country',
      label: 'Country',
      operator: 'equal',
      type: 'string',
      value: 'USA'
    }
  ], 'group0');
}

模式 3：将 SQL 转换回规则

function importFilter(sqlString: string) {
  qryBldrObj.setRulesFromSql(sqlString);
}

模式 4：显示摘要视图

<QueryBuilderComponent 
  columns={columnData}
  summaryView={true}  // Shows query summary at the bottom
/>

关键属性速查表

属性	类型	默认值	用途
columns	ColumnsModel[]	-	定义可用字段和运算符
rule	RuleModel	{}	初始筛选规则
dataSource	Object[] | DataManager	[]	用于绑定的数据
displayMode	'Horizontal' | 'Vertical'	'Horizontal'	布局方向
allowDragAndDrop	boolean	false	启用规则的拖放管理
enablePersistence	boolean	false	将状态保存到 localStorage
enableRtl	boolean	false	从右向左布局
allowValidation	boolean	false	验证规则条件
summaryView	boolean	false	显示筛选查询摘要
showButtons	ShowButtonsModel	defaults	控制添加/删除按钮的可见性
maxGroupCount	number	5	最大嵌套组深度
readonly	boolean	false	将组件设为只读

常见使用场景

使用场景 1：高级搜索筛选器

创建筛选界面，让用户使用多个条件构建复杂的搜索查询：

1. 为可搜索字段定义列
2. 使用空规则或默认规则初始化
3. 设置 showButtons 以启用规则管理
4. 在表单提交时获取 SQL
5. 在后端执行查询

阅读： references/rules-and-filtering.md 和 references/query-conversion.md

使用场景 2：数据驱动型仪表板

构建一个仪表板，让用户能够跨多个列筛选数据：

1. 将 DataManager 绑定到远程服务
2. 根据数据类型配置列
3. 启用拖放功能以改善用户体验
4. 使用 getPredicate() 筛选 DataManager
5. 动态显示筛选结果

阅读： references/data-binding.md 和 references/rules-and-filtering.md

使用场景 3：查询模板系统

允许用户保存和加载筛选模板：

1. 设置 enablePersistence={true} 以自动保存状态
2. 或者手动将 getRules() 保存到数据库
3. 需要时使用 setRules() 加载规则
4. 在下拉列表中显示已保存的模板

阅读： references/advanced-features.md

使用场景 4：报表生成器

使用自定义模板创建报表筛选 UI：

1. 设计自定义标题模板以展示品牌形象
2. 使用自定义运算符进行特定领域的筛选
3. 使用 allowValidation 启用验证
4. 显示 summaryView，让内容更加清晰
5. 生成 SQL 以执行报表

阅读： references/templates-and-customization.md 和 references/advanced-features.md

后续步骤

1. 开始使用： 安装软件包并创建第一个 Query Builder
2. 定义列： 配置用户可以筛选的字段
3. 绑定数据： 连接本地或远程数据源
4. 构建 UI： 添加规则和组，并支持拖放操作
5. 生成查询： 将规则转换为 SQL 或其他格式
6. 自定义： 应用主题、模板和无障碍功能

---

需要帮助？ 请查看上面的特定参考文件，了解详细示例和实现模式。