当前位置：首页 > news >正文

Vue3 + Element Plus 表格查询规范：条件管理、分页联动 + 避坑，标准化写法｜表单与表格规范篇

news 2026/5/12 11:09:30

【Vue3+Element Plus】中后台表格查询场景：从条件管理、重置逻辑到分页联动，掌握标准化查询交互写法，避开响应式丢失、分页错乱、空值传参等高频坑！

📑 文章目录

一、开篇：表格查询的三个核心问题
二、环境与依赖
三、查询条件：用一个对象统一管理
- 3.1 为什么要用一个对象？
- 3.2 推荐：统一查询对象
四、重置逻辑：只清条件，分页回第一页
- 4.1 常见误区
- 4.2 正确做法：逐字段重置 + 分页归位
五、分页联动：切换页、改每页条数时带条件
- 5.1 要联动什么？
- 5.2 Element Plus 分页写法
六、完整示例：一个可复用的表格查询页面
七、常见踩坑与对应处理
- 7.1 防抖：避免频繁请求
- 7.2 空字符串和 undefined
- 7.3 日期范围格式
- 7.4 重置时表单校验
八、小结
🔍 系列模块导航

同学们好，我是 Eugene（尤金），一名多年中后台前端开发工程师。

（Eugene 发音 /juːˈdʒiːn/，大家怎么顺口怎么叫就好）

很多前端开发者都会遇到一个瓶颈：

代码能跑，但不够规范；功能能实现，但维护起来特别痛苦；一个人写没问题，一到团队协作就各种混乱、踩坑、返工。

想写出干净、优雅、可维护的专业代码，靠的不是天赋，而是体系化的规范 + 真实实战经验。

这一系列《前端规范实战》，我会用大白话 + 真实业务场景，不讲玄学、不堆理论，只分享能直接落地的规范、标准与避坑指南。

帮你从「会写代码」真正升级为「会写优质、可维护、团队级别的代码」。

一、开篇：表格查询的三个核心问题

在实际业务里，表格查询常见有三个问题：

查询条件：条件怎么存、怎么和接口对应、怎么校验
重置：点重置后列表会不会乱、分页要不要清、防抖会不会残留
分页联动：切换页/改每页条数时，要不要带条件、要不要清空页码

下面围绕这三个点，用 Vue3 + Element Plus 给出一套可直接落地的写法。

⬆ 返回目录

二、环境与依赖

示例基于：

Vue 3.x
Element Plus
Vue Router（如用到）
支持async/await的现代浏览器

# 如需从零创建npmcreate vue@latest# 安装 Element Plusnpminstallelement-plus

⬆ 返回目录

三、查询条件：用一个对象统一管理

3.1 为什么要用一个对象？

错误写法示例：

// ❌ 不推荐：分散在多个 ref 里constkeyword=ref('')conststatus=ref('')constdateRange=ref([])constpage=ref(1)constpageSize=ref(10)// 调用接口时要手动拼constfetchList=()=>{api.getList({keyword:keyword.value,status:status.value,startDate:dateRange.value?.[0],endDate:dateRange.value?.[1],page:page.value,pageSize:pageSize.value})}

问题在于：

字段一多，传参容易漏
重置时要一个个清，逻辑分散
后续加字段要改多处

更推荐：用一个对象统一管理查询条件。

⬆ 返回目录

3.2 推荐：统一查询对象

<scriptsetup>import{ref,reactive,computed}from'vue'// 1. 查询条件统一放在一个对象里constqueryForm=reactive({keyword:'',status:'',dateRange:[]// 日期范围，Element Plus DatePicker 常用 []})// 2. 分页单独拆出来，因为重置时只清条件，不清分页配置constpagination=reactive({page:1,pageSize:10})// 3. 根据 queryForm + pagination 生成接口参数constqueryParams=computed(()=>({keyword:queryForm.keyword?.trim()||undefined,status:queryForm.status||undefined,startDate:queryForm.dateRange?.[0]||undefined,endDate:queryForm.dateRange?.[1]||undefined,page:pagination.page,pageSize:pagination.pageSize}))</script>

要点：

queryForm：所有和筛选相关的字段
pagination：分页配置，和业务条件分开
queryParams：把表单+分页转成接口需要的参数，便于统一传给接口

