syncfusion-aspnetcore-query-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing QueryBuilder in ASP.NET Core

在ASP.NET Core中实现QueryBuilder

The Syncfusion QueryBuilder is a UI component for creating and editing filter conditions visually. Users can define rules and groups, combine them with AND/OR connectors, and export them as JSON, SQL, or MongoDB queries — all using ASP.NET Core TagHelper syntax.

Syncfusion QueryBuilder是一个用于可视化创建和编辑过滤条件的UI组件。用户可以定义规则和分组，使用AND/OR连接器组合它们，并通过ASP.NET Core TagHelper语法将其导出为JSON、SQL或MongoDB查询。

Navigation Guide

导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

NuGet package installation and TagHelper setup
CDN stylesheet and script references
Basic QueryBuilder with columns
Render with initial Rule (JSON)
EmployeeView model class example

📄 阅读： references/getting-started.md

NuGet包安装与TagHelper配置
CDN样式表和脚本引用
带列的基础QueryBuilder
使用初始规则（JSON）渲染
EmployeeView模型类示例

Column Configuration

列配置

📄 Read: references/columns.md

Auto-generating columns from DataSource
Labels, field mapping, data types
Operators table (all supported types)
Number step and date/number format
Validation (isRequired, min, max)
Column-level custom input templates

📄 阅读： references/columns.md

从数据源自动生成列
标签、字段映射、数据类型
运算符表（所有支持类型）
数字步长和日期/数字格式
验证（必填、最小值、最大值）
列级自定义输入模板

Data Binding

数据绑定

📄 Read: references/data-binding.md

Local data binding (JSON array, DataManager)
Remote data (OData, ODataV4, WebAPI, UrlAdaptor)
Using getPredicate to filter data
Grid integration via ruleChange event

📄 阅读： references/data-binding.md

本地数据绑定（JSON数组、DataManager）
远程数据（OData、ODataV4、WebAPI、UrlAdaptor）
使用getPredicate过滤数据
通过ruleChange事件集成Grid

Import & Export

导入与导出

📄 Read: references/import-export.md

Import from JSON (initial Rule / setRules)
Import from SQL (Inline, Parameter, Named Parameter)
Import from MongoDB (setMongoQuery)
Export to JSON (getRules)
Export to SQL variants and MongoDB

📄 阅读： references/import-export.md

从JSON导入（初始规则/setRules）
从SQL导入（内联、参数化、命名参数）
从MongoDB导入（setMongoQuery）
导出为JSON（getRules）
导出为多种SQL变体和MongoDB查询

Filtering & Rule Management

过滤与规则管理

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

ShowButtons configuration (ruleDelete, groupInsert, groupDelete, clone, lock)
addRules / deleteRules / addGroups / deleteGroups methods
cloneGroup / cloneRule methods
lockGroup / lockRule methods
EnableSeparateConnector between rules
EnableNotCondition for NOT groups

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

ShowButtons配置（规则删除、分组插入、分组删除、克隆、锁定）
addRules / deleteRules / addGroups / deleteGroups方法
cloneGroup / cloneRule方法
lockGroup / lockRule方法
启用规则间独立连接器
为分组启用NOT条件

Templates & Appearance

模板与外观

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

Header template customization
Display mode (Horizontal / Vertical)
Summary view (collapsed read-only display)
Model binding (fieldModel, operatorModel, valueModel)
CSS classes for styling customization

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

头部模板自定义
显示模式（水平/垂直）
摘要视图（折叠只读显示）
模型绑定（fieldModel、operatorModel、valueModel）
用于样式自定义的CSS类

Configuration & How-To

配置与操作指南

📄 Read: references/configuration-and-how-to.md

Drag and drop (AllowDragAndDrop, events)
MaxGroupCount to restrict nested groups
SortDirection for column field ordering
EnablePersistence (state saved in localStorage)
EnableRtl for right-to-left languages
ReadOnly mode, Width/Height, CssClass
AutoSelectField, AutoSelectOperator, MatchCase

