React / Next.js

React 运营列表的 URL 状态与查询边界

运营列表常同时有关键词、状态、多个日期范围、分页和导出。筛选条件若只保存在组件状态里,刷新页面或分享链接就会丢失;若 URL、表格和请求各存一份,又容易出现筛选条显示 A、接口实际查询 B 的问题。

运营列表常同时有关键词、状态、多个日期范围、分页和导出。筛选条件若只保存在组件状态里,刷新页面或分享链接就会丢失;若 URL、表格和请求各存一份,又容易出现筛选条显示 A、接口实际查询 B 的问题。

让 URL 表达可复现的列表视图

把筛选、页码和每页条数放进 URL 查询参数,并在路由入口用 Schema 解析。非法页码、未知状态或不支持的每页条数应回到明确的默认值。组件读取解析后的结果;用户修改筛选时更新 URL,并将页码重置为 1,避免仍停留在旧条件的末页。

短暂的输入草稿可以留在组件内,例如尚未提交的日期范围。提交后由 URL 成为列表视图的事实来源。这样浏览器前进、后退和复制链接都能还原同一组条件。

查询键要对应实际请求

TanStack Query 的列表键应包含规范化后的筛选和分页参数。关键词首尾空格如果不会改变服务端查询结果,就先归一化,再用于请求和查询键,避免相同列表占用多个缓存条目。翻页时可以暂时保留上一页数据,但界面应清楚标识正在更新,不能把旧页内容当成新页结果。

接口响应仍需验证边界。TypeScript 类型只约束本地代码,不能证明远端返回了预期字段;在请求层解析分页数据和详情数据,可以把契约错误留在明确的错误状态,而不是让表格在渲染时崩溃。

日期筛选先约定语义

“下单时间”是时间点,通常需要把用户选择的本地日期范围转换成带时区意义的起止时间;“出行日期”通常是业务日历日期,直接传 YYYY-MM-DD 更合适。两者不能共用同一个转换函数,否则跨时区用户可能查到错误的一天。

日期区间还要约定上下界是否包含端点。采用“起始时刻包含、次日零点不包含”的半开区间,往往比构造 23:59:59.999 更容易跨数据库精度保持一致;具体格式以服务端接口契约为准。测试应固定时间和时区,覆盖月初、月末、跨年与夏令时附近的情况。

导出沿用同一组筛选条件

导出按钮应使用当前列表的筛选条件,但通常不带分页参数。把“筛选条件转接口参数”的逻辑集中在一个函数中,列表请求附加分页,导出请求省略分页,才能避免“看到的是筛选结果,下载的却是全量数据”。导出期间提供进行中和失败状态;不要因为下载接口返回成功就假定文件内容正确。

验收时先设置多种筛选并翻页,再刷新、复制链接到新标签、后退和导出。逐步核对 URL、界面、请求参数及文件内容是否一致。这条路径比单独测试每个筛选控件更容易发现状态分叉。