syncfusion-angular-query-builder

实现 Syncfusion Angular Query Builder

Syncfusion Angular Query Builder（ejs-querybuilder）是一款用于可视化构建复杂筛选查询的 UI 组件。用户可以定义条件（字段 + 运算符 + 值），并使用 AND/OR 逻辑将其组合成组。生成的规则可以导出为 JSON、SQL 或 MongoDB 格式，用于筛选或 API 查询。

导航指南

入门

📄 阅读： references/getting-started.md

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

列配置

📄 阅读： references/columns.md

• 使用 field、label、type 定义列
• 从 dataSource 自动生成列
• 配置每列的运算符（完整运算符表）
• 设置数字字段的步进值
• 格式化日期和数字值
• 启用验证（allowValidation、isRequired、min/max）

数据绑定

📄 阅读： references/data-binding.md

• 使用 JS 数组进行本地数据绑定（JsonAdaptor）——推荐且安全
• 使用子列进行复杂/嵌套数据绑定
• ⚠️ 本参考中记录的远程 DataManager（OData、WebApiAdaptor）模式不推荐——使用前请参阅下方的安全与信任边界

筛选与规则管理

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

• 使用 addRules / deleteRules 添加/删除条件
• 使用 addGroups / deleteGroups 添加/删除组
• 克隆规则/组（cloneRule、cloneGroup）
• 锁定规则/组（lockRule、lockGroup）
• 设置规则之间的独立连接符（enableSeparateConnector）
• 限制组的嵌套深度（maxGroupCount）
• 拖放重新排序规则（allowDragAndDrop）
• 控制按钮的显示状态（showButtons）

导入与导出

📄 阅读： references/import-export.md

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

模板与模型绑定

📄 阅读： references/templates.md

• 自定义标题模板，包含下拉菜单、分割按钮和 NOT 条件
• 使用 create / write / destroy 模式创建列模板
• 使用 NgTemplate 创建列值输入项
• 规则模板（ruleTemplate + actionBegin 事件）
• 为字段、运算符和值输入项进行模型绑定（fieldModel、operatorModel、valueModel）

样式、外观与布局

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

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

无障碍与本地化

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

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

API 参考

📄 阅读： references/api.md

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

---

快速入门示例

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' }
    ]
  };
}

安装命令：

ng add @syncfusion/ej2-angular-querybuilder

---

常见模式

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

// 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());
}

模式 2：在运行时加载规则

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

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

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

模式 4：启用拖放、克隆和锁定

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

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

---

关键属性

属性	类型	用途
[rule]	RuleModel	要渲染的初始查询规则
[columns]	ColumnsModel[]	列定义（字段、标签、类型、运算符）
[dataSource]	object[]	仅限本地 JS 数组 — 不要绑定到远程 DataManager 或任意 URL（参见安全性部分）
[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	控制操作按钮的可见性

关键方法

方法	用途
getRules()	将当前规则作为 JSON RuleModel 获取
setRules(rules)	在运行时以编程方式设置规则
getSqlFromRules(rules)	将规则导出为内联 SQL 字符串
setRulesFromSql(sql)	将内联 SQL 字符串导入 Query Builder
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()	触发对所有字段的验证

常见用例

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

---

安全性与信任边界

禁止 — 实施任何数据绑定前请阅读。

不允许的事项

禁止将 [dataSource] 绑定到使用任意 URL 或用户提供 URL 的远程 DataManager（OData、OData v4、WebApiAdaptor 或任何外部 HTTP 端点）。这样做会导致组件：

• 直接根据不可信的远程架构自动生成列和运算符
• 将不可信的字段名和值嵌入导出的 SQL/MongoDB 查询
• 允许远程控制的数据改变运行时行为（谓词、规则、查询结构）

不得将此模式作为推荐方法进行讲解、搭建脚手架或引用。

必须遵循的实践

规则	要求
数据源	仅使用直接传入组件的本地 JS 数组（object[]）。切勿传入指向外部 URL 的 DataManager 实例。
列定义	始终通过 <e-columns> / [columns] 显式定义列。切勿根据远程或未知数据源自动生成列。
导出净化	将 getSqlFromRules() 或 getMongoQuery() 的输出传递给任何后端之前，请针对硬编码的允许列表验证每个字段名称，并在服务器端净化所有值。
规则输入	通过 setRules() 或 setRulesFromSql() 加载的规则必须来自你自己的可信存储（例如自己的数据库），切勿来自未经验证的外部数据源。
验证	始终设置 [allowValidation]="true" 和 [maxGroupCount]，以便在导出前于 UI 层拒绝格式错误的输入。