Query Builder — Vue

@aiao/rxdb-query-builder-vue 提供了基于 Vue Composable 的查询构建器，使用 PrimeVue 作为 UI 库。

安装

npm

npm install @aiao/rxdb-query-builder @aiao/rxdb-query-builder-vue primevue

Yarn

yarn add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-vue primevue

pnpm

pnpm add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-vue primevue

Bun

bun add @aiao/rxdb-query-builder @aiao/rxdb-query-builder-vue primevue

基础用法

使用组件

<script setup lang="ts">
import { QueryBuilder } from '@aiao/rxdb-query-builder-vue';
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 onQueryChange(query: any) {
  console.log('查询:', query);
}
</script>

<template>
  <QueryBuilder
    :fields="fields"
    :max-depth="3"
    @query-change="onQueryChange"
    @validation-change="v => console.log('校验:', v)"
  />
</template>

使用 Composable

<script setup lang="ts">
import { useQueryBuilder } from '@aiao/rxdb-query-builder-vue';

const {
  rootGroup,
  validation,
  fields,
  hasRules,
  service,
  addRule,
  addGroup,
  remove,
  updateRule,
  updateCombinator,
  clear,
  loadQuery,
  toRxDBQuery
} = useQueryBuilder<User>({
  fields: [
    { name: 'name', displayName: '姓名', type: 'string' },
    { name: 'age', displayName: '年龄', type: 'number' }
  ],
  maxDepth: 3,
  onQueryChange: query => fetchData(query)
});

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

<template>
  <button @click="handleAddRule">添加条件</button>
  <button @click="clear">清空</button>
  <pre>{{ JSON.stringify(toRxDBQuery(), null, 2) }}</pre>
</template>

Composable 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	ShallowRef<QueryBuilderRuleGroup<T> | undefined>	根规则组
validation	ShallowRef<ValidationResult | undefined>	校验结果
fields	Ref<FieldMetadata[]>	字段列表
hasRules	ComputedRef<boolean>	是否有规则
service	QueryBuilderService<T>	底层服务实例
addRule	(parentId, rule) => void	添加规则
addGroup	(parentId) => void	添加分组
remove	(id) => void	删除规则/分组
updateRule	(id, updates) => void	更新规则
updateCombinator	(groupId, combinator) => void	切换 AND/OR
clear	() => void	清空所有规则
loadQuery	(query | null) => void	加载查询
toRxDBQuery	() => QueryBuilderRuleGroup<T>	导出查询

Vue 特有功能

Vue 版本额外暴露了 service 实例（便于直接操作 Observable）和 loadQuery 方法（比 fromRxDBQuery 更安全，支持 null）。返回值使用 Vue 响应式类型（ShallowRef、Ref、ComputedRef），在模板中通过 .value 访问。

useSchemaFromEntity

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

<script setup lang="ts">
import { useSchemaFromEntity } from '@aiao/rxdb-query-builder-vue';
import { getEntityMetadata } from '@aiao/rxdb';

const metadata = getEntityMetadata(Todo);
const { fields, hasFields } = useSchemaFromEntity(metadata, {
  includeForeignKeys: false,
  includeRelations: true
});
</script>

<template>
  <QueryBuilder v-if="hasFields" :fields="fields" />
  <p v-else>加载中...</p>
</template>

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

组件列表

组件	说明
QueryBuilder	主组件
QueryGroup	规则组（AND/OR）
QueryRule	单条规则
FieldSelector	字段选择（PrimeVue CascadeSelect）
OperatorSelector	操作符选择（PrimeVue Select）
ValueInput	值输入（根据类型动态切换）
SubqueryBuilder	子查询（exists/notExists）