📄 阅读： references/configuration-and-how-to.md

拖拽功能（AllowDragAndDrop、事件）
MaxGroupCount限制嵌套分组
列字段排序方向
启用持久化（状态保存到localStorage）
启用RTL（从右到左语言）
只读模式、宽/高、CssClass
AutoSelectField、AutoSelectOperator、MatchCase

Localization

本地化

📄 Read: references/localization.md

Setting the Locale property
Full locale key reference table
Example: Arabic / RTL localization

📄 阅读： references/localization.md

设置Locale属性
完整的本地化键参考表
示例：阿拉伯语/RTL本地化

API Reference

API参考

📄 Read: references/api.md

Complete properties with types and defaults
All events with descriptions
QueryBuilderColumn sub-properties
QueryBuilderShowButtons sub-properties
TagHelper attribute naming conventions

📄 阅读： references/api.md

带类型和默认值的完整属性
所有事件及描述
QueryBuilderColumn子属性
QueryBuilderShowButtons子属性
TagHelper属性命名规范

Quick Start Example

快速入门示例

cshtml

@* _ViewImports.cshtml must have: @addTagHelper *, Syncfusion.EJ2 *@

<ejs-querybuilder id="querybuilder" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Title" label="Title" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

cshtml

@* _ViewImports.cshtml必须包含：@addTagHelper *, Syncfusion.EJ2 *@

<ejs-querybuilder id="querybuilder" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Title" label="Title" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Common Patterns

常见模式

Render with Initial Rule

使用初始规则渲染

cshtml

@using Syncfusion.EJ2.QueryBuilder
@{
    QueryBuilderRule rule = new QueryBuilderRule()
    {
        Condition = "and",
        Rules = new List<QueryBuilderRule>()
        {
            new QueryBuilderRule { Label = "First Name", Field = "FirstName", Type = "string", Operator = "startswith", Value = "Nancy" },
            new QueryBuilderRule { Label = "Country", Field = "Country", Type = "string", Operator = "equal", Value = "USA" }
        }
    };
    var dataSource = EmployeeView.GetAllRecords();
}
<ejs-querybuilder id="querybuilder" width="70%" rule="rule" dataSource="dataSource">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

cshtml

@using Syncfusion.EJ2.QueryBuilder
@{
    QueryBuilderRule rule = new QueryBuilderRule()
    {
        Condition = "and",
        Rules = new List<QueryBuilderRule>()
        {
            new QueryBuilderRule { Label = "First Name", Field = "FirstName", Type = "string", Operator = "startswith", Value = "Nancy" },
            new QueryBuilderRule { Label = "Country", Field = "Country", Type = "string", Operator = "equal", Value = "USA" }
        }
    };
    var dataSource = EmployeeView.GetAllRecords();
}
<ejs-querybuilder id="querybuilder" width="70%" rule="rule" dataSource="dataSource">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Export Rules to SQL

将规则导出为SQL

javascript

var queryBuilder = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);

// Get JSON rules
var jsonRules = queryBuilder.getRules();

// Get Inline SQL
var sql = queryBuilder.getSqlFromRules(jsonRules);

// Get Parameterized SQL
var paramSql = queryBuilder.getParameterizedSql(jsonRules);

javascript

var queryBuilder = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);

// 获取JSON规则
var jsonRules = queryBuilder.getRules();

// 获取内联SQL
var sql = queryBuilder.getSqlFromRules(jsonRules);

// 获取参数化SQL
var paramSql = queryBuilder.getParameterizedSql(jsonRules);

Grid Integration with QueryBuilder

QueryBuilder与Grid集成

javascript

// In ruleChange event handler:
function ruleChanged(args) {
    var qryBldrObj = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);
    var gridObj = ej.base.getInstance(document.getElementById("Grid"), ejs.grids.Grid);
    gridObj.query = qryBldrObj.getDataManagerQuery(qryBldrObj.getRules());
    gridObj.refresh();
}

