syncfusion-react-query-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Query Builder

Syncfusion React Query Builder组件实现指南

A comprehensive guide for implementing and customizing the Syncfusion React Query Builder component. The Query Builder is a powerful UI component for creating and managing complex filter conditions, with support for rule-based queries, multiple data types, SQL generation, and extensive customization options.

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

Component Overview

组件概览

The Query Builder component provides a graphical interface for creating and editing complex filter rules. It outputs structured JSON that can be converted to SQL, Mongo queries, or custom predicates for filtering data. Key capabilities include:

Rule Management: Create, edit, delete, and nest rules and groups
Multiple Data Types: Support for string, number, date, boolean, and custom types
Operator Support: 16+ built-in operators (equal, contains, between, in, etc.)
Query Conversion: Convert to SQL, Mongo, or parameterized queries
Customization: Custom templates, themes, and styling
Accessibility: WCAG compliant with keyboard navigation and screen reader support
Advanced Features: Drag-and-drop, state persistence, cloning, locking

Query Builder组件提供了图形化界面，用于创建和编辑复杂筛选规则。它输出结构化JSON，可转换为SQL、Mongo查询或自定义断言来筛选数据。核心功能包括：

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
Basic component initialization
CSS imports and themes
Creating your first Query Builder
Column definition basics
Running the application

📄 阅读：references/getting-started.md

安装与包配置
组件基础初始化
CSS导入与主题设置
创建首个Query Builder
列定义基础
运行应用

Columns and Operators

列与运算符

📄 Read: references/columns-and-operators.md

Defining column schema with ColumnsModel
Auto-generating columns from data sources
Configuring labels and field mappings
Supported operators by data type
Setting step and format properties
Column validation configuration

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

基于ColumnsModel定义列 schema
从数据源自动生成列
配置标签与字段映射
按数据类型划分的支持运算符
设置步长与格式属性
列验证配置

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding local data arrays
Remote data with DataManager
ODataV4Adaptor integration
Dynamic data updates
Using DataManager with Query Builder
Handling data source changes

📄 阅读：references/data-binding.md

绑定本地数据数组
通过DataManager绑定远程数据
ODataV4Adaptor集成
动态数据更新
DataManager与Query Builder结合使用
处理数据源变更

Rules and Filtering

规则与筛选

📄 Read: references/rules-and-filtering.md

Understanding rule structure (RuleModel)
Creating rules programmatically with addRules
Creating groups with addGroups
Deleting rules and groups
Managing nested rule hierarchies
Drag-and-drop rule management
Show buttons configuration

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

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

Query Conversion

查询转换

📄 Read: references/query-conversion.md

Converting rules to SQL with getSqlFromRules
Generating Mongo queries with getMongoQuery
Creating parameterized SQL queries
Named parameter SQL generation
Converting predicates for DataManager
Importing rules from SQL queries
Handling localization in SQL conversion

📄 阅读：references/query-conversion.md

使用getSqlFromRules将规则转换为SQL
使用getMongoQuery生成Mongo查询
创建参数化SQL查询
命名参数SQL生成
转换断言以适配DataManager
从SQL查询导入规则
处理SQL转换中的本地化

Templates and Customization

模板与自定义

📄 Read: references/templates-and-customization.md

Creating custom header templates
Custom component injection into templates
Styling with CSS classes and cssClass property
Theme Studio integration
Custom operator definitions
Handling actionBegin events for customization

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

创建自定义头部模板
向模板中注入自定义组件
使用CSS类与cssClass属性设置样式
主题工作室集成
自定义运算符定义
处理actionBegin事件以实现自定义逻辑

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Display modes (Horizontal and Vertical layouts)
Cloning rules and groups with cloneRule/cloneGroup
Locking rules and groups for read-only access
Separate connectors for visual distinction
Restricting group operations
RTL (Right-to-Left) support
State persistence with enablePersistence
Sort direction configuration
Summary view display
Accessibility and keyboard navigation

📄 阅读：references/advanced-features.md

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

API Reference

API参考

📄 Read: references/api-reference.md

Complete properties list with types and defaults
All methods with parameters and return types
Event handlers and event arguments
Model interfaces (RuleModel, ColumnsModel, ShowButtonsModel)
Return type definitions and data structures
Property usage patterns

📄 阅读：references/api-reference.md

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

Quick Start Example

快速入门示例

tsx

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;

tsx

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;

Common Patterns

常见模式

Pattern 1: Retrieving Filtered Results as SQL

模式1：以SQL形式获取筛选结果

tsx

let qryBldrObj: QueryBuilderComponent;

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

tsx

let qryBldrObj: QueryBuilderComponent;

