跳到主要内容

查询构建器

查询构建器属于 @aiao/rxdb-model 体系，不是单独发布的 @aiao/rxdb-query-builder* 包。

实际包结构如下：

@aiao/rxdb-model           ← 核心模型、服务、schema 工具
@aiao/rxdb-model-angular   ← Angular 组件
@aiao/rxdb-model-react     ← React 组件 + Hook
@aiao/rxdb-model-vue       ← Vue 组件 + Composable

架构​

@aiao/rxdb-model
├── QueryBuilderService  ← 查询构建状态管理
├── SchemaParser         ← 从 EntityMetadata 解析字段
├── OperatorRegistry     ← 操作符注册与筛选
├── Validation           ← 规则合法性校验
└── Query Conversion     ← RxDB RuleGroup 与 UI 状态互转

@aiao/rxdb-model-angular  ← Angular Signal 组件
@aiao/rxdb-model-react    ← React 组件 + Hook
@aiao/rxdb-model-vue      ← Vue 组件 + Composable

安装​

# 核心工具
npm install @aiao/rxdb-model

# Angular
npm install @aiao/rxdb-model-angular

# React
npm install @aiao/rxdb-model-react

# Vue
npm install @aiao/rxdb-model-vue

核心概念​

查询模型​

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

import type { QueryBuilderRuleGroup } from '@aiao/rxdb-model';

const query: QueryBuilderRuleGroup<User> = {
  id: 'root',
  combinator: 'and',
  rules: []
};

这里先记住三件事：

  • QueryBuilderRule<T> 是带 id 的单条规则
  • QueryBuilderRuleGroup<T> 是带 id 的规则组
  • toRxDBQuery() 导出的是标准 RuleGroup<T>，可以直接交给仓库查询 API 使用

字段元数据​

import type { FieldMetadata } from '@aiao/rxdb-model';

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

字段元数据既可以手写，也可以从实体元数据自动生成。

QueryBuilderService​

这是框架无关的核心状态管理服务：

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

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(service.getState().rootGroup.id);

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

const query = service.toRxDBQuery();
service.fromRxDBQuery(query);

核心能力​

  • addRule(parentId, rule)：添加规则
  • addGroup(parentId)：添加分组
  • updateRule(id, updates)：更新规则
  • remove(id)：删除规则或分组
  • moveItem(itemId, targetGroupId, targetIndex)：拖拽排序
  • toRxDBQuery() / fromRxDBQuery(query)：导出与加载查询

配置选项​

interface QueryBuilderConfig {
  maxNestingLevel?: number;
  enableHistory?: boolean;
  maxHistoryLength?: number;
  readonly?: boolean;
}

从 Entity 解析 Schema​

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

import { createSchemaFromEntity } from '@aiao/rxdb-model';
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-model';

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

registry.register({
  key: 'fuzzy',
  label: '模糊匹配',
  valueType: 'single',
  applicableTypes: ['string']
} as OperatorDefinition);

跨框架 API 对比​

功能AngularReactVue
主组件<rxdb-query-builder><QueryBuilder><QueryBuilder>
状态管理组件内置 SignaluseQueryBuilder hookuseQueryBuilder composable
字段输入[fields] / [schema]fields / schema propfields / schema prop
查询输出(queryChange) outputonQueryChange callback@query-change 事件
响应式Angular SignalReact StateVue Ref/ShallowRef

详细用法见各框架文档：