⬆ 返回目录

四、重置逻辑：只清条件，分页回第一页

4.1 常见误区

// ❌ 错误1：重置时不清分页，导致“查不到数据”consthandleReset=()=>{queryForm.keyword=''queryForm.status=''queryForm.dateRange=[]// 忘记把 page 设为 1，用户可能还在第 5 页，结果列表为空}// ❌ 错误2：用 Object.assign 导致响应式丢失consthandleReset=()=>{Object.assign(queryForm,{keyword:'',status:'',dateRange:[]})// 如果 queryForm 是 ref，这样可能无法触发视图更新}// ❌ 错误3：整个替换 queryForm，会打断表单的 v-model 绑定consthandleReset=()=>{queryForm={keyword:'',status:'',dateRange:[]}// 若 queryForm 是 reactive，直接赋值会丢失响应式}

⬆ 返回目录

4.2 正确做法：逐字段重置 + 分页归位

<scriptsetup>// 定义初始值，便于重置时复用constgetInitialQueryForm=()=>({keyword:'',status:'',dateRange:[]})constqueryForm=reactive(getInitialQueryForm())constpagination=reactive({page:1,pageSize:10})consthandleReset=()=>{// 1. 逐个字段还原，保持响应式constinitial=getInitialQueryForm()Object.keys(initial).forEach(key=>{queryForm[key]=initial[key]})// 2. 分页回到第一页pagination.page=1// 3. 立即拉取列表（重置后的第一页）fetchList()}</script>

这样做的效果：

条件被完整重置
分页回到第一页，避免“空列表”
仍然保持reactive的响应式
使用getInitialQueryForm()方便以后增减字段

⬆ 返回目录

五、分页联动：切换页、改每页条数时带条件

5.1 要联动什么？

切换页码、改变pageSize时，都要带上当前查询条件重新请求
改变pageSize时，一般把page置为 1，避免越界

⬆ 返回目录

5.2 Element Plus 分页写法

