React 页面返回时恢复滚动位置的完整解决方案

本文介绍如何在 React Router 应用中实现“返回上一页时精准恢复原始滚动位置”，避免因 scrollToTop() 干扰导致的定位失效，通过 sessionStorage 安全暂存并还原 window.scrollY。

本文介绍如何在 react router 应用中实现“返回上一页时精准恢复原始滚动位置”，避免因 `scrolltotop()` 干扰导致的定位失效，通过 `sessionstorage` 安全暂存并还原 `window.scrolly`。

在单页应用（SPA）中，用户从首页滚动至页面中部点击「View All」跳转到 /records，再点击页头「Back」返回时，浏览器原生 navigate(-1) 通常无法自动恢复历史滚动位置——尤其当目标页面存在强制 scrollTo(0, 0) 逻辑时，问题会加剧。根本原因在于：滚动位置未被显式捕获与传递，且 scrollToTop() 覆盖了真实离开位置。

✅ 正确思路：分离「进入新页」与「返回旧页」的滚动行为

• 进入新页（如 /records）：仍需滚动到顶部（提升可读性），但不干扰历史位置记录；
• 返回旧页（如 HomePage）：应恢复用户离开前的精确 scrollY，而非重置为 0；
• 关键约束：避免在跳转前调用 scrollToTop()，否则 window.scrollY 被清零，无法保存真实位置。

? 实现步骤（精简可靠版）

1. 在触发跳转的组件中保存离开位置

以 LastRecordsCard 为例，在 的 onClick 中主动捕获当前滚动偏移：

export default function LastRecordsCard() {
  const storeScrollPosition = () => {
    sessionStorage.setItem('scrollPosition', String(window.scrollY));
  };

  return (
    <Card className="w-full shadow-lg">
      <CardBody>
        <Typography variant="h5" color="blue-gray" className="mb-4 flex items-center justify-between">
          Last Records
          <Link to="/records" onClick={storeScrollPosition}>
            <Button size="sm" variant="text" className="flex gap-2">
              View All
              <ArrowLongRightIcon strokeWidth={2} className="w-4 h-4" />
            </Button>
          </Link>
        </Typography>
      </CardBody>
    </Card>
  );
}

⚠️ 注意：移除所有 onClick={scrollToTop} 或 useEffect(() => { window.scrollTo(0, 0) }) 类逻辑——它们会覆盖 scrollY 值，导致 sessionStorage 存入 0。

2. 在目标页面（如 HomePage）的根组件中还原位置

在 HomePage 组件内添加副作用，仅在挂载时检查并滚动：

import { useEffect } from 'react';

function HomePage() {
  useEffect(() => {
    const savedPosition = sessionStorage.getItem('scrollPosition');
    if (savedPosition) {
      // 使用平滑滚动提升体验
      window.scrollTo({ top: parseInt(savedPosition, 10), behavior: 'smooth' });
      sessionStorage.removeItem('scrollPosition'); // 清理，避免重复生效
    }
  }, []);

  return (
    <>
      <div className="overflow-hidden">
        <Menu />
        <div className="h-6 bg-green-50"></div>
        <div className="flex justify-center min-h-screen bg-green-50">
          <div className="mt-2">
            <div className="mx-6"><TrendCard /></div>
            <div className="mt-8 mx-6"><LastRecordsCard /></div>
          </div>
        </div>
      </div>
    </>
  );
}

export default HomePage;

3. （可选）统一管理：封装为自定义 Hook

为提升复用性，可提取为 useRestoreScrollPosition：

// hooks/useRestoreScrollPosition.ts
import { useEffect } from 'react';

export function useRestoreScrollPosition() {
  useEffect(() => {
    const position = sessionStorage.getItem('scrollPosition');
    if (position) {
      window.scrollTo({
        top: parseInt(position, 10),
        behavior: 'smooth',
      });
      sessionStorage.removeItem('scrollPosition');
    }
  }, []);
}

// 在 HomePage 中使用：
// useRestoreScrollPosition();

? 关键注意事项

• sessionStorage 是安全选择：数据仅限当前标签页生命周期，关闭页面即清除，无跨会话污染风险；
• 务必移除干扰逻辑：检查项目中所有 window.scrollTo(0, 0) 调用点（尤其是路由变更监听器、Layout 组件等），确保跳转前 scrollY 未被重置；
• 移动端兼容性：window.scrollTo({ behavior: 'smooth' }) 在 Safari 旧版本中可能不支持，生产环境建议降级为 window.scrollTo(0, y)；
• 服务端渲染（SSR）场景：window 对象在服务端不可用，需包裹 typeof window !== 'undefined' 判断，或在 useEffect 中执行（已天然满足）。

✅ 最终效果验证

此方案轻量、稳定、符合 React 生态习惯，无需引入额外库，即可解决 SPA 中长期存在的“返回失焦”痛点。