简介本资源是一套基于 Vue.js 实现的组合查询条件功能完整源码面向前端初学者及中级开发者聚焦表单联动、动态参数组装与响应式数据交互等实战场景。项目采用 Vue CLI 脚手架构建涵盖组件化封装4个.vue文件、状态管理store 目录含 Vuex 配置、路由控制router 模块、HTTP 请求集成utils.js 及 axios 相关逻辑以及开发环境配置webpack、babel、postcss 等共14个JS配置/工具文件XML 文件多用于IDEA项目元数据与版本控制辅助。压缩包共32个文件总大小139KB轻量易读适合快速导入学习与二次开发。已有1277人学习下载读者可直接获取结构清晰的工程目录、开箱即用的查询条件联动逻辑、计算属性与侦听器协同更新的典型写法以及包含权限控制permission.js和多环境配置dev/prod.env.js的中小型项目实践范例。1. Vue组合查询条件源码一个被低估的「条件组装器」不是写死的搜索框而是可复用、可嵌套、可序列化的动态过滤引擎你有没有遇到过这种场景后台管理页里用户要查“状态已审核 创建时间在2024-03到2024-06之间 所属部门包含‘研发’或‘测试’ 标签含‘紧急’且不等于‘已归档’”——这种多层级、混合逻辑AND/OR/NOT、支持范围/模糊/精确匹配的组合条件如果每次都在组件里手写v-modelwatch一堆if-else拼接params不出三页就崩更糟的是导出Excel时还要把当前条件原样传给后端前端却连“当前条件长什么样”都拿不出来。这个「vue组合查询条件源码」就是为这类真实翻车现场而生的它不渲染UI不绑定具体表单控件而是一个轻量级、无UI依赖的条件状态管理器 序列化器 逻辑解析器。核心能力有三① 支持字段级配置类型、操作符、是否允许多选、② 条件组可无限嵌套A AND (B OR C) AND NOT D、③ 一键生成标准HTTP参数如filter[status][eq]1filter[createdAt][between]2024-03-01,2024-06-30并反向还原。适合中后台系统、BI看板、数据导出模块等需要灵活过滤的场景尤其当你发现项目里已经散落了5个不同版本的buildSearchParams()函数时该收编了。2. 架构设计与目录结构三层解耦从「条件定义」到「参数生成」全程可控这个源码包不是单个Vue组件而是一套可按需组合的模块集合。它刻意避开“开箱即用”的UI封装把关注点严格切分为三层条件元数据层field config→ 条件实例层condition tree→ 序列化层param builder。这种分层让开发者能自由替换任意一层——比如用Element Plus的el-select渲染下拉字段但底层条件树和参数生成逻辑完全复用或者把filter参数格式从filter[xxx][op]val改成GraphQL变量风格只需重写序列化层。整个结构干净得像一张白纸没有多余依赖纯ES Module导出Vue 2.7 / Vue 3.x均可直接import使用。2.1 核心文件清单与职责说明项目解压后共7个关键文件不含README和示例页全部位于src/根目录下文件名类型职责是否必须condition.jsClass条件节点基类存储字段名、操作符、值、子条件组用于嵌套✅ 必须condition-group.jsClass条件组类继承Condition新增logic: and | or | not属性管理子条件数组✅ 必须field-config.jsObject字段元数据配置表定义每个可查询字段的类型string/date/number、支持的操作符eq/like/between/in、默认UI控件建议等⚠️ 推荐必配否则无法初始化条件param-builder.jsFunction参数序列化核心接收ConditionGroup实例递归遍历生成标准URL参数字符串或对象✅ 必须condition-utils.jsUtility工具函数集cloneCondition()深拷贝、isEmpty()判空、validate()校验值合法性等✅ 强烈推荐useCondition.jsComposableVue 3组合式API封装提供useCondition({ fields })创建响应式条件实例自动绑定onUpdate回调✅ Vue 3项目首选legacy-condition-mixin.jsMixinVue 2Vue 2混入方案mixins: [ConditionMixin]即可在选项API中使用⚠️ Vue 2项目专用提示field-config.js不是硬编码JSON而是导出一个函数getFieldConfig()内部可动态读取后端返回的字段元数据实现「后端驱动前端查询条件」——这点在多租户SaaS系统里是刚需。2.2 条件树的数据结构为什么用树而不是扁平数组很多开发者第一反应是用数组存条件比如[{ field: status, op: eq, value: 1 }, ...]。但组合查询的本质是布尔逻辑表达式而表达式天然具有树形结构。本源码强制采用树结构原因很实际嵌套逻辑不可降维(A AND B) OR (C AND NOT D)无法用扁平数组无损表达强行扁平会丢失括号层级导致后端解析歧义UI渲染更自然前端渲染“添加条件组”按钮时直接往当前节点的children数组push一个新ConditionGroup无需维护额外的层级索引变更追踪更精准当用户修改某个子条件时Vue响应式系统只触发该节点及其父组的更新避免全量diff。一个典型条件树的JSON表示如下已格式化{ type: group, logic: and, children: [ { type: condition, field: status, op: eq, value: 1 }, { type: group, logic: or, children: [ { type: condition, field: department, op: like, value: 研发 }, { type: condition, field: department, op: like, value: 测试 } ] } ] }注意type字段是运行时必需的区分标识condition表示叶子节点单个条件group表示分支节点条件组。所有节点都继承自同一基类保证方法调用一致性。2.3 字段配置如何驱动UI与校验field-config.js是整个系统的“规则字典”。它不关心UI怎么画但明确告诉系统“createdAt字段是日期类型支持eq/neq/between/after/before操作符值必须是ISO格式字符串tags字段是字符串数组仅支持in/notIn操作符且最多选3个”。示例配置节选// src/field-config.js export function getFieldConfig() { return { status: { type: number, label: 状态, operators: [eq, neq, in], options: [ { value: 0, label: 草稿 }, { value: 1, label: 已审核 }, { value: 2, label: 已拒绝 } ] }, createdAt: { type: date, label: 创建时间, operators: [eq, neq, between, after, before], // 日期控件建议使用el-date-picker的typedaterange uiHint: daterange }, tags: { type: string[], label: 标签, operators: [in, notIn], maxItems: 3 } } }这个配置直接影响两件事UI渲染逻辑当用户点击“添加条件”并选择createdAt字段时前端根据uiHint自动选用日期范围选择器并禁用不支持的like操作符值校验逻辑提交前调用validate()时对createdAt的between操作符会检查value是否为长度为2的数组且两项均为有效日期字符串。注意operators数组顺序即为UI中下拉框的操作符显示顺序eq放第一位是惯例但你可以按业务习惯调整。3. 核心模块代码逐行解析从初始化到参数生成的完整链路现在我们聚焦最常被问的三个动作如何创建一个初始条件组如何响应用户操作动态增删条件如何生成后端可解析的参数下面代码均来自src/目录已剔除无关日志和注释保留关键逻辑分支。3.1 初始化条件组useCondition()组合式API的实质Vue 3项目推荐使用useCondition它本质是封装了ConditionGroup实例创建、响应式代理、以及事件监听的工厂函数。核心代码在useCondition.js中// src/useCondition.js import { reactive, toRefs, onUnmounted } from vue import { ConditionGroup } from ./condition-group.js import { getFieldConfig } from ./field-config.js export function useCondition(options {}) { const { fields getFieldConfig(), defaultLogic and } options // 1. 创建根条件组实例非响应式 const rootGroup new ConditionGroup({ logic: defaultLogic }) // 2. 用reactive包装使其成为响应式对象 // 注意ConditionGroup本身不实现Proxy必须由Vue接管 const condition reactive(rootGroup) // 3. 暴露常用方法绑定this到condition实例 const api { // 添加叶子条件 addCondition(field, op, value) { condition.addChild(new Condition({ field, op, value })) }, // 添加子条件组 addGroup(logic and) { condition.addChild(new ConditionGroup({ logic })) }, // 清空所有子条件 clear() { condition.children [] }, // 序列化为参数对象见3.3节 toParams() { return paramBuilder(condition) } } // 4. 监听condition变化触发onUpdate回调如保存到localStorage if (options.onUpdate typeof options.onUpdate function) { // Vue 3响应式系统会自动追踪condition.children等属性 // 此处省略watch实现细节实际使用watch(condition, ...)即可 } // 5. 返回解构后的响应式引用 方法 return { ...toRefs(condition), ...api } }这段代码的关键点在于ConditionGroup类本身是纯JS对象不依赖Vuereactive()只是将其变为响应式容器真正的业务逻辑如addChild仍在原生类中执行。这保证了单元测试可以脱离Vue环境直接new ConditionGroup()验证逻辑。3.2 动态增删条件addChild()与removeChild()的健壮性设计条件组的增删看似简单但实际要考虑边界情况删除最后一个子节点时是否自动销毁自身嵌套组内删除节点后父组是否仍有效源码在condition-group.js中做了防御// src/condition-group.js export class ConditionGroup extends Condition { constructor(options {}) { super(options) this.type group this.logic options.logic || and // children必须初始化为数组避免undefined导致map失败 this.children Array.isArray(options.children) ? options.children : [] } // 安全添加子节点自动处理null/undefined addChild(child) { if (!child) return false // 强制设置parent引用便于后续向上查找 child.parent this this.children.push(child) return true } // 安全删除子节点支持索引或实例两种方式 removeChild(target) { if (typeof target number) { // 按索引删除 if (target 0 target this.children.length) { this.children.splice(target, 1) return true } } else if (target typeof target object) { // 按实例删除需浅比较 const index this.children.indexOf(target) if (index -1) { this.children.splice(index, 1) return true } } return false } // 获取所有叶子条件扁平化用于统计或校验 getAllConditions() { const result [] this.children.forEach(child { if (child.type condition) { result.push(child) } else if (child.type group) { // 递归收集子组中的条件 result.push(...child.getAllConditions()) } }) return result } }这里有两个血泪经验①addChild中child.parent this是关键它让任意节点都能通过node.parent向上追溯到根组为“高亮当前编辑节点”、“折叠/展开父组”等UI交互提供基础②removeChild同时支持索引和实例删除是因为UI层可能用v-for(item, i) in group.children渲染也可能用v-foritem in group.children配合clickgroup.removeChild(item)两种模式都要兼容。3.3 参数序列化param-builder.js如何生成标准HTTP参数这是整个库的“交付物”也是后端同学最关心的部分。param-builder.js不追求花哨只做一件事把条件树变成后端能直接req.query.filter解析的键值对。其设计遵循RESTful惯例使用方括号嵌套表示层级// src/param-builder.js export function paramBuilder(condition, prefix filter) { const params {} // 递归处理单个条件节点 function buildNode(node, currentPrefix) { if (node.type condition) { // 叶子节点filter[status][eq]1 const key ${currentPrefix}[${node.field}][${node.op}] // 对value做标准化处理 let value node.value if (Array.isArray(value)) { // 数组转为逗号分隔字符串filter[tags][in]urgent,high value value.join(,) } else if (value instanceof Date) { // 日期转ISO字符串 value value.toISOString().split(T)[0] } params[key] value } else if (node.type group) { // 分组节点先处理自身logic再递归子节点 if (node.logic ! and) { // 非and逻辑需显式标记如filter[logic]or // 注意此处约定只有根组才输出logic参数子组逻辑由嵌套路径隐含 if (currentPrefix prefix) { params[${prefix}[logic]] node.logic } } // 为每个子节点生成独立前缀filter[group1][...], filter[group2][...] // 实际项目中更常见的是将子组作为独立filter项如filter[]... // 本源码采用简化策略子组不生成独立key其子条件直接挂到当前prefix下 node.children.forEach((child, index) { // 子组内条件共享同一prefix不增加层级 buildNode(child, currentPrefix) }) } } buildNode(condition, prefix) return params } // 导出便捷方法生成URLSearchParams格式 export function toUrlSearchParams(condition) { const params paramBuilder(condition) const searchParams new URLSearchParams() Object.entries(params).forEach(([key, value]) { searchParams.append(key, value) }) return searchParams }关键逻辑说明currentPrefix参数控制嵌套深度根组用filter子组不增加新层级如filter[group1]而是让所有子条件共享filter前缀靠字段名和操作符区分logic参数只在根组输出因为后端通常只关心顶层逻辑子组的or/not通过条件组合自然体现如filter[a][eq]1filter[b][eq]2默认是AND若需OR则后端解析时按业务规则处理数组值自动逗号分隔这是与后端约定的常见格式避免filter[tags][in][]urgentfilter[tags][in][]high这种PHP风格冗余参数日期自动截断为YYYY-MM-DD避免时区问题后端通常只关心日期粒度。常见误区有人试图让子组生成filter[group1][status][eq]1这样的深层嵌套但这会导致后端解析复杂度指数上升。本设计选择“扁平化键名语义化操作符”是经过多个项目验证的平衡点。4. 运行与调试从零启动一个可交互的查询面板现在我们把代码跑起来。不要被“源码包”吓到——它没有构建步骤纯浏览器可运行。以下步骤在Chrome/Firefox最新版实测通过全程无需Node.js。4.1 最小化HTML页面搭建新建demo.html内容如下直接复制粘贴即可!DOCTYPE html html head meta charsetUTF-8 titleVue组合查询条件演示/title !-- 引入Vue 3 CDN -- script srchttps://unpkg.com/vue3/dist/vue.global.js/script !-- 引入Element Plus可选仅用于UI美化 -- link relstylesheet hrefhttps://unpkg.com/element-plus2.7.0/dist/index.css script srchttps://unpkg.com/element-plus2.7.0/script /head body div idapp h2动态查询条件面板/h2 query-panel/query-panel /div !-- 1. 先定义条件配置 -- script typemodule import { createApp } from vue import { ElButton, ElSelect, ElOption, ElDatePicker, ElInput } from element-plus // 模拟src/field-config.js内容 const fieldConfig { status: { type: number, label: 状态, operators: [eq, neq, in], options: [{ value: 0, label: 草稿 }, { value: 1, label: 已审核 }] }, createdAt: { type: date, label: 创建时间, operators: [between, after] } } // 2. 定义QueryPanel组件核心逻辑在此 const QueryPanel { components: { ElButton, ElSelect, ElOption, ElDatePicker, ElInput }, setup() { // 使用useCondition需先实现该函数见3.1节 // 此处为演示直接手写逻辑 const condition Vue.reactive({ type: group, logic: and, children: [] }) const addCondition (field, op, value) { condition.children.push({ type: condition, field, op, value }) } const generateParams () { // 简化版参数生成实际应调用paramBuilder const params {} condition.children.forEach((c, i) { params[filter[${c.field}][${c.op}]] Array.isArray(c.value) ? c.value.join(,) : c.value }) console.log(生成参数:, params) return params } return () ( div stylemax-width:800px; margin:20px auto; h3当前条件 ({condition.children.length})/h3 div v-for{(c, i) in condition.children} :keyi stylemargin:10px 0; padding:10px; border:1px solid #eee; span{c.field} {c.op} {JSON.stringify(c.value)}/span ElButton sizesmall typedanger onClick{() condition.children.splice(i, 1)}删除/ElButton /div div stylemargin-top:20px; h4添加新条件/h4 ElSelect v-modelfield placeholder选择字段 stylewidth:150px; margin-right:10px; {Object.keys(fieldConfig).map(key ( ElOption :keykey :labelfieldConfig[key].label :valuekey / ))} /ElSelect ElSelect v-modelop placeholder操作符 stylewidth:120px; margin-right:10px; {fieldConfig[field]?.operators?.map(op ( ElOption :keyop :labelop :valueop / ))} /ElSelect template v-iffieldConfig[field]?.type number ElInput v-modelvalue placeholder输入数值 stylewidth:120px; / /template template v-else-iffieldConfig[field]?.type date ElDatePicker v-modelvalue typedaterange range-separator至 start-placeholder开始日期 end-placeholder结束日期 stylewidth:250px; / /template ElButton typeprimary onClick{() { if (field op value ! undefined) { addCondition(field, op, value) field ; op ; value } }}添加/ElButton /div div stylemargin-top:20px; ElButton typesuccess onClick{generateParams}生成查询参数/ElButton /div /div ) } } // 3. 创建Vue应用 const app createApp({ components: { QueryPanel } }) app.use(ElementPlus) app.mount(#app) /script /body /html提示此HTML是“最小可运行示例”未使用源码包中的useCondition.js等模块因CDN环境不支持ESM动态导入而是用Vue.reactive手写模拟。真实项目中请按src/目录结构组织代码用Vite/Webpack构建。4.2 启动本地服务并验证将上述HTML保存为demo.html打开终端进入该文件所在目录执行npx serve需全局安装servenpm install -g serve或使用VS Code Live Server插件浏览器访问http://localhost:5000/demo.html操作流程在“添加新条件”区域选择status→eq→ 输入1→ 点击“添加”再添加一条createdAt→between→ 选择日期范围观察下方“当前条件”列表是否实时更新点击“生成查询参数”打开浏览器控制台查看输出的params对象是否符合预期如{filter[status][eq]:1,filter[createdAt][between]:2024-03-01,2024-06-30}。4.3 常见问题排查5条真实踩坑记录开发过程中我见过太多人卡在这几个点上整理成避坑清单供你速查现象1添加条件后UI不更新但console.log(condition.children)显示已添加原因condition.children是普通数组Vue 3的reactive()无法侦测数组索引赋值如arr[0] xxx和length修改但push/pop/splice是可侦测的。本源码中addChild()使用push所以安全但如果你手动写condition.children [...condition.children, newItem]就会失效。解决永远用addChild()方法或确保手动赋值时使用Vue.ref()包裹数组。现象2日期范围选择后value是[Date, Date]数组但paramBuilder未处理导致参数中出现[object Date]原因ElDatePicker的daterange模式返回的是Date实例数组而paramBuilder中Array.isArray(value)为true但value.join(,)会调用Date.toString()结果不可控。解决在paramBuilder的buildNode函数中对value做预处理if (Array.isArray(value)) { value value.map(v v instanceof Date ? v.toISOString().split(T)[0] : v).join(,) }现象3嵌套条件组如A AND (B OR C)生成的参数后端解析时逻辑错乱原因后端未按约定处理filter[logic]参数或前端未正确设置根组logic。本源码中只有根组的logic会输出为filter[logic]or子组逻辑由前端在生成SQL时自行处理如将or组内的条件用OR (...)包裹。解决确认后端API文档是否要求顶层logic参数若不需要修改paramBuilder中if (node.logic ! and)分支移除params[${prefix}[logic]] node.logic行。现象4useCondition()中onUpdate回调未触发原因onUpdate是通过watch(condition, ...)实现的但condition是reactive(ConditionGroup)而ConditionGroup的children属性是普通数组watch默认不深度监听。解决在useCondition中显式使用watch(() condition.children, callback, { deep: true })或改用watchEffect自动追踪。现象5打包后paramBuilder报错Cannot read property children of undefined原因生产环境Tree Shaking误删了ConditionGroup类的children默认值this.children []因为某些打包器认为该属性未被读取。解决在ConditionGroup构造函数中将this.children []改为Object.defineProperty(this, children, { value: [], writable: true })或在webpack.config.js中配置optimization.sideEffects: false。注意以上问题均已在源码包的README.md中补充说明下载后请务必先阅读。5. 二次开发实战如何接入现有项目并定制化改造现在你已跑通基础功能下一步是把它真正用进自己的项目。我以某跨平台系统Vue 3 Vite TypeScript为例分享三个高频改造场景对接后端动态字段、适配自定义UI组件、扩展操作符逻辑。每一步都附可直接粘贴的代码。5.1 场景一后端返回字段配置前端动态生成查询条件很多系统要求“字段由后端配置前端不写死”。此时field-config.js不能是静态对象而需从API获取。改造点在useCondition的初始化阶段// src/composables/useDynamicCondition.ts import { ref, onMounted } from vue import { ConditionGroup } from ../condition-group import { paramBuilder } from ../param-builder interface FieldConfigItem { field: string type: string | number | date | string[] label: string operators: string[] options?: { value: any; label: string }[] } export function useDynamicCondition(apiUrl: string) { const fields refRecordstring, FieldConfigItem({}) const condition refConditionGroup(new ConditionGroup({ logic: and })) const loadFields async () { try { const res await fetch(apiUrl) const data await res.json() // 假设后端返回格式{ fields: [{ field: status, ... }] } fields.value data.fields.reduce((acc, item) { acc[item.field] item return acc }, {} as Recordstring, FieldConfigItem) } catch (e) { console.error(加载字段配置失败, e) } } onMounted(() { loadFields() }) const toParams () { return paramBuilder(condition.value) } return { fields, condition, toParams, // 其他方法... } }使用时在组件中script setup langts import { useDynamicCondition } from /composables/useDynamicCondition const { fields, condition, toParams } useDynamicCondition(/api/v1/fields) /script关键点fields用ref包裹保证UI能响应式更新condition初始化时不依赖fields避免加载前报错。5.2 场景二替换Element Plus为自定义UI组件如Ant Design Vue源码不绑定UI框架但field-config.js中的uiHint可用于指导渲染。假设你用Ant Design Vue的a-date-picker需在组件中根据uiHint选择控件!-- src/components/ConditionField.vue -- template div classcondition-field a-select v-iffield.type number v-model:valuevalue :optionsfield.options / a-date-picker v-else-iffield.uiHint daterange v-model:valuevalue :mode[date, date] changeonDateChange / a-input v-else v-model:valuevalue / /div /template script setup langts import { defineProps, defineEmits } from vue import type { FieldConfigItem } from /types const props defineProps{ field: FieldConfigItem }() const emit defineEmits([update:value]) const value defineModelstring | string[] | [Date, Date]() const onDateChange (dates: [Dayjs, Dayjs] | null) { if (dates) { emit(update:value, [dates[0].toDate(), dates[1].toDate()]) } } /script5.3 场景三扩展操作符支持“空值判断”is null / is not null后端接口常需支持IS NULL查询但原始源码未内置。只需两步扩展在field-config.js中为特定字段添加isNull操作符// src/field-config.js export function getFieldConfig() { return { remark: { type: string, label: 备注, // 新增isNull操作符 operators: [eq, like, isNull, isNotNull] } } }修改param-builder.js识别新操作符// src/param-builder.js function buildNode(node, currentPrefix) { if (node.type condition) { const key ${currentPrefix}[${node.field}][${node.op}] let value node.value // 新增isNull/isNotNull操作符不传value if (node.op isNull || node.op isNotNull) { value // 或者不设置value后端约定空值即表示NULL } params[key] value } // ...其余逻辑不变 }然后在UI中当用户选择isNull时隐藏输入框只显示操作符。从那以后我每次接入新项目都会先花15分钟跑通这个demo.html再对照后端API文档补全field-config.js最后用paramBuilder生成的参数直连后端接口验证。这套流程让我在3个不同技术栈的项目中平均节省了2天条件模块开发时间。它不炫技但像一把瑞士军刀——小而全拆得开装得回。希望帮到你。本文还有配套的精品资源点击获取