<template><el-paginationv-model:current-page="pagination.page"v-model:page-size="pagination.pageSize":page-sizes="[10, 20, 50, 100]":total="tableData.total"layout="total, sizes, prev, pager, next, jumper"@current-change="handlePageChange"@size-change="handleSizeChange"/></template><scriptsetup>consthandlePageChange=(page)=>{pagination.page=pagefetchList()}consthandleSizeChange=(size)=>{pagination.pageSize=size pagination.page=1// 每页条数变了，回到第一页fetchList()}</script>

注意：v-model:current-page和v-model:page-size会直接改pagination，handlePageChange/handleSizeChange里只需要再调用fetchList()即可，此时queryParams里已经包含最新条件和分页。

⬆ 返回目录

六、完整示例：一个可复用的表格查询页面

下面是一个可直接复用的单文件示例，覆盖查询、重置、分页联动和防抖。

<template><divclass="table-query-demo"><!-- 1. 查询表单 --><el-form:model="queryForm"inlineclass="query-form"><el-form-itemlabel="关键词"prop="keyword"><el-inputv-model="queryForm.keyword"placeholder="请输入关键词"clearable@keyup.enter="handleSearch"/></el-form-item><el-form-itemlabel="状态"prop="status"><el-selectv-model="queryForm.status"placeholder="请选择状态"clearablestyle="width:120px"><el-optionlabel="全部"value=""/><el-optionlabel="启用"value="1"/><el-optionlabel="禁用"value="0"/></el-select></el-form-item><el-form-itemlabel="日期范围"prop="dateRange"><el-date-pickerv-model="queryForm.dateRange"type="daterange"range-separator="至"start-placeholder="开始日期"end-placeholder="结束日期"value-format="YYYY-MM-DD"/></el-form-item><el-form-item><el-buttontype="primary"@click="handleSearch">查询</el-button><el-button@click="handleReset">重置</el-button></el-form-item></el-form><!-- 2. 表格 --><el-tablev-loading="loading":data="tableData.list"border><el-table-columnprop="id"label="ID"width="80"/><el-table-columnprop="name"label="名称"/><el-table-columnprop="status"label="状态"width="100"><template#default="{ row }">{{ row.status === 1 ? '启用' : '禁用' }}</template></el-table-column><el-table-columnprop="createTime"label="创建时间"width="180"/></el-table><!-- 3. 分页 --><el-paginationv-model:current-page="pagination.page"v-model:page-size="pagination.pageSize":page-sizes="[10, 20, 50, 100]":total="tableData.total"layout="total, sizes, prev, pager, next, jumper"class="pagination"@current-change="handlePageChange"@size-change="handleSizeChange"/></div></template><scriptsetup>import{ref,reactive,computed,onMounted}from'vue'// ========== 1. 查询条件 ==========constgetInitialQueryForm=()=>({keyword:'',status:'',dateRange:[]})constqueryForm=reactive(getInitialQueryForm())// ========== 2. 分页 ==========constpagination=reactive({page:1,pageSize:10})// ========== 3. 接口参数（computed 自动同步） ==========constqueryParams=computed(()=>({keyword:queryForm.keyword?.trim()||undefined,status:queryForm.status||undefined,startDate:queryForm.dateRange?.[0]||undefined,endDate:queryForm.dateRange?.[1]||undefined,page:pagination.page,pageSize:pagination.pageSize}))// ========== 4. 列表数据 ==========constloading=ref(false)consttableData=reactive({list:[],total:0})// ========== 5. 请求列表（模拟接口） ==========constfetchList=async()=>{loading.value=truetry{// 实际项目替换为真实 APIconstres=awaitnewPromise((resolve)=>{setTimeout(()=>{resolve({data:{list:[{id:1,name:'测试数据',status:1,createTime:'2024-01-01'}],total:100}},300)})})tableData.list=res.data.list tableData.total=res.data.total}finally{loading.value=false}}// ========== 6. 查询 ==========consthandleSearch=()=>{pagination.page=1fetchList()}// ========== 7. 重置 ==========consthandleReset=()=>{constinitial=getInitialQueryForm()Object.keys(initial).forEach((key)=>{queryForm[key]=initial[key]})pagination.page=1fetchList()}// ========== 8. 分页切换 ==========consthandlePageChange=()=>{fetchList()}consthandleSizeChange=()=>{pagination.page=1fetchList()}onMounted(()=>{fetchList()})</script><stylescoped>.table-query-demo{padding:20px;}.query-form{margin-bottom:16px;}.pagination{margin-top:16px;justify-content:flex-end;}</style>

你可以直接复制到项目里，把fetchList里的模拟请求换成真实接口即可。

⬆ 返回目录

七、常见踩坑与对应处理

7.1 防抖：避免频繁请求

import{useDebounceFn}from'@vueuse/core'// 对 fetchList 做防抖，300msconstfetchListDebounced=useDebounceFn(fetchList,300)// 关键词输入框变化时用防抖查询consthandleKeywordChange=()=>{pagination.page=1fetchListDebounced()}

注意：查询 / 重置按钮通常不需要防抖，只有“输入框变化即查询”的场景才用。

⬆ 返回目录

7.2 空字符串和 undefined

后端往往希望“没填”时不传该字段，而不是传空字符串：

// ✅ 用 undefined 表示“不传”keyword:queryForm.keyword?.trim()||undefined// ❌ 传空字符串可能影响后端逻辑keyword:queryForm.keyword?.trim()??''

⬆ 返回目录

7.3 日期范围格式

// Element Plus DatePicker value-format="YYYY-MM-DD"// queryForm.dateRange 为 ['2024-01-01', '2024-01-31']startDate:queryForm.dateRange?.[0]endDate:queryForm.dateRange?.[1]

需和后端约定的格式一致（如YYYY-MM-DD或时间戳）。

⬆ 返回目录

7.4 重置时表单校验

若使用了el-form的校验规则：

constformRef=ref()consthandleReset=()=>{formRef.value?.resetFields()pagination.page=1fetchList()}

resetFields()会按prop把对应字段还原为初始值，适合和rules一起使用。

⬆ 返回目录

八、小结

场景	做法
查询条件	用`reactive`对象统一管理，`computed`转成接口参数
重置	逐字段还原 +`pagination.page = 1`+ 重新请求
分页	切换页、改`pageSize`时都带上当前条件请求，改`pageSize`时`page = 1`
防抖	输入即查时用`useDebounceFn`，按钮点击不必防抖
空值	不传的字段用`undefined`，避免传空字符串