syncfusion-angular-query-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Query Builder

实现Syncfusion Angular Query Builder组件

The Syncfusion Angular Query Builder (

ejs-querybuilder

) is a UI component for visually constructing complex filter queries. Users define conditions (field + operator + value) and combine them into groups with AND/OR logic. The resulting rules can be exported to JSON, SQL, or MongoDB formats for use in filtering or API queries.

Syncfusion Angular Query Builder（

ejs-querybuilder

）是一个用于可视化构建复杂筛选查询的UI组件。用户可以定义条件（字段 + 操作符 + 值），并通过AND/OR逻辑将其组合成规则组。生成的规则可导出为JSON、SQL或MongoDB格式，用于筛选或API查询。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installing
```
@syncfusion/ej2-angular-querybuilder
```
Setting up CSS/theme imports (Material3)
Creating a basic Query Builder with columns
Rendering with an initial rule
Running the Angular application

📄 阅读： references/getting-started.md

安装
```
@syncfusion/ej2-angular-querybuilder
```
设置CSS/主题导入（Material3）
创建带列配置的基础Query Builder
使用初始规则渲染组件
运行Angular应用

Columns Configuration

列配置

📄 Read: references/columns.md

Defining columns with
```
field
```
,
```
label
```
,
```
type
```
Auto-generating columns from dataSource
Configuring operators per column (full operators table)
Setting step values for number fields
Formatting date and number values
Enabling validation (
```
allowValidation
```
,
```
isRequired
```
,
```
min
```
/
```
max
```
)

📄 阅读： references/columns.md

通过
```
field
```
、
```
label
```
、
```
type
```
定义列
从dataSource自动生成列
为每列配置操作符（完整操作符表）
为数字字段设置步长值
格式化日期和数字值
启用验证（
```
allowValidation
```
、
```
isRequired
```
、
```
min
```
/
```
max
```
）

Data Binding

数据绑定

📄 Read: references/data-binding.md

Local data binding (JS arrays,
```
JsonAdaptor
```
)
Remote data with
```
DataManager
```
(OData, OData v4, WebApiAdaptor)
Using
```
getPredicate()
```
with DataManager for filtering
Complex/nested data binding with sub-columns

📄 阅读： references/data-binding.md

本地数据绑定（JS数组、
```
JsonAdaptor
```
）
结合
```
DataManager
```
实现远程数据绑定（OData、OData v4、WebApiAdaptor）
结合
```
getPredicate()
```
与DataManager实现筛选
复杂/嵌套数据绑定（子列）

Filtering & Rules Management

筛选与规则管理

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

Adding/deleting conditions with
```
addRules
```
/
```
deleteRules
```
Adding/deleting groups with
```
addGroups
```
/
```
deleteGroups
```
Cloning rules/groups (
```
cloneRule
```
,
```
cloneGroup
```
)
Locking rules/groups (
```
lockRule
```
,
```
lockGroup
```
)
Separate connectors between rules (
```
enableSeparateConnector
```
)
Restricting group nesting depth (
```
maxGroupCount
```
)
Drag-and-drop rule reordering (
```
allowDragAndDrop
```
)
Controlling button visibility (
```
showButtons
```
)

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

使用
```
addRules
```
/
```
deleteRules
```
添加/删除条件
使用
```
addGroups
```
/
```
deleteGroups
```
添加/删除规则组
克隆规则/组（
```
cloneRule
```
、
```
cloneGroup
```
）
锁定规则/组（
```
lockRule
```
、
```
lockGroup
```
）
为规则设置独立连接符（
```
enableSeparateConnector
```
）
限制组嵌套深度（
```
maxGroupCount
```
）
拖拽重排规则（
```
allowDragAndDrop
```
）
控制按钮可见性（
```
showButtons
```
）

Import & Export

导入与导出

📄 Read: references/import-export.md

Importing from JSON (initial
```
rule
```
property +
```
setRules
```
)
Importing from SQL (inline, parameterized, named parameterized)
Importing from MongoDB (
```
setMongoQuery
```
)
Exporting to JSON (
```
getRules
```
)
Exporting to SQL (inline, parameterized, named parameterized)
Exporting to MongoDB (
```
getMongoQuery
```
)

