Query Builder

@aiao/rxdb-query-builder 是一个可视化查询条件构建器，支持 Angular、React 和 Vue 三端。用户通过拖拽和表单操作构建复杂的数据库查询条件，无需手写查询语法。

架构

@aiao/rxdb-query-builder          ← 核心库（框架无关）
├── QueryBuilderService            ← BehaviorSubject 驱动的状态管理
├── SchemaParser                   ← 从 EntityMetadata 解析字段
├── OperatorRegistry               ← 操作符注册与管理
├── ValidationService              ← 规则校验
└── QueryConverter                 ← RxDB ↔ QB 查询格式转换

@aiao/rxdb-query-builder-angular  ← Angular 组件（Signal-based）
@aiao/rxdb-query-builder-react    ← React 组件 + Hook
@aiao/rxdb-query-builder-vue      ← Vue 组件 + Composable

安装

npm

# 核心库 + 框架包
npm install @aiao/rxdb-query-builder

# Angular
npm install @aiao/rxdb-query-builder-angular

# React
npm install @aiao/rxdb-query-builder-react

# Vue
npm install @aiao/rxdb-query-builder-vue

Yarn

# 核心库 + 框架包
yarn add @aiao/rxdb-query-builder

# Angular
yarn add @aiao/rxdb-query-builder-angular

# React
yarn add @aiao/rxdb-query-builder-react

# Vue
yarn add @aiao/rxdb-query-builder-vue

pnpm

# 核心库 + 框架包
pnpm add @aiao/rxdb-query-builder

# Angular
pnpm add @aiao/rxdb-query-builder-angular

# React
pnpm add @aiao/rxdb-query-builder-react

# Vue
pnpm add @aiao/rxdb-query-builder-vue

Bun

# 核心库 + 框架包
bun add @aiao/rxdb-query-builder

# Angular
bun add @aiao/rxdb-query-builder-angular

# React
bun add @aiao/rxdb-query-builder-react

# Vue
bun add @aiao/rxdb-query-builder-vue

核心概念

数据模型

查询条件由规则 (Rule) 和规则组 (RuleGroup) 组成，支持任意嵌套：

// 规则：单个查询条件
interface QueryBuilderRule<T> {
  id: string;
  field: keyof T & string;
  operator: string; // '=', '!=', 'contains', 'between' 等
  value: unknown;
}

// 规则组：用 AND/OR 组合多个规则
interface QueryBuilderRuleGroup<T> {
  id: string;
  combinator: 'and' | 'or';
  rules: Array<QueryBuilderRule<T> | QueryBuilderRuleGroup<T>>;
}

字段元数据

interface FieldMetadata {
  name: string; // 字段路径，如 'name', 'orders.amount'
  displayName: string; // 显示名称
  type: PropertyType; // 'string' | 'number' | 'boolean' | 'date' | 'relation' | ...
  required?: boolean;
  nullable?: boolean;
  enum?: unknown[]; // 枚举值列表
  isRelation?: boolean;
  relationTarget?: string;
  relationKind?: '1:1' | '1:m' | 'm:1' | 'm:n';
  relationFields?: FieldMetadata[]; // 关联实体的字段
}

默认操作符

操作符	标签	值类型	适用字段类型
= / !=	等于/不等于	单值	string, number, boolean, date
< / > / <= / >=	比较	单值	number, date, string
contains / notContains	包含/不包含	单值	string, array
startsWith / endsWith	开头/结尾	单值	string
in / notIn	在列表中	数组	string, number
between / notBetween	范围内	范围	number, date
null / notNull	为空/不为空	无	可空字段
exists / notExists	存在/不存在	子查询	关系字段

QueryBuilderService

核心状态管理服务，框架无关：

import { createQueryBuilderService, type FieldMetadata } from '@aiao/rxdb-query-builder';

const fields: FieldMetadata[] = [
  { name: 'name', displayName: '姓名', type: 'string' },
  { name: 'age', displayName: '年龄', type: 'number' },
  { name: 'active', displayName: '激活', type: 'boolean' }
];

const service = createQueryBuilderService<User>({
  fields,
  config: { maxNestingLevel: 3 }
});

// 操作
service.addRule(undefined, { field: 'name', operator: '=', value: '张三' });
service.addGroup(rootGroupId, 'or');
service.updateRule(ruleId, { value: '李四' });
service.remove(ruleId);
service.clear();

// 订阅状态
service.rootGroup$.subscribe(group => console.log('查询:', group));
service.validation$.subscribe(result => console.log('校验:', result));

// 导出/导入
const query = service.toRxDBQuery();
service.fromRxDBQuery(existingQuery);

配置选项

interface QueryBuilderConfig<T> {
  maxNestingLevel?: number; // 最大嵌套层级，默认 5
  enableHistory?: boolean; // 启用撤销/重做
  maxHistoryLength?: number; // 历史记录上限，默认 50
  customOperators?: OperatorDefinition[];
  readonly?: boolean;
}

从 Entity 解析 Schema

通过 createSchemaFromEntity 自动从 RxDB 实体元数据生成字段列表：

import { createSchemaFromEntity } from '@aiao/rxdb-query-builder';
import { getEntityMetadata } from '@aiao/rxdb';

const metadata = getEntityMetadata(Todo);
const fields = createSchemaFromEntity(metadata, {
  includeForeignKeys: false, // 默认排除外键
  includeRelations: true // 包含关系字段
});

解析选项

interface SchemaParserOptions {
  includeForeignKeys?: boolean; // 是否包含外键字段
  includeComputedProperties?: boolean; // 是否包含计算属性
  includeRelations?: boolean; // 是否包含关系字段
  fieldFilter?: (field: FieldMetadata) => boolean; // 自定义过滤
  displayNameGenerator?: (name: string) => string; // 自定义显示名称
}

自定义操作符

import { createOperatorRegistry, type OperatorDefinition } from '@aiao/rxdb-query-builder';

const registry = createOperatorRegistry({ useDefaultOperators: true });

// 注册自定义操作符
registry.register({
  key: 'fuzzy',
  label: '模糊匹配',
  valueType: 'single',
  applicableTypes: ['string']
});

// 在服务中使用
const service = createQueryBuilderService<User>({
  fields,
  operatorRegistry: registry
});

跨框架 API 对比

功能	Angular	React	Vue
主组件	<rxdb-query-builder>	<QueryBuilder>	<QueryBuilder>
状态管理	组件内置 Signal	useQueryBuilder hook	useQueryBuilder composable
字段输入	[fields] input	fields prop	fields option
查询输出	(queryChange) output	onQueryChange callback	onQueryChange callback
响应式	Angular Signal	React State	Vue Ref/ShallowRef

详细用法见框架文档：

• Angular
• React
• Vue