SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场syncfusion-javascript-query-builder

syncfusion-javascript-query-builder

前端与建站

查看项目

更新于 10-16 02:02

技能介绍

用途

Syncfusion JavaScript QueryBuilder 是一个用于构建动态、复杂查询的可视化 UI 组件。该技能提供在 TypeScript 应用中实现、配置和自定义 QueryBuilder 的全面指导，让用户无需编写代码即可构建复杂的过滤条件。

主要能力

  • 支持多种数据类型：字符串、数字、日期、布尔。
  • 支持多种运算符：等于、包含、介于等。
  • 支持使用 AND/OR 条件对规则进行分组，以及嵌套分组层级。
  • 支持自定义模板以定制 UI。
  • 支持拖拽交互：重排、克隆、锁定规则。
  • 支持 JSON 导入/导出与 SQL 生成。
  • 支持 RTL 和完整键盘无障碍访问，符合 WCAG 2.1 AA 标准。

使用方式

文档按主题组织，包含以下参考文件：

  • 入门：安装与 npm 包设置、Syncfusion 依赖配置、CSS 导入与主题设置、基本初始化、列定义、运行第一个应用。
  • 列与架构定义：列定义与架构结构、从数据自动生成列、字段映射与标签、支持的数据类型、各类型运算符、数字/日期的 step 与 format 属性、自定义列配置模式。
  • 数据绑定：使用 JavaScript 数组的本地数据绑定、使用 DataManager 的远程数据绑定、DataSource 赋值模式、预定义查询的 RuleModel 结构、绑定初始规则、动态数据更新与刷新、DataManager 配置。
  • 规则与分组管理：RuleModel 结构（condition、rules、field、operator、value）、创建单条过滤规则、使用 AND/OR 逻辑分组、以编程方式添加和删除规则、添加和删除分组、规则验证与约束、嵌套分组层级。
  • 过滤与搜索操作：创建和删除过滤条件、查询执行方法、自定义过滤条件模式、条件内搜索、ShowButtons 配置（规则删除、分组插入/删除）、基于 UI 和编程方式的过滤、过滤变更事件处理。
  • 模板与自定义：值模板、运算符模板、字段模板自定义、自定义 HTML 模板创建、模板渲染与绑定、CSS 类自定义、动态模板渲染模式。
  • 拖拽与规则交互：规则拖放、组内克隆规则、锁定规则防止修改、分隔符与连接符行为、在组间移动规则、拖放事件处理、视觉反馈与样式。
  • 导入/导出与持久化：将规则导出为 JSON、从 JSON 导入规则、SQL 查询生成、JSON 序列化模式、格式转换（规则转 SQL/JSON）、数据持久化策略、状态管理。
  • 无障碍与 RTL：WCAG 2.1 AA 合规标准、键盘导航模式、ARIA 属性与标签、屏幕阅读器支持、RTL 语言支持、焦点管理与指示器、本地化与国际化。
  • 高级特性与故障排查：全局与本地配置选项、模型绑定模式、高级验证策略、性能优化技巧、事件处理与回调、状态持久化模式、常见问题与故障排查、复杂场景最佳实践。
  • API 参考：完整属性参考（含类型与默认值）、所有公共方法（含参数与返回类型）、所有事件（含事件参数接口）、关键模型接口（RuleModel、ColumnsModel、ShowButtonsModel、ValueModel、TemplateColumn、Validation）、事件参数接口（ActionEventArgs、ChangeEventArgs、RuleChangeEventArgs、DragEventArgs、DropEventArgs）、SQL/查询输出接口（ParameterizedSql、ParameterizedNamedSql）、初始化、SQL 导出、规则管理、克隆/锁定、拖放的使用示例。

快速上手示例

import { QueryBuilder, ColumnsModel, RuleModel } from '@syncfusion/ej2-querybuilder';

// 定义数据
const employeeData = [
  {
    EmployeeID: 1,
    FirstName: 'Nancy',
    Title: 'Sales Representative',
    HireDate: '22/07/2001',
    City: 'Seattle',
    Country: 'USA'
  },
  {
    EmployeeID: 2,
    FirstName: 'Andrew',
    Title: 'Vice President',
    HireDate: '21/04/2003',
    City: 'Tacoma',
    Country: 'USA'
  }
];

// 定义与数据匹配的列
const columnData: ColumnsModel[] = [
  { field: 'EmployeeID', label: 'Employee ID', type: 'number' },
  { field: 'FirstName', label: 'First Name', type: 'string' },
  { field: 'Title', label: 'Title', type: 'string' },
  { field: 'HireDate', label: 'Hire Date', type: 'date', format: 'dd/MM/yyyy' },
  { field: 'City', label: 'City', type: 'string' },
  { field: 'Country', label: 'Country', type: 'string' }
];

// 可选：定义初始规则
const initialRules: RuleModel = {
  condition: 'and',
  rules: [
    {
      label: 'Employee ID',
      field: 'EmployeeID',
      type: 'number',
      operator: 'equal',
      value: 1
    },
    {
      label: 'Title',
      field: 'Title',
      type: 'string',
      operator: 'startswith',
      value: 'Sales'
    }
  ]
};

// 创建 QueryBuilder 实例
const queryBuilder = new QueryBuilder({
  width: '100%',
  dataSource: employeeData,
  columns: columnData,
  rule: initialRules
});

// 渲染到 DOM
queryBuilder.appendTo('#querybuilder');

常见模式

模式 1：单规则基本过滤

const rule: RuleModel = {
  condition: 'and',
  rules: [{
    field: 'FirstName',
    type: 'string',
    operator: 'startswith',
    value: 'A'
  }]
};

模式 2：使用分组的 AND/OR 逻辑

const rule: RuleModel = {
  condition: 'and',
  rules: [
    { field: 'City', operator: 'equal', value: 'Seattle' },
    {
      condition: 'or',
      rules: [
        { field: 'Title', operator: 'contains', value: 'Sales' },
        { field: 'Title', operator: 'contains', value: 'Manager' }
      ]
    }
  ]
};

模式 3：动态添加规则

const newRule = [{
  field: 'Country',
  operator: 'equal',
  value: 'USA'
}];
queryBuilder.addRules(newRule, 'group0');

模式 4：导出为 JSON 以便存储

const rules = queryBuilder.getRules();
const jsonQuery = JSON.stringify(rules);
// 存储到数据库或本地存储

关键概念

  • RuleModel：表示单个过滤条件，包含 field、operator 和 value。
  • Condition：用于组合多条规则的逻辑运算符（AND/OR）。
  • GroupModel：带有 AND/OR 条件的规则容器。
  • Operators：比较方法（equal、contains、between 等）。
  • Data Types：支持的列类型（string、number、date、boolean）。
  • Templates：用于字段、运算符和值的自定义 UI 元素。
  • State：规则和分组的当前配置。

适用场景

  • 高级搜索过滤：让用户为数据搜索构建复杂查询。
  • 报表生成：为报表参数创建动态过滤器。
  • 数据导出：在导出前通过可视化 UI 过滤数据。
  • 日志分析：构建复杂查询以分析系统日志。
  • 客户细分：基于多个条件筛选客户。
  • 权限规则：定义具有复杂条件的访问规则。
  • 通知规则：创建动态告警条件。
  • ETL 工作流：在转换前过滤源数据。

限制

资料中未提供关于收费、价格、平台限制或具体性能指标的信息，暂未提供。