Query Builder — React

@aiao/rxdb-query-builder-react 提供了基于 React Hook 的查询构建器，使用 PrimeReact 作为 UI 库。

安装

npm

npm install @aiao/rxdb-query-builder @aiao/rxdb-query-builder-react primereact

Yarn

yarn add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-react primereact

pnpm

pnpm add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-react primereact

Bun

bun add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-react primereact

基础用法

使用组件

import { QueryBuilder } from '@aiao/rxdb-query-builder-react';
import 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' }
];

function SearchPage() {
  return (
    <QueryBuilder<User>
      fields={fields}
      maxDepth={3}
      onQueryChange={query => console.log('查询:', query)}
      onValidationChange={result => console.log('校验:', result)}
    />
  );
}

使用 Hook

import { useQueryBuilder } from '@aiao/rxdb-query-builder-react';

function SearchPage() {
  const {
    rootGroup,
    validation,
    fields,
    hasRules,
    addRule,
    addGroup,
    remove,
    updateRule,
    updateCombinator,
    clear,
    toRxDBQuery
  } = useQueryBuilder<User>({
    fields: [
      { name: 'name', displayName: '姓名', type: 'string' },
      { name: 'age', displayName: '年龄', type: 'number' }
    ],
    maxDepth: 3,
    onQueryChange: query => {
      // 查询条件变更
      fetchData(query);
    }
  });

  const handleAddRule = () => {
    addRule(rootGroup?.id, {
      field: 'name',
      operator: '=',
      value: ''
    });
  };

  return (
    <div>
      <button onClick={handleAddRule}>添加条件</button>
      <button onClick={clear}>清空</button>
      <pre>{JSON.stringify(toRxDBQuery(), null, 2)}</pre>
    </div>
  );
}

Hook API

useQueryBuilder

function useQueryBuilder<T extends object>(options?: UseQueryBuilderOptions<T>): UseQueryBuilderReturn<T>;

Options

属性	类型	默认值	说明
schema	SchemaInfo	—	Schema 信息
fields	FieldMetadata[]	[]	字段列表
initialQuery	QueryBuilderRuleGroup<T>	—	初始查询
maxDepth	number	5	最大嵌套层级
onQueryChange	(query) => void	—	查询变更回调
onValidationChange	(result) => void	—	校验变更回调

返回值

属性	类型	说明
rootGroup	QueryBuilderRuleGroup<T> | undefined	根规则组
validation	ValidationResult | undefined	校验结果
fields	FieldMetadata[]	字段列表
hasRules	boolean	是否有规则
addRule	(parentId, rule) => void	添加规则
addGroup	(parentId) => void	添加分组
remove	(id) => void	删除规则/分组
updateRule	(id, updates) => void	更新规则
updateCombinator	(groupId, combinator) => void	切换 AND/OR
clear	() => void	清空所有规则
toRxDBQuery	() => QueryBuilderRuleGroup<T>	导出查询

useSchemaFromEntity

从 RxDB EntityMetadata 自动解析字段列表：

import { useSchemaFromEntity } from '@aiao/rxdb-query-builder-react';

function SearchPage({ entityMetadata }) {
  const { fields, hasFields } = useSchemaFromEntity(entityMetadata, {
    includeForeignKeys: false,
    includeRelations: true
  });

  if (!hasFields) return <p>加载中...</p>;

  return <QueryBuilder<User> fields={fields} />;
}

选项	类型	默认值	说明
enabled	boolean	true	是否启用解析
includeForeignKeys	boolean	false	包含外键字段
includeRelations	boolean	false	包含关系字段

组件列表

组件	Props	说明
QueryBuilder	QueryBuilderProps<T>	主组件（= Hook Options + className）
QueryGroup	QueryGroupProps<T>	规则组
QueryRule	QueryRuleProps<T>	单条规则
FieldSelector	FieldSelectorProps	字段选择（PrimeReact CascadeSelect）
OperatorSelector	OperatorSelectorProps	操作符选择（PrimeReact Dropdown）
ValueInput	ValueInputProps	值输入（根据类型动态切换）
SubqueryBuilder	SubqueryBuilderProps	子查询（exists/notExists）