📄 阅读： references/import-export.md

从JSON导入（初始
```
rule
```
属性 +
```
setRules
```
）
从SQL导入（内联、参数化、命名参数化）
从MongoDB导入（
```
setMongoQuery
```
）
导出为JSON（
```
getRules
```
）
导出为SQL（内联、参数化、命名参数化）
导出为MongoDB查询（
```
getMongoQuery
```
）

Templates & Model Binding

模板与模型绑定

📄 Read: references/templates.md

Custom header template with dropdown, split-button, NOT condition
Column template with
```
create
```
/
```
write
```
/
```
destroy
```
pattern
Using
```
NgTemplate
```
for column value inputs
Rule template (
```
ruleTemplate
```
+
```
actionBegin
```
event)
Model binding for field, operator, value inputs (
```
fieldModel
```
,
```
operatorModel
```
,
```
valueModel
```
)

📄 阅读： references/templates.md

带下拉菜单、拆分按钮、NOT条件的自定义头部模板
采用
```
create
```
/
```
write
```
/
```
destroy
```
模式的列模板
使用
```
NgTemplate
```
实现列值输入
规则模板（
```
ruleTemplate
```
+
```
actionBegin
```
事件）
字段、操作符、值输入的模型绑定（
```
fieldModel
```
、
```
operatorModel
```
、
```
valueModel
```
）

Style, Appearance & Layout

样式、外观与布局

📄 Read: references/style-and-appearance.md

CSS class customization table
Theme Studio integration
Display modes: horizontal (default) vs. vertical (
```
displayMode
```
)
Summary view (
```
summaryView
```
)
RTL support (
```
enableRtl
```
)
State persistence (
```
enablePersistence
```
)

📄 阅读： references/style-and-appearance.md

CSS类自定义表
Theme Studio集成
显示模式：水平（默认） vs 垂直（
```
displayMode
```
）
摘要视图（
```
summaryView
```
）
RTL支持（
```
enableRtl
```
）
状态持久化（
```
enablePersistence
```
）

Accessibility & Localization

可访问性与本地化

📄 Read: references/accessibility-and-localization.md

WCAG 2.2, Section 508, WAI-ARIA compliance
Keyboard navigation shortcuts
Localization setup and full locale key reference
Sort columns display (
```
sortDirection
```
)

📄 阅读： references/accessibility-and-localization.md

符合WCAG 2.2、Section 508、WAI-ARIA标准
键盘导航快捷键
本地化设置及完整区域键参考
列显示排序（
```
sortDirection
```
）

API Reference

API参考

📄 Read: references/api.md

Complete Properties reference (40+ properties)
Complete Methods reference (30+ methods)
Complete Events reference (7 events)
Type definitions and interfaces
Official Syncfusion documentation links

📄 阅读： references/api.md

完整属性参考（40+属性）
完整方法参考（30+方法）
完整事件参考（7个事件）
类型定义与接口
官方Syncfusion文档链接

Quick Start Example

快速入门示例

typescript

import { QueryBuilderModule } from '@syncfusion/ej2-angular-querybuilder';
import { Component } from '@angular/core';

