Vue / 系统课时
封装查询表单
封装查询表单
列表页的查询区域往往重复出现,但字段本身又因业务不同而变化。本课把默认条件、草稿状态、重置、展开收起和查询事件封装进查询壳组件,并用插槽保留字段扩展能力,最终让页面只负责接口请求与结果展示。
学习目标
- 能区分查询壳的通用行为与页面字段、接口等业务职责。
- 能实现默认条件、重置、展开收起和查询事件。
- 能在页面中复用查询组件,并正确处理隐藏字段与分页联动。
抽出稳定的查询流程
查询组件应管理一份可编辑草稿:初始化时合并默认值和外部值;用户提交时向外发送快照;重置时恢复默认值;展开状态只控制字段是否可见,不应暗中修改查询条件。具体字段通过默认插槽传入,接口调用继续由页面负责。

实现查询壳组件
下面的 QueryPanel.vue 不预设业务字段,只提供草稿模型和通用按钮。查询模型被限制为可序列化的基础值和字符串数组,提交与重置时通过克隆函数生成独立快照。
<script setup lang="ts">
import { reactive, ref, watch } from 'vue'
type QueryValue = string | number | boolean | string[] | null
type QueryModel = Record<string, QueryValue>
interface Props {
modelValue: QueryModel
defaultValue?: QueryModel
defaultExpanded?: boolean
expandable?: boolean
queryOnReset?: boolean
}
const props = withDefaults(defineProps<Props>(), {
defaultValue: () => ({}),
defaultExpanded: false,
expandable: true,
queryOnReset: true
})
const emit = defineEmits<{
'update:modelValue': [value: QueryModel]
'update:expanded': [value: boolean]
query: [value: QueryModel]
reset: [value: QueryModel]
}>()
function cloneModel(model: QueryModel): QueryModel {
return JSON.parse(JSON.stringify(model)) as QueryModel
}
const expanded = ref(props.defaultExpanded)
// 草稿与父级已确认条件分离,只在查询或重置时同步。
const form = reactive<QueryModel>(
cloneModel({ ...props.defaultValue, ...props.modelValue })
)
// 保留 reactive 对象引用,确保插槽中的字段持续响应。
function replaceForm(next: QueryModel) {
Object.keys(form).forEach((key) => delete form[key])
Object.assign(form, cloneModel(next))
}
watch(
() => props.modelValue,
(value) => replaceForm({ ...props.defaultValue, ...value }),
{ deep: true }
)
function query() {
const snapshot = cloneModel(form)
emit('update:modelValue', snapshot)
emit('query', snapshot)
}
function reset() {
replaceForm(props.defaultValue)
const snapshot = cloneModel(form)
emit('update:modelValue', snapshot)
emit('reset', snapshot)
// 是否自动重新查询由显式参数控制,避免重置行为含糊。
if (props.queryOnReset) emit('query', snapshot)
}
function toggleExpanded() {
expanded.value = !expanded.value
emit('update:expanded', expanded.value)
}
</script>
<template>
<form class="query-panel" @submit.prevent="query">
<div class="query-panel__fields">
<slot :model="form" :expanded="expanded" />
</div>
<div class="query-panel__actions">
<button type="submit">查询</button>
<button type="button" @click="reset">重置</button>
<button v-if="expandable" type="button" @click="toggleExpanded">
{{ expanded ? '收起' : '展开' }}
</button>
</div>
</form>
</template>预期结果
组件初始值由 defaultValue 与 modelValue 合并得到。
点击查询会同步 modelValue,并触发 query 事件。
点击重置会恢复 defaultValue,触发 reset;queryOnReset 为 true 时继续触发 query。
展开或收起只改变 expanded,不会删除隐藏字段的值。在列表页接入查询事件
页面通过插槽定义字段,通过 v-model 保存已确认条件,并在 query 事件中重置分页、调用接口。下面是片段示例,依赖上面的 QueryPanel.vue。
<script setup lang="ts">
import { ref } from 'vue'
import QueryPanel from './QueryPanel.vue'
const conditions = ref({
keyword: '',
status: 'all',
owner: ''
})
const page = ref(1)
// 查询条件变化后,列表统一回到第一页再请求数据。
function loadUsers(value: Record<string, unknown>) {
page.value = 1
console.log('query', JSON.stringify(value), 'page', page.value)
}
</script>
<template>
<QueryPanel
v-model="conditions"
:default-value="{ keyword: '', status: 'all', owner: '' }"
@query="loadUsers"
>
<template #default="{ model, expanded }">
<input v-model="model.keyword" placeholder="用户名" />
<select v-model="model.status">
<option value="all">全部状态</option>
<option value="enabled">启用</option>
<option value="disabled">停用</option>
</select>
<input v-if="expanded" v-model="model.owner" placeholder="负责人" />
</template>
</QueryPanel>
</template>预期结果
页面初始显示用户名和状态字段,点击“展开”后显示负责人字段。
输入 alice 并点击“查询”时,控制台输出:
query {"keyword":"alice","status":"all","owner":""} page 1
点击“重置”后恢复三个默认值,并再次按第 1 页查询。处理默认值和隐藏字段
defaultValue 表示“重置后应该回到什么状态”,不是简单的空对象。例如当前组织、固定数据范围等条件可以保留在默认值中。外部 modelValue 用于回填 URL、标签页缓存或已保存条件,两者冲突时应以外部值为准。
收起字段后,本实现会保留其值,因为隐藏不等于失效。若产品要求收起时清空高级条件,应由页面在 update:expanded 事件中明确处理,避免通用组件替业务做不可见的数据修改。
验收与边界
验收时至少覆盖四条路径:初次进入是否应用默认值;修改后查询是否发送快照;重置是否恢复默认值并按约定查询;反复展开收起是否保留字段值。接口加载态、错误提示、权限和结果为空等逻辑仍属于列表页,不应继续塞进查询组件。
示例中的克隆函数依赖 JSON 序列化,因此查询模型只应保存字符串、数字、布尔值、空值和字符串数组。日期可先转换为 ISO 字符串;若项目需要支持更复杂的数据类型,应替换为统一的深拷贝工具,并同步扩展 QueryValue 类型。