Pinia 分页筛选状态持久化需统一定义结构化 state，精准配置 persist 的 paths 与 key，筛选变更时重置 currentPage，并可选同步路由 query。
Pinia 管理分页列表的查询参数与筛选条件持久化，核心是把 当前页码、每页条数、搜索关键词、状态筛选项、日期范围等组合成可复用的状态对象，并通过持久化插件自动存取 localStorage（或 sessionStorage）。关键不在“存什么”，而在于“什么时候重置”和“哪些字段该存”。
1. 在 Store 中定义结构化的分页与筛选状态
避免零散定义多个 ref，统一用一个 state 对象管理所有相关参数，便于后续持久化控制和逻辑复用：
- currentPage：当前页码，初始为 1
- pageSize：每页条数，常设为 10 / 20 / 50，支持用户切换
- searchKey：订单号、用户名等模糊搜索字段
- status：下拉选择的订单状态（如 'pending' | 'paid' | 'shipped'）
- dateRange：数组格式的起止时间 ['2026-01-01', '2026-10-13']
- 其他业务字段（如渠道、支付方式）按需添加
这样设计后，整个筛选+分页就是一个可序列化的 plain object，天然适配持久化插件。
2. 配置 persist 字段，精准控制持久化范围
不是所有字段都要存——比如临时 loading 状态、接口错误信息就不该进 localStorage。只保留用户真正关心的“视图状态”：
- 启用 persist：设
enabled: true - 指定字段：用
paths明确列出要持久化的 key，例如['currentPage', 'pageSize', 'searchKey', 'status', 'dateRange'] - 自定义 key 名：设
key: 'order-list-filter'，避免和其他 store 冲突，也方便调试 - 存储位置：默认 localStorage；若希望关页即失效（如测试环境），可改用
storage: sessionStorage
示例代码片段：
export const useOrderListStore = defineStore('orderList', {
state: () => ({
currentPage: 1,
pageSize: 20,
searchKey: '',
status: '',
dateRange: [] as string[],
loading: false,
list: [] as OrderItem[],
}),
persist: {
enabled: true,
key: 'order-list-filter',
storage: localStorage,
paths: ['currentPage', 'pageSize', 'searchKey', 'status', 'dateRange']
}
})
3. 关联行为：筛选变更时重置页码，保持语义一致
用户修改任意筛选条件（比如换了个日期范围或点了新状态），当前页码若还停留在第 5 页，很可能查不到数据或漏掉首屏结果。因此必须在 action 中主动重置：
- 提供一个
updateFilters方法，接收新筛选值 - 内部先设
this.currentPage = 1，再触发接口请求 - 不要在组件里手动改 currentPage，全部收口到 store 的 action 中
这样既保证了 UI 行为统一，也让持久化后的状态始终是“有效且自洽”的——下次打开页面时，页码不会卡在无效位置。
4. 与路由解耦，但支持 URL 同步（可选增强）
如果项目要求分享链接时能还原筛选状态（如发给同事一个带参数的 URL），可在 store 初始化后读取路由 query，并反向同步到 state：
- 在 setup 或 onMounted 中调用
store.$patch(route.query)，把 query 转为 store 字段 - 监听 store 变化，用
router.push({ query: store.$state })同步回 URL（注意防循环） - 此时 persist 和 URL 两套机制并存：localStorage 保长期偏好，query 保临时分享
这种混合方案兼顾了用户体验与协作需求，也不影响基础持久化逻辑。
