Vue / 系统课时
表格查询与分页
表格查询与分页
企业表格不是“请求一次列表”这么简单:筛选、排序、分页、勾选和 URL 查询参数会共同改变数据状态。本节把这些状态收敛到一个查询模型中,并处理翻页重置、请求竞态和跨页选择边界。
学习目标
- 用统一查询状态管理筛选、排序、页码与页大小。
- 正确处理筛选后页码重置、URL 同步和重复请求竞态。
- 区分“当前页数据状态”和“用户选择状态”,避免翻页后选择丢失。
让所有查询条件只有一个事实来源
最容易失控的实现是每个控件都直接拼接口参数:搜索框改 keyword,分页组件改 page,表头又单独维护排序字段。久而久之,界面状态、URL 和实际请求参数会出现三份不同的真相。
更稳妥的做法是维护一个 query 对象。筛选、排序和分页只修改它;请求函数只读取它;URL 同步也从它派生。勾选行则属于另一类状态,不应混入查询参数。

封装查询、排序和分页
下面是片段示例,适用于 Vue 3 组合式 API。它依赖后端 /api/orders 返回 { items, total },重点展示查询状态同步和请求竞态处理;把接口地址与返回类型替换为你的真实业务定义即可。
import { reactive, ref, watch } from 'vue'
interface OrderRow {
id: string
customerName: string
amount: number
status: 'pending' | 'paid'
}
interface OrderResponse {
items: OrderRow[]
total: number
}
const query = reactive({
keyword: '',
status: '',
page: 1,
pageSize: 20,
sortBy: 'createdAt',
sortOrder: 'desc' as 'asc' | 'desc',
})
const rows = ref<OrderRow[]>([])
const total = ref(0)
const selectedIds = ref(new Set<string>())
let controller: AbortController | null = null
function buildSearchParams() {
return new URLSearchParams({
keyword: query.keyword,
status: query.status,
page: String(query.page),
pageSize: String(query.pageSize),
sortBy: query.sortBy,
sortOrder: query.sortOrder,
})
}
async function load() {
controller?.abort()
controller = new AbortController()
try {
const params = buildSearchParams()
const response = await fetch(`/api/orders?${params}`, {
signal: controller.signal,
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const data: OrderResponse = await response.json()
rows.value = data.items
total.value = data.total
} catch (error) {
// 被新查询取消属于正常竞态处理,其余错误交给页面错误态展示。
if (!(error instanceof DOMException && error.name === 'AbortError')) {
throw error
}
}
}
function applyFilter(keyword: string, status: string) {
query.keyword = keyword
query.status = status
query.page = 1
void load()
}
function changeSort(sortBy: string, sortOrder: 'asc' | 'desc') {
query.sortBy = sortBy
query.sortOrder = sortOrder
query.page = 1
void load()
}
function changePage(page: number) {
query.page = page
void load()
}
function changePageSize(pageSize: number) {
query.pageSize = pageSize
query.page = 1
void load()
}
function toggleSelection(id: string, checked: boolean) {
const next = new Set(selectedIds.value)
checked ? next.add(id) : next.delete(id)
selectedIds.value = next
}
watch(
query,
() => {
// URL 只同步查询状态,刷新页面后可据此恢复筛选与分页。
history.replaceState(null, '', `?${buildSearchParams()}`)
},
{ deep: true },
)预期结果
筛选、排序或页大小变化:page 自动回到 1,再按最新参数请求数据。
翻页:只改变 page,不清空 selectedIds。
连续触发查询:上一请求会被取消,避免旧响应覆盖新结果。
浏览器地址栏:持续反映 keyword、status、page、pageSize、sortBy、sortOrder。接口实际返回值、请求耗时和 URL 编码结果会随项目数据而变化。
明确哪些操作必须重置页码
筛选条件改变后继续停留在原页码,常会得到“空表格但其实有数据”的假象。例如用户在第 8 页缩小筛选范围,新结果只有 2 页,此时必须回到第 1 页。排序改变通常也应重置到第 1 页,因为记录顺序已经整体改变。
单纯翻页和修改页大小的策略要按产品约定处理。页大小改变时,最简单且可预测的做法同样是回第 1 页;如果业务要求尽量保持当前首条记录,则需要用旧页码与页大小计算新的页码,而不是直接复用旧值。
让 URL、请求和界面保持同步
查询页通常需要支持刷新后恢复条件、复制链接给同事、浏览器前进后退。因此初始化时应从 URLSearchParams 解析允许的字段,并做类型与白名单校验,再写回 query。不要把任意 URL 字符串直接传给后端排序字段。
同步方向也要清楚:控件改变 query,query 触发 URL 更新和数据请求;而浏览器历史导航发生时,再从 URL 恢复 query。如果项目使用 Vue Router,应优先通过 route.query 与 router.replace 完成同步,而不是同时直接操作 history。
把选择状态与当前页解耦
如果勾选状态只保存在当前页的 rows 上,翻页后旧数据被替换,选择自然会丢失。使用 Set<string> 保存业务主键,可以让选择跨页存在,并且不会随着重新请求当前页而重置。
但跨页全选不能简单理解成“把当前所有 ID 都放进 Set”。当数据量很大时,更适合保存“全选当前查询条件”这一语义,再记录少量排除项。筛选条件改变后是否保留旧选择也要由业务明确:若批量操作只针对当前筛选集,就应清空旧选择。无论采用哪种方案,查询状态与选择状态都应分开建模。