syncfusion-angular-query-builder

用途

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

主要能力

资料中列出的能力包括：

列配置：定义列的 field、label、type；可从 dataSource 自动生成列；按列配置运算符；为数字字段设置步进值；格式化日期与数字值；启用校验（allowValidation、isRequired、min/max）。
数据绑定：使用 JS 数组进行本地数据绑定（JsonAdaptor，资料标注为推荐且安全）；支持复杂/嵌套数据绑定与子列。
筛选与规则管理：通过 addRules / deleteRules 增删条件；通过 addGroups / deleteGroups 增删分组；克隆规则/分组（cloneRule、cloneGroup）；锁定规则/分组（lockRule、lockGroup）；启用规则间独立连接符（enableSeparateConnector）；限制分组嵌套深度（maxGroupCount）；拖拽重排序（allowDragAndDrop）；控制按钮可见性（showButtons）。
导入与导出：从 JSON 导入（initial rule 属性 + setRules）；从 SQL 导入（内联、参数化、命名参数化）；从 MongoDB 导入（setMongoQuery）；导出为 JSON（getRules）；导出为 SQL（内联、参数化、命名参数化）；导出为 MongoDB（getMongoQuery）。
模板与模型绑定：自定义头部模板（含下拉、拆分按钮、NOT 条件）；列模板（create / write / destroy 模式）；使用 NgTemplate 作为列值输入；规则模板（ruleTemplate + actionBegin 事件）；字段、运算符、值输入的模型绑定（fieldModel、operatorModel、valueModel）。
样式、外观与布局：CSS 类自定义；Theme Studio 集成；水平（默认）与垂直显示模式（displayMode）；摘要视图（summaryView）；RTL 支持（enableRtl）；状态持久化（enablePersistence）。
无障碍与本地化：资料称符合 WCAG 2.2、Section 508、WAI-ARIA；键盘导航快捷键；本地化设置与完整 locale 键参考；列显示排序（sortDirection）。
API 参考：完整 Properties（40+）、Methods（30+）、Events（7）以及类型定义与接口。

使用方式

安装命令：

ng add @syncfusion/ej2-angular-querybuilder

快速开始示例（原文代码）：

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

入门步骤包括：安装 @syncfusion/ej2-angular-querybuilder；设置 CSS/主题导入（Material3）；创建带列的基本 Query Builder；使用初始规则渲染；运行 Angular 应用。

常见模式（原文代码）：

// Pattern 1: Export rules to SQL for backend use
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
this.qb.setRules({
  condition: 'or',
  rules: [
    { field: 'City', operator: 'equal', value: 'London' },
    { field: 'Country', operator: 'equal', value: 'UK' }
  ]
});

// Pattern 3: Programmatically add a condition
this.qb.addRules([{ field: 'Title', operator: 'contains', value: 'Manager' }], 'querybuilder_group0');

<!-- Pattern 4: Enable drag-and-drop + clone + lock -->
<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]（初始规则）、[columns]（列定义）、[dataSource]（仅限本地 JS 数组）、[allowDragAndDrop]、[enableSeparateConnector]、[enableNotCondition]、[summaryView]、[enablePersistence]、[enableRtl]、[displayMode]、[maxGroupCount]（默认 5）、[sortDirection]、[allowValidation]、[showButtons]。

关键方法包括：getRules()、setRules(rules)、getSqlFromRules(rules)、setRulesFromSql(sql)、getMongoQuery(rules)、setMongoQuery(query)、addRules(rules, groupID)、deleteRules(ruleIDs)、addGroups(groups, groupID)、deleteGroups(groupIDs)、cloneRule(ruleID)、cloneGroup(groupID)、lockRule(ruleID)、lockGroup(groupID)、validateFields()。

适用场景

资料列出的常见用例：管理后台仪表盘（让用户无需编写 SQL 即可构建自定义数据筛选）；报表构建器（为动态报表生成 WHERE 条件）；搜索界面（复杂搜索表单的可视化查询构建）；数据导出工具（在 UI 中构建 MongoDB/SQL 过滤器并传给 API）；保存的搜索（将规则导出为 JSON 存储，并用 setRules 重新加载）。

限制与安全边界

资料明确提出安全与信任边界要求：

禁止项：不得将 [dataSource] 绑定到指向任意或用户提供的 URL 的远程 DataManager（OData、OData v4、WebApiAdaptor 或任何外部 HTTP 端点）。资料指出该做法会导致组件从不受信任的远程 schema 自动生成列与运算符、将不受信任的字段名与值嵌入导出的 SQL/MongoDB 查询，并允许远程控制的数据改变运行时行为。该模式不得被作为推荐做法教授、搭建或引用。
必需实践：只使用直接在组件中传入的本地 JS 数组（object[]），绝不传入指向外部 URL 的 DataManager 实例；始终通过 <e-columns> / [columns] 显式定义列，绝不从远程或未知数据源自动生成列；在将 getSqlFromRules() 或 getMongoQuery() 输出传给任何后端之前，必须依据硬编码的允许列表校验每个字段名，并在服务端清理所有值；通过 setRules() 或 setRulesFromSql() 加载的规则必须来自自有可信存储（例如自有数据库），绝不能来自未经校验的外部来源；始终设置 [allowValidation]="true" 与 [maxGroupCount]，在导出前于 UI 层拒绝畸形输入。

其他未在资料中说明的收费、价格、平台或效果信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制与安全边界