javascript

// 在ruleChange事件处理程序中：
function ruleChanged(args) {
    var qryBldrObj = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);
    var gridObj = ej.base.getInstance(document.getElementById("Grid"), ejs.grids.Grid);
    gridObj.query = qryBldrObj.getDataManagerQuery(qryBldrObj.getRules());
    gridObj.refresh();
}

Drag and Drop Enabled

启用拖拽功能

cshtml

<ejs-querybuilder id="querybuilder" allowDragAndDrop="true" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

cshtml

<ejs-querybuilder id="querybuilder" allowDragAndDrop="true" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Key Properties Quick Reference

关键属性速查

Property	TagHelper Attribute	Purpose
`Columns`	`e-querybuilder-columns`	Define filterable fields
`Rule`	`rule="rule"`	Initial rule — C# `QueryBuilderRule` object
`DataSource`	`dataSource`	Bind local/remote data
`AllowDragAndDrop`	`allowDragAndDrop`	Enable rule reordering
`AllowValidation`	`allowValidation`	Validate rule inputs
`EnableSeparateConnector`	`enableSeparateConnector`	Per-rule AND/OR connectors
`EnableNotCondition`	`enableNotCondition`	NOT group operator
`MaxGroupCount`	`maxGroupCount`	Limit nested group depth
`SummaryView`	`summaryView`	Show collapsed rule summary
`DisplayMode`	`displayMode`	Horizontal or Vertical layout
`EnablePersistence`	`enablePersistence`	Save state to localStorage
`EnableRtl`	`enableRtl`	Right-to-left layout
`SortDirection`	`sortDirection`	Sort column field list
`Readonly`	`readonly`	Disable all interactions
`Width` / `Height`	`width` / `height`	Component dimensions

属性	TagHelper属性	用途
`Columns`	`e-querybuilder-columns`	定义可过滤字段
`Rule`	`rule="rule"`	初始规则 — C# `QueryBuilderRule` 对象
`DataSource`	`dataSource`	绑定本地/远程数据
`AllowDragAndDrop`	`allowDragAndDrop`	启用规则重排
`AllowValidation`	`allowValidation`	验证规则输入
`EnableSeparateConnector`	`enableSeparateConnector`	规则级AND/OR连接器
`EnableNotCondition`	`enableNotCondition`	NOT分组运算符
`MaxGroupCount`	`maxGroupCount`	限制嵌套分组深度
`SummaryView`	`summaryView`	显示折叠式规则摘要
`DisplayMode`	`displayMode`	水平或垂直布局
`EnablePersistence`	`enablePersistence`	将状态保存到localStorage
`EnableRtl`	`enableRtl`	从右到左布局
`SortDirection`	`sortDirection`	排序列字段列表
`Readonly`	`readonly`	禁用所有交互
`Width` / `Height`	`width` / `height`	组件尺寸

Common Use Cases

常见使用场景

Data grid filter UI → QueryBuilder + Grid integration via
```
ruleChange
```
Save/restore conditions →
```
getRules
```
+
```
setRules
```
with localStorage or backend
SQL WHERE clause builder →
```
getSqlFromRules
```
/
```
getParameterizedSql
```
MongoDB filter →
```
getMongoQuery
```
/
```
setMongoQuery
```
Read-only filter display →
```
summaryView="true"
```
+
```
readonly="true"
```
Mobile-friendly layout →
```
displayMode="Vertical"
```
+
```
maxGroupCount="2"
```
Localized UI →
```
locale
```
property + L10n translation object

数据网格过滤UI → 通过
```
ruleChange
```
集成QueryBuilder + Grid
保存/恢复条件 → 使用
```
getRules
```
+
```
setRules
```
结合localStorage或后端存储
SQL WHERE子句构建器 →
```
getSqlFromRules
```
/
```
getParameterizedSql
```
MongoDB过滤器 →
```
getMongoQuery
```
/
```
setMongoQuery
```
只读过滤显示 →
```
summaryView="true"
```
+
```
readonly="true"
```
移动端友好布局 →
```
displayMode="Vertical"
```
+
```
maxGroupCount="2"
```
本地化UI →
```
locale
```
属性 + L10n翻译对象

