Vue / 系统课时

封装查询表单

封装查询表单

列表页的查询区域往往重复出现,但字段本身又因业务不同而变化。本课把默认条件、草稿状态、重置、展开收起和查询事件封装进查询壳组件,并用插槽保留字段扩展能力,最终让页面只负责接口请求与结果展示。

学习目标

  • 能区分查询壳的通用行为与页面字段、接口等业务职责。
  • 能实现默认条件、重置、展开收起和查询事件。
  • 能在页面中复用查询组件,并正确处理隐藏字段与分页联动。

抽出稳定的查询流程

查询组件应管理一份可编辑草稿:初始化时合并默认值和外部值;用户提交时向外发送快照;重置时恢复默认值;展开状态只控制字段是否可见,不应暗中修改查询条件。具体字段通过默认插槽传入,接口调用继续由页面负责。

查询表单的状态与事件流

实现查询壳组件

下面的 QueryPanel.vue 不预设业务字段,只提供草稿模型和通用按钮。查询模型被限制为可序列化的基础值和字符串数组,提交与重置时通过克隆函数生成独立快照。

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>

预期结果

text
组件初始值由 defaultValue 与 modelValue 合并得到。
点击查询会同步 modelValue,并触发 query 事件。
点击重置会恢复 defaultValue,触发 reset;queryOnReset 为 true 时继续触发 query。
展开或收起只改变 expanded,不会删除隐藏字段的值。

在列表页接入查询事件

页面通过插槽定义字段,通过 v-model 保存已确认条件,并在 query 事件中重置分页、调用接口。下面是片段示例,依赖上面的 QueryPanel.vue。

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>

预期结果

text
页面初始显示用户名和状态字段,点击“展开”后显示负责人字段。
输入 alice 并点击“查询”时,控制台输出:
query {"keyword":"alice","status":"all","owner":""} page 1
点击“重置”后恢复三个默认值,并再次按第 1 页查询。

处理默认值和隐藏字段

defaultValue 表示“重置后应该回到什么状态”,不是简单的空对象。例如当前组织、固定数据范围等条件可以保留在默认值中。外部 modelValue 用于回填 URL、标签页缓存或已保存条件,两者冲突时应以外部值为准。

收起字段后,本实现会保留其值,因为隐藏不等于失效。若产品要求收起时清空高级条件,应由页面在 update:expanded 事件中明确处理,避免通用组件替业务做不可见的数据修改。

验收与边界

验收时至少覆盖四条路径:初次进入是否应用默认值;修改后查询是否发送快照;重置是否恢复默认值并按约定查询;反复展开收起是否保留字段值。接口加载态、错误提示、权限和结果为空等逻辑仍属于列表页,不应继续塞进查询组件。

示例中的克隆函数依赖 JSON 序列化,因此查询模型只应保存字符串、数字、布尔值、空值和字符串数组。日期可先转换为 ISO 字符串;若项目需要支持更复杂的数据类型,应替换为统一的深拷贝工具,并同步扩展 QueryValue 类型。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

封装查询表单

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通