function generateSQL() {
  const sqlQuery = qryBldrObj.getSqlFromRules();
  console.log('Generated SQL:', sqlQuery);
  // 发送至后端执行
}

Pattern 2: Programmatically Adding Rules

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

tsx

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

tsx

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

Pattern 3: Converting SQL Back to Rules

模式3：将SQL转换回规则

tsx

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

tsx

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

Pattern 4: Displaying Summary View

模式4：显示摘要视图

tsx

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

tsx

<QueryBuilderComponent 
  columns={columnData}
  summaryView={true}  // 在底部显示查询摘要
/>

Key Props Cheat Sheet

关键属性速查表

Prop	Type	Default	Purpose
`columns`	ColumnsModel[]	-	Defines available fields and operators
`rule`	RuleModel	{}	Initial filter rules
`dataSource`	Object[] \| DataManager	[]	Data for binding
`displayMode`	'Horizontal' \| 'Vertical'	'Horizontal'	Layout orientation
`allowDragAndDrop`	boolean	false	Enable drag-drop rule management
`enablePersistence`	boolean	false	Save state to localStorage
`enableRtl`	boolean	false	Right-to-left layout
`allowValidation`	boolean	false	Validate rule conditions
`summaryView`	boolean	false	Show filtered query summary
`showButtons`	ShowButtonsModel	defaults	Control add/delete button visibility
`maxGroupCount`	number	5	Maximum nested group depth
`readonly`	boolean	false	Make component read-only

属性	类型	默认值	用途
`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	默认配置	控制添加/删除按钮可见性
`maxGroupCount`	number	5	最大嵌套分组深度
`readonly`	boolean	false	将组件设置为只读

Common Use Cases

常见使用场景

Use Case 1: Advanced Search Filter

场景1：高级搜索筛选

Create a filter interface for users to build complex search queries with multiple conditions:

Define columns for searchable fields
Initialize with empty or default rules
Set
```
showButtons
```
to enable rule management
Retrieve SQL on form submission
Execute query on backend

Read: references/rules-and-filtering.md and references/query-conversion.md

为用户创建可构建多条件复杂搜索查询的筛选界面：

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

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

Use Case 2: Data-Driven Dashboard

场景2：数据驱动仪表盘

Build a dashboard where users filter data across multiple columns:

Bind DataManager with remote service
Configure columns based on data types
Enable drag-and-drop for better UX
Use getPredicate() to filter DataManager
Display filtered results dynamically

Read: references/data-binding.md and references/rules-and-filtering.md

构建允许用户跨多列筛选数据的仪表盘：

将DataManager与远程服务绑定
根据数据类型配置列
启用拖拽操作以提升用户体验
使用getPredicate()筛选DataManager数据
动态显示筛选结果

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

Use Case 3: Query Template System

场景3：查询模板系统

Allow users to save and load filter templates:

Set
```
enablePersistence={true}
```
for automatic state saving
Or manually save
```
getRules()
```
to database
Load rules with
```
setRules()
```
when needed
Display saved templates in a dropdown

Read: references/advanced-features.md

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

设置
```
enablePersistence={true}
```
以自动保存状态
或手动将
```
getRules()
```
保存至数据库
需要时使用
```
setRules()
```
加载规则
在下拉菜单中显示已保存模板

阅读：references/advanced-features.md

Use Case 4: Report Builder

场景4：报表构建器

Create a report filter UI with custom templates:

Design custom header template for branding
Use custom operators for domain-specific filtering
Enable validation with
```
allowValidation
```
Display
```
summaryView
```
for clarity
Generate SQL for report execution

Read: references/templates-and-customization.md and references/advanced-features.md

创建带有自定义模板的报表筛选UI：

设计自定义头部模板以实现品牌化
使用自定义运算符实现特定领域的筛选
启用
```
allowValidation
```
以支持验证
显示
```
summaryView
```
以提升清晰度
生成SQL用于报表执行

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

Next Steps

后续步骤

Getting Started: Install the package and create your first Query Builder
Define Columns: Configure the fields users can filter on
Bind Data: Connect to local or remote data sources
Build UI: Add rules and groups with drag-and-drop support
Generate Queries: Convert rules to SQL or other formats
Customize: Apply themes, templates, and accessibility features

Need help? Check the specific reference files above for detailed examples and implementation patterns.

快速入门：安装包并创建首个Query Builder
定义列：配置用户可筛选的字段
绑定数据：连接本地或远程数据源
构建UI：添加规则与分组，支持拖拽操作
生成查询：将规则转换为SQL或其他格式
自定义：应用主题、模板与无障碍功能

需要帮助？ 查看上述具体参考文件，获取详细示例与实现模式。