Security & Trust Boundary

安全与信任边界

External Dependency: CDN-Based JavaScript Execution

外部依赖：基于CDN的JavaScript执行

The Syncfusion QueryBuilder requires runtime execution of external JavaScript from the official CDN endpoint (

https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js

). This is a required trusted dependency with the following security considerations:

Syncfusion QueryBuilder需要从官方CDN端点（

https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js

）运行外部JavaScript。这是一个必需的可信依赖，需考虑以下安全事项：

Risk Mitigation Strategies

风险缓解策略

Use HTTPS Only
- Always reference CDN resources via HTTPS to prevent man-in-the-middle attacks
- Verify your layout template uses
```
https://
```
  scheme

Subresource Integrity (SRI)

Include SRI hash attributes to validate script integrity:

html

<script src="https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js" 
        integrity="sha384-[HASH]" 
        crossorigin="anonymous"></script>

Content Security Policy (CSP)

Add Syncfusion CDN to your CSP whitelist:

script-src 'self' https://cdn.syncfusion.com;
style-src 'self' https://cdn.syncfusion.com;

Vendor Lock & Trust Assessment
- Trusted Vendor: Syncfusion is an established commercial component vendor with industry adoption
- No Open-Source Alternatives: QueryBuilder functionality is specialized; evaluate internal development costs vs. vendor dependency
- Consider Bundling: For enhanced control, bundle Syncfusion scripts locally instead of using CDN (download and host on your own domain)

Version Pinning

Always pin the specific version instead of using wildcard versions:

❌ https://cdn.syncfusion.com/ej2/latest/dist/ej2.min.js
✅ https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js

Update Management
- Regularly update Syncfusion NuGet packages and verify corresponding CDN versions match
- Subscribe to Syncfusion security announcements
- Test updates in staging environment before production deployment

仅使用HTTPS
- 始终通过HTTPS引用CDN资源，防止中间人攻击
- 验证你的布局模板使用
```
https://
```
  协议

子资源完整性（SRI）

包含SRI哈希属性以验证脚本完整性：

html

<script src="https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js" 
        integrity="sha384-[HASH]" 
        crossorigin="anonymous"></script>

内容安全策略（CSP）

将Syncfusion CDN添加到你的CSP白名单：

script-src 'self' https://cdn.syncfusion.com;
style-src 'self' https://cdn.syncfusion.com;

供应商锁定与信任评估
- 可信供应商：Syncfusion是成熟的商业组件供应商，已获得行业广泛采用
- 无开源替代方案：QueryBuilder功能具有专业性；需评估内部开发成本与供应商依赖的权衡
- 考虑打包：为增强控制，可将Syncfusion脚本本地打包，而非使用CDN（下载并托管在自有域名）

版本固定

始终固定特定版本，而非使用通配符版本：

❌ https://cdn.syncfusion.com/ej2/latest/dist/ej2.min.js
✅ https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js

更新管理
- 定期更新Syncfusion NuGet包，并验证对应的CDN版本匹配
- 订阅Syncfusion安全公告
- 在生产部署前，在 staging 环境测试更新

Acceptable Risk Assessment

可接受风险评估

Severity: Medium (requires trust boundary evaluation at deployment)
Mitigation: Implement SRI + CSP + version pinning
Approval: Obtain security team sign-off for use in compliant applications

Start here: Read references/getting-started.md to set up your first QueryBuilder.

undefined

严重程度：中等（部署时需评估信任边界）
缓解措施：实施SRI + CSP + 版本固定
审批：合规应用使用前需获得安全团队签字确认

开始： 阅读 references/getting-started.md 搭建你的第一个QueryBuilder。