syncfusion-angular-query-builder（syncfusion Angular query 构建器）

Implementing Syncfusion Angular Query Builder

The Syncfusion Angular Query Builder (ejs-querybuilder) is a UI component for visually constructing complex filter queries. Users define conditions (field + operator + value) and combine them into groups with AND/OR logic. The resulting rules can be exported to JSON, SQL, or MongoDB formats for use in filtering or API queries.

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installing @syncfusion/ej2-angular-querybuilder
• Setting up CSS/theme imports (Material3)
• Creating a basic Query Builder with columns
• Rendering with an initial rule
• Running the Angular application

Columns Configuration

📄 Read: references/columns.md

• Defining columns with field, label, type
• Auto-generating columns from dataSource
• Configuring operators per column (full operators table)
• Setting step values for number fields
• Formatting date and number values
• Enabling validation (allowValidation, isRequired, min/max)

Data Binding

📄 Read: references/data-binding.md

• Local data binding with JS arrays (JsonAdaptor) — recommended and safe
• Complex/nested data binding with sub-columns
• ⚠️ Remote DataManager (OData, WebApiAdaptor) patterns documented in this reference are not recommended — see Security & Trust Boundary below before use

Filtering & Rules Management

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

• Adding/deleting conditions with addRules / deleteRules
• Adding/deleting groups with addGroups / deleteGroups
• Cloning rules/groups (cloneRule, cloneGroup)
• Locking rules/groups (lockRule, lockGroup)
• Separate connectors between rules (enableSeparateConnector)
• Restricting group nesting depth (maxGroupCount)
• Drag-and-drop rule reordering (allowDragAndDrop)
• Controlling button visibility (showButtons)

Import & Export

📄 Read: references/import-export.md

• Importing from JSON (initial rule property + setRules)
• Importing from SQL (inline, parameterized, named parameterized)
• Importing from MongoDB (setMongoQuery)
• Exporting to JSON (getRules)
• Exporting to SQL (inline, parameterized, named parameterized)
• Exporting to MongoDB (getMongoQuery)

Templates & Model Binding

📄 Read: references/templates.md

• Custom header template with dropdown, split-button, NOT condition
• Column template with create / write / destroy pattern
• Using NgTemplate for column value inputs
• Rule template (ruleTemplate + actionBegin event)
• Model binding for field, operator, value inputs (fieldModel, operatorModel, valueModel)

Style, Appearance & Layout

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

• CSS class customization table
• Theme Studio integration
• Display modes: horizontal (default) vs. vertical (displayMode)
• Summary view (summaryView)
• RTL support (enableRtl)
• State persistence (enablePersistence)

Accessibility & Localization

📄 Read: references/accessibility-and-localization.md

• WCAG 2.2, Section 508, WAI-ARIA compliance
• Keyboard navigation shortcuts
• Localization setup and full locale key reference
• Sort columns display (sortDirection)

API Reference

📄 Read: references/api.md

• Complete Properties reference (40+ properties)
• Complete Methods reference (30+ methods)
• Complete Events reference (7 events)
• Type definitions and interfaces
• Official Syncfusion documentation links

Quick Start Example

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

Install with:

ng add @syncfusion/ej2-angular-querybuilder

Common Patterns

Pattern 1: Export rules to SQL for backend use

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

Pattern 2: Load rules at runtime

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

Pattern 3: Programmatically add a condition

// Add a rule to the root group
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 };

Key Properties

Key Methods

Common Use Cases

• Admin dashboards: Let users build custom data filters without writing SQL
• Report builders: Generate WHERE clause conditions for dynamic reports
• Search interfaces: Visual query construction for complex search forms
• Data export tools: Build MongoDB/SQL filters from a UI, pass to API
• Saved searches: Export rules to JSON, store, and reload with setRules

Security & Trust Boundary

PROHIBITION — Read before implementing any data binding.

What is NOT permitted

Binding [dataSource] to a remote DataManager with an arbitrary or user-supplied URL (OData, OData v4, WebApiAdaptor, or any external HTTP endpoint) is prohibited in this skill. Doing so causes the component to:

• Auto-generate columns and operators directly from untrusted remote schema
• Embed untrusted field names and values into exported SQL/MongoDB queries
• Allow remote-controlled data to alter runtime behavior (predicates, rules, query structure)

This pattern must not be taught, scaffolded, or referenced as a recommended approach.

Required practices