syncfusion-react-query-builder（syncfusion React query 构建器）

Implementing Syncfusion React Query Builder

A comprehensive guide for implementing and customizing the Syncfusion React Query Builder component. The Query Builder is a powerful UI component for creating and managing complex filter conditions, with support for rule-based queries, multiple data types, SQL generation, and extensive customization options.

Component Overview

The Query Builder component provides a graphical interface for creating and editing complex filter rules. It outputs structured JSON that can be converted to SQL, Mongo queries, or custom predicates for filtering data. Key capabilities include:

• Rule Management: Create, edit, delete, and nest rules and groups
• Multiple Data Types: Support for string, number, date, boolean, and custom types
• Operator Support: 16+ built-in operators (equal, contains, between, in, etc.)
• Query Conversion: Convert to SQL, Mongo, or parameterized queries
• Customization: Custom templates, themes, and styling
• Accessibility: WCAG compliant with keyboard navigation and screen reader support
• Advanced Features: Drag-and-drop, state persistence, cloning, locking

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup
• Basic component initialization
• CSS imports and themes
• Creating your first Query Builder
• Column definition basics
• Running the application

Columns and Operators

📄 Read: references/columns-and-operators.md

• Defining column schema with ColumnsModel
• Auto-generating columns from data sources
• Configuring labels and field mappings
• Supported operators by data type
• Setting step and format properties
• Column validation configuration

Data Binding

📄 Read: references/data-binding.md

• Binding local data arrays
• Remote data with DataManager
• ODataV4Adaptor integration
• Dynamic data updates
• Using DataManager with Query Builder
• Handling data source changes

Rules and Filtering

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

• Understanding rule structure (RuleModel)
• Creating rules programmatically with addRules
• Creating groups with addGroups
• Deleting rules and groups
• Managing nested rule hierarchies
• Drag-and-drop rule management
• Show buttons configuration

Query Conversion

📄 Read: references/query-conversion.md

• Converting rules to SQL with getSqlFromRules
• Generating Mongo queries with getMongoQuery
• Creating parameterized SQL queries
• Named parameter SQL generation
• Converting predicates for DataManager
• Importing rules from SQL queries
• Handling localization in SQL conversion

Templates and Customization

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

• Creating custom header templates
• Custom component injection into templates
• Styling with CSS classes and cssClass property
• Theme Studio integration
• Custom operator definitions
• Handling actionBegin events for customization

Advanced Features

📄 Read: references/advanced-features.md

• Display modes (Horizontal and Vertical layouts)
• Cloning rules and groups with cloneRule/cloneGroup
• Locking rules and groups for read-only access
• Separate connectors for visual distinction
• Restricting group operations
• RTL (Right-to-Left) support
• State persistence with enablePersistence
• Sort direction configuration
• Summary view display
• Accessibility and keyboard navigation

API Reference

📄 Read: references/api-reference.md

• Complete properties list with types and defaults
• All methods with parameters and return types
• Event handlers and event arguments
• Model interfaces (RuleModel, ColumnsModel, ShowButtonsModel)
• Return type definitions and data structures
• Property usage patterns

Quick Start Example

import { ColumnsModel, QueryBuilderComponent, RuleModel } from '@syncfusion/ej2-react-querybuilder';
import React from 'react';

function App() {
  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: 'Country', label: 'Country', type: 'string' }
  ];

  const initialRules: RuleModel = {
    condition: 'and',
    rules: [
      {
        field: 'EmployeeID',
        label: 'Employee ID',
        operator: 'equal',
        type: 'number',
        value: 1001
      }
    ]
  };

  return (
    <QueryBuilderComponent
      width="100%"
      columns={columnData}
      rule={initialRules}
    />
  );
}

export default App;

Common Patterns

Pattern 1: Retrieving Filtered Results as SQL

let qryBldrObj: QueryBuilderComponent;

function generateSQL() {
  const sqlQuery = qryBldrObj.getSqlFromRules();
  console.log('Generated SQL:', sqlQuery);
  // Send to backend for execution
}

Pattern 2: Programmatically Adding Rules

function addFilter() {
  qryBldrObj.addRules([
    {
      field: 'Country',
      label: 'Country',
      operator: 'equal',
      type: 'string',
      value: 'USA'
    }
  ], 'group0');
}

Pattern 3: Converting SQL Back to Rules

function importFilter(sqlString: string) {
  qryBldrObj.setRulesFromSql(sqlString);
}

Pattern 4: Displaying Summary View

<QueryBuilderComponent
  columns={columnData}
  summaryView={true}  // Shows query summary at the bottom
/>

Key Props Cheat Sheet

Common Use Cases

Use Case 1: Advanced Search Filter

Create a filter interface for users to build complex search queries with multiple conditions:

1. Define columns for searchable fields
2. Initialize with empty or default rules
3. Set showButtons to enable rule management
4. Retrieve SQL on form submission
5. Execute query on backend

Read: references/rules-and-filtering.md and references/query-conversion.md

Use Case 2: Data-Driven Dashboard

Build a dashboard where users filter data across multiple columns:

1. Bind DataManager with remote service
2. Configure columns based on data types
3. Enable drag-and-drop for better UX
4. Use getPredicate() to filter DataManager
5. Display filtered results dynamically

Read: references/data-binding.md and references/rules-and-filtering.md

Use Case 3: Query Template System

Allow users to save and load filter templates:

1. Set enablePersistence={true} for automatic state saving
2. Or manually save getRules() to database
3. Load rules with setRules() when needed
4. Display saved templates in a dropdown

Read: references/advanced-features.md

Use Case 4: Report Builder

Create a report filter UI with custom templates:

1. Design custom header template for branding
2. Use custom operators for domain-specific filtering
3. Enable validation with allowValidation
4. Display summaryView for clarity
5. Generate SQL for report execution

Read: references/templates-and-customization.md and references/advanced-features.md

Next Steps

1. Getting Started: Install the package and create your first Query Builder
2. Define Columns: Configure the fields users can filter on
3. Bind Data: Connect to local or remote data sources
4. Build UI: Add rules and groups with drag-and-drop support
5. Generate Queries: Convert rules to SQL or other formats
6. Customize: Apply themes, templates, and accessibility features

Need help? Check the specific reference files above for detailed examples and implementation patterns.