@Component({
  imports: [QueryBuilderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-querybuilder width="70%" [rule]="importRules">
      <e-columns>
        <e-column field="EmployeeID" label="Employee ID" type="number"></e-column>
        <e-column field="FirstName" label="First Name" type="string"></e-column>
        <e-column field="Title" label="Title" type="string"></e-column>
        <e-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-column>
        <e-column field="Country" label="Country" type="string"></e-column>
      </e-columns>
    </ejs-querybuilder>
  `
})
export class App {
  public importRules = {
    condition: 'and',
    rules: [
      { field: 'EmployeeID', label: 'Employee ID', type: 'number', operator: 'equal', value: 1 },
      { field: 'Country', label: 'Country', type: 'string', operator: 'equal', value: 'USA' }
    ]
  };
}

Install with:

bash

ng add @syncfusion/ej2-angular-querybuilder

typescript

import { QueryBuilderModule } from '@syncfusion/ej2-angular-querybuilder';
import { Component } from '@angular/core';

@Component({
  imports: [QueryBuilderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-querybuilder width="70%" [rule]="importRules">
      <e-columns>
        <e-column field="EmployeeID" label="Employee ID" type="number"></e-column>
        <e-column field="FirstName" label="First Name" type="string"></e-column>
        <e-column field="Title" label="Title" type="string"></e-column>
        <e-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-column>
        <e-column field="Country" label="Country" type="string"></e-column>
      </e-columns>
    </ejs-querybuilder>
  `
})
export class App {
  public importRules = {
    condition: 'and',
    rules: [
      { field: 'EmployeeID', label: 'Employee ID', type: 'number', operator: 'equal', value: 1 },
      { field: 'Country', label: 'Country', type: 'string', operator: 'equal', value: 'USA' }
    ]
  };
}

安装命令：

bash

ng add @syncfusion/ej2-angular-querybuilder

Common Patterns

常见模式

Pattern 1: Export rules to SQL for backend use

模式1：将规则导出为SQL供后端使用

typescript

// In your component
import { QueryBuilderComponent } from '@syncfusion/ej2-angular-querybuilder';
import { ViewChild } from '@angular/core';

@ViewChild('querybuilder') qb!: QueryBuilderComponent;

getSqlQuery(): string {
  return this.qb.getSqlFromRules(this.qb.getRules());
}

typescript

// 在组件中
import { QueryBuilderComponent } from '@syncfusion/ej2-angular-querybuilder';
import { ViewChild } from '@angular/core';

@ViewChild('querybuilder') qb!: QueryBuilderComponent;

getSqlQuery(): string {
  return this.qb.getSqlFromRules(this.qb.getRules());
}

Pattern 2: Load rules at runtime

模式2：运行时加载规则

typescript

// After component renders, update rules dynamically
this.qb.setRules({
  condition: 'or',
  rules: [
    { field: 'City', operator: 'equal', value: 'London' },
    { field: 'Country', operator: 'equal', value: 'UK' }
  ]
});

typescript

// 组件渲染后，动态更新规则
this.qb.setRules({
  condition: 'or',
  rules: [
    { field: 'City', operator: 'equal', value: 'London' },
    { field: 'Country', operator: 'equal', value: 'UK' }
  ]
});

Pattern 3: Programmatically add a condition

模式3：以编程方式添加条件

typescript

// Add a rule to the root group
this.qb.addRules([{ field: 'Title', operator: 'contains', value: 'Manager' }], 'querybuilder_group0');

typescript

// 向根组添加规则
this.qb.addRules([{ field: 'Title', operator: 'contains', value: 'Manager' }], 'querybuilder_group0');

Pattern 4: Enable drag-and-drop + clone + lock

模式4：启用拖拽 + 克隆 + 锁定

html

<ejs-querybuilder [allowDragAndDrop]="true" [showButtons]="showButtons">
</ejs-querybuilder>

typescript

public showButtons = { ruleDelete: true, groupInsert: true, groupDelete: true, ruleInsert: true, cloneRule: true, cloneGroup: true, lockRule: true, lockGroup: true };

html

<ejs-querybuilder [allowDragAndDrop]="true" [showButtons]="showButtons">
</ejs-querybuilder>

typescript

public showButtons = { ruleDelete: true, groupInsert: true, groupDelete: true, ruleInsert: true, cloneRule: true, cloneGroup: true, lockRule: true, lockGroup: true };

Key Properties

核心属性

Property	Type	Purpose
`[rule]`	RuleModel	Initial query rules to render
`[columns]`	ColumnsModel[]	Column definitions (field, label, type, operators)
`[dataSource]`	object[] / DataManager	Data for auto-column generation and predicate
`[allowDragAndDrop]`	boolean	Enable drag-and-drop rule/group reordering
`[enableSeparateConnector]`	boolean	Different AND/OR per rule instead of per group
`[enableNotCondition]`	boolean	Show NOT condition toggle on groups
`[summaryView]`	boolean	Show human-readable summary of current query
`[enablePersistence]`	boolean	Persist rules to localStorage across refreshes
`[enableRtl]`	boolean	Right-to-left layout for RTL languages
`[displayMode]`	string	`'Horizontal'` (default) or `'Vertical'` layout
`[maxGroupCount]`	number	Max number of nested groups (default: 5)
`[sortDirection]`	string	Sort field dropdown: `'Ascending'` or `'Descending'`
`[allowValidation]`	boolean	Enable field/operator/value validation
`[showButtons]`	ShowButtons	Control visibility of action buttons

属性	类型	用途
`[rule]`	RuleModel	渲染初始查询规则
`[columns]`	ColumnsModel[]	列定义（字段、标签、类型、操作符）
`[dataSource]`	object[] / DataManager	用于自动列生成和谓词的数据
`[allowDragAndDrop]`	boolean	启用规则/组拖拽重排
`[enableSeparateConnector]`	boolean	为每个规则设置独立的AND/OR（而非按组设置）
`[enableNotCondition]`	boolean	在规则组上显示NOT条件切换按钮
`[summaryView]`	boolean	显示当前查询的易读性摘要
`[enablePersistence]`	boolean	将规则持久化到localStorage，刷新后保留
`[enableRtl]`	boolean	为RTL语言启用从右到左布局
`[displayMode]`	string	`'Horizontal'` （默认）或 `'Vertical'` 布局
`[maxGroupCount]`	number	最大嵌套组数量（默认：5）
`[sortDirection]`	string	字段下拉框排序： `'Ascending'` 或 `'Descending'`
`[allowValidation]`	boolean	启用字段/操作符/值验证
`[showButtons]`	ShowButtons	控制操作按钮的可见性

Key Methods

核心方法

Method	Purpose
`getRules()`	Get current rules as JSON RuleModel
`setRules(rules)`	Set rules programmatically at runtime
`getSqlFromRules(rules)`	Export rules to inline SQL string
`setRulesFromSql(sql)`	Import inline SQL string into Query Builder
`getMongoQuery(rules)`	Export rules to MongoDB query string
`setMongoQuery(query)`	Import MongoDB query string
`addRules(rules, groupID)`	Add rules to a specific group
`deleteRules(ruleIDs)`	Remove rules by ID
`addGroups(groups, groupID)`	Add sub-groups to a group
`deleteGroups(groupIDs)`	Remove groups by ID
`cloneRule(ruleID)`	Clone a rule adjacent to the original
`cloneGroup(groupID)`	Clone a group with all its rules
`lockRule(ruleID)`	Make a rule read-only
`lockGroup(groupID)`	Make a group and its contents read-only
`validateFields()`	Trigger validation on all fields

方法	用途
`getRules()`	获取当前规则的JSON格式RuleModel
`setRules(rules)`	运行时以编程方式设置规则
`getSqlFromRules(rules)`	将规则导出为内联SQL字符串
`setRulesFromSql(sql)`	将内联SQL字符串导入到查询构建器
`getMongoQuery(rules)`	将规则导出为MongoDB查询字符串
`setMongoQuery(query)`	导入MongoDB查询字符串
`addRules(rules, groupID)`	向指定组添加规则
`deleteRules(ruleIDs)`	通过ID删除规则
`addGroups(groups, groupID)`	向指定组添加子组
`deleteGroups(groupIDs)`	通过ID删除组
`cloneRule(ruleID)`	在原规则旁克隆规则
`cloneGroup(groupID)`	克隆包含所有规则的组
`lockRule(ruleID)`	将规则设为只读
`lockGroup(groupID)`	将组及其内容设为只读
`validateFields()`	触发所有字段的验证

Common Use Cases

常见使用场景

Admin dashboards: Let users build custom data filters without writing SQL
Report builders: Generate WHERE clause conditions for dynamic reports
Search interfaces: Visual query construction for complex search forms
Data export tools: Build MongoDB/SQL filters from a UI, pass to API
Saved searches: Export rules to JSON, store, and reload with
```
setRules
```

管理仪表盘： 让用户无需编写SQL即可构建自定义数据筛选器
报表生成器： 为动态报表生成WHERE子句条件
搜索界面： 为复杂搜索表单实现可视化查询构建
数据导出工具： 通过UI构建MongoDB/SQL筛选器，传递给API
保存的搜索： 将规则导出为JSON，存储后通过
```
setRules
```
重新加载