syncfusion-aspnetcore-query-builder

在 ASP.NET Core 中实现 QueryBuilder

Syncfusion QueryBuilder 是一个用于以可视化方式创建和编辑筛选条件的 UI 组件。用户可以定义规则和组，使用 AND/OR 连接符将它们组合起来，并将其导出为 JSON、SQL 或 MongoDB 查询——所有操作均使用 ASP.NET Core TagHelper 语法。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包并设置 TagHelper
• 引用 CDN 样式表和脚本
• 使用列创建基本 QueryBuilder
• 使用初始 Rule（JSON）进行渲染
• EmployeeView 模型类示例

列配置

📄 阅读： references/columns.md

• 根据 DataSource 自动生成列
• 标签、字段映射和数据类型
• 运算符表（所有支持的类型）
• 数字步长以及日期/数字格式
• 验证（isRequired、min、max）
• 列级自定义输入模板

数据绑定

📄 阅读： references/data-binding.md

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

导入和导出

📄 阅读： references/import-export.md

• 从 JSON 导入（初始 Rule / setRules）
• 从 SQL 导入（Inline、Parameter、Named Parameter）
• 从 MongoDB 导入（setMongoQuery）
• 导出为 JSON（getRules）
• 导出为各种 SQL 格式和 MongoDB

筛选和规则管理

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

• 配置 ShowButtons（ruleDelete、groupInsert、groupDelete、clone、lock）
• addRules / deleteRules / addGroups / deleteGroups 方法
• cloneGroup / cloneRule 方法
• lockGroup / lockRule 方法
• 启用规则之间的 EnableSeparateConnector
• 启用用于 NOT 组的 EnableNotCondition

模板和外观

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

• 自定义标题模板
• 显示模式（Horizontal / Vertical）
• 摘要视图（折叠的只读显示）
• 模型绑定（fieldModel、operatorModel、valueModel）
• 用于自定义样式的 CSS 类

配置和使用指南

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

• 拖放（AllowDragAndDrop、事件）
• 使用 MaxGroupCount 限制嵌套组
• 使用 SortDirection 对列字段排序
• EnablePersistence（状态保存在 localStorage 中）
• 为从右到左的语言启用 EnableRtl
• ReadOnly 模式、Width/Height、CssClass
• AutoSelectField、AutoSelectOperator、MatchCase

本地化

📄 阅读： references/localization.md

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

API 参考

📄 阅读： references/api.md

• 完整的属性、类型和默认值
• 所有事件及其说明
• QueryBuilderColumn 子属性
• QueryBuilderShowButtons 子属性
• TagHelper 属性命名约定

快速入门示例

@* _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>

常见模式

使用初始 Rule 进行渲染

@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>

将规则导出为 SQL

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);

将 Grid 与 QueryBuilder 集成

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

启用拖放

<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>

关键属性速查

属性	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	组件尺寸

常见用例

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

安全与信任边界

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

Syncfusion QueryBuilder 需要在运行时从官方 CDN 端点（https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js）执行外部 JavaScript。这是一项必需的可信依赖，需要考虑以下安全事项：

风险缓解策略

1. 仅使用 HTTPS

   • 始终通过 HTTPS 引用 CDN 资源，以防止中间人攻击
   • 确认布局模板使用 https:// 协议

2. 子资源完整性（SRI）

   • 添加 SRI 哈希属性以验证脚本完整性：

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

3. 内容安全策略（CSP）

   • 将 Syncfusion CDN 添加到 CSP 白名单：

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

4. 供应商锁定与信任评估

   • 可信供应商：Syncfusion 是一家成熟的商业组件供应商，已在业内得到广泛采用
   • 没有开源替代方案：QueryBuilder 功能较为专用；请评估内部开发成本与依赖供应商之间的取舍
   • 考虑打包：为增强控制，可将 Syncfusion 脚本打包到本地，而不使用 CDN（下载并托管在自己的域名下）

5. 固定版本

   • 始终固定到特定版本，而不要使用通配符版本：

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

6. 更新管理

   • 定期更新 Syncfusion NuGet 包，并确认对应的 CDN 版本一致
   • 订阅 Syncfusion 安全公告
   • 在生产环境部署前，先在预发布环境中测试更新

可接受风险评估

• 严重性：中等（部署时需要评估信任边界）
• 缓解措施：实施 SRI + CSP + 版本固定
• 审批：在合规应用中使用前，取得安全团队批准

---

**从这里开始：**阅读 references/getting-started.md，设置你的第一个 QueryBuilder。