React-Query 分页查询中的 Pagination 组件首次点击问题解析

问题现象

在使用 React-Query 进行分页数据获取时，开发者经常会遇到一个典型问题：当配合 NextUI 的 Pagination 组件使用时，首次点击页码按钮时，UI 没有立即响应，但 API 请求已经发出。只有在第二次点击时，页码切换的动画效果才会正常显示。

问题本质

这种现象并非真正的 bug，而是 React-Query 的工作机制与 UI 组件期望行为的差异导致的。当用户首次点击页码时：

1. 页码状态立即更新
2. 触发新的查询请求
3. 在数据加载期间，React-Query 会清除当前数据（除非特别配置）
4. 导致 Pagination 组件失去 total 属性（因为 data 暂时为 undefined）
5. 组件因此无法完成动画过渡

解决方案

React-Query 提供了 placeholderData 选项来优化这种场景。通过设置 placeholderData: keepPreviousData，可以保留前一页的数据直到新数据加载完成：

const { data } = useQuery({ 
  queryKey: ['posts', page], 
  queryFn: () => fetchData(page),
  placeholderData: keepPreviousData
})

深入理解

内存消耗考量

开发者可能会担心保留之前数据会导致内存问题。实际上：

1. React-Query 有自动垃圾回收机制
2. 可以通过 cacheTime 配置控制缓存时间
3. 现代浏览器能轻松处理中等规模的分页数据
4. 对于真正大数据量的应用，可考虑虚拟滚动等技术

替代方案比较

除了 placeholderData，还有其他几种处理方式：

1. Skeleton 加载状态：在数据加载时显示骨架屏
2. 禁用按钮：加载期间禁用分页控件
3. 乐观更新：预测结果并立即更新UI

但 placeholderData 方案提供了最佳的用户体验平衡点。

最佳实践建议

1. 对于分页查询，始终考虑使用 placeholderData
2. 合理设置 staleTime 以避免不必要的重请求
3. 结合 isLoading 和 isFetching 状态增强UI反馈
4. 对于关键操作，考虑添加重试逻辑

通过理解这些机制，开发者可以构建出既流畅又可靠的分页体验。