React Router 6.15 中实现页面跳转时自动滚动到顶部的完整方案-js教程-PHP中文网

React Router 6.15 中实现页面跳转时自动滚动到顶部的完整方案

在 React Router 6.15 中，ScrollRestoration 组件可原生支持导航时滚动至顶部及历史回退时恢复滚动位置；若需更精细控制，也可通过自定义 useScrollToTop Hook 或布局级组件实现。

在 react router 6.15 中，`scrollrestoration` 组件可原生支持导航时滚动至顶部及历史回退时恢复滚动位置；若需更精细控制，也可通过自定义 `usescrolltotop` hook 或布局级组件实现。

React Router v6.15 已内置完善的滚动行为管理能力，无需手动封装 ScrollToTop 组件即可实现「新页面滚动到顶 + 返回时恢复原位置」的用户体验。核心方案有两种：推荐使用官方 ScrollRestoration，或按需定制逻辑。

✅ 推荐方案：使用（数据路由专属）

ScrollRestoration 是 React Router 官方提供的声明式滚动管理组件，仅适用于数据路由器（如 createBrowserRouter），且必须在路由上下文中渲染（即位于 RouterProvider 内部）。它会：

在 新导航（push）时自动滚动到页面顶部（window.scrollTo(0, 0)）；
在 浏览器后退/前进（pop）时自动恢复上一次该路由的滚动位置（基于 history.state）。

只需在根布局组件（如 Layout）中渲染一次即可，位置建议紧邻前或后：

// components/Layout.tsx
import { Outlet, ScrollRestoration } from 'react-router-dom';

export default function Layout() {
  return (
    <div classname="app-layout">
      <header>My App</header><main>
        {/* ScrollRestoration 必须在此处渲染 */}
        <scrollrestoration></scrollrestoration><outlet></outlet></main><footer>© 2024</footer>
</div>
  );
}

⚠️ 注意事项：

react-best-practices

重要：对 React 或 Next.js 代码的任何更改必须先阅读本技能。Vercel 工程团队的 React 与 Next.js 指南，涵盖可视化...

下载

ScrollRestoration 不能放在 createRoutesFromElements 的 JSX 路由定义中（如内直接写），因为它不是路由元素，而是 UI 组件；
它依赖浏览器 history.scrollRestoration = 'manual' 的底层机制，因此需确保未被其他脚本覆盖；
若需自定义滚动行为（如仅滚动容器而非整个页面），可配合 getKey 属性实现（见官方文档）。

? 替代方案：手动控制滚动（适用于特殊场景）

当 ScrollRestoration 不满足需求（例如：强制所有导航都滚动到顶，忽略历史恢复；或需滚动至特定元素），可采用以下任一方式：

方式 1：自定义 Hook（推荐用于逻辑复用）

// hooks/useScrollToTop.ts
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export function useScrollToTop() {
  const { pathname } = useLocation();

  useEffect(() => {
    window.scrollTo({ top: 0, left: 0, behavior: 'smooth' });
  }, [pathname]);
}

在布局组件中调用：

// components/Layout.tsx
import { Outlet } from 'react-router-dom';
import { useScrollToTop } from '../hooks/useScrollToTop';

export default function Layout() {
  useScrollToTop(); // 每次 pathname 变化时触发

  return (
    <div>
      <nav>...</nav><outlet></outlet>
</div>
  );
}

方式 2：独立布局路由组件（适合嵌套滚动控制）

// layouts/ScrollToTopLayout.tsx
import { useEffect, type ReactNode } from 'react';
import { Outlet, useLocation } from 'react-router-dom';

export default function ScrollToTopLayout({ children }: { children?: ReactNode }) {
  const { pathname } = useLocation();

  useEffect(() => {
    window.scrollTo(0, 0);
  }, [pathname]);

  return {children ?? <outlet></outlet>}>;
}

并在路由配置中包裹：

// App.tsx
import { createBrowserRouter, createRoutesFromElements, Route, RouterProvider } from 'react-router-dom';
import Layout from './components/Layout';
import Home from './pages/Home';
// ... 其他页面

const router = createBrowserRouter(
  createRoutesFromElements(
    <route element="{<ScrollToTopLayout"></route>}>
      <route path="/" element="{<Layout"></route>}>
        <route index element="{<Home"></route>} />
        <route path="day1" element="{<Day1"></route>} />
        <route path="day2" element="{<Day2"></route>} />
        <route path="day3" element="{<Day3"></route>} />
        <route path="dayC" element="{<DayC"></route>} />
      
    
  )
);

export default function App() {
  return <routerprovider router="{router}"></routerprovider>;
}

? 总结与选型建议

方案	适用场景	是否恢复历史滚动	是否需额外配置	推荐指数
	标准 SPA 导航体验（含前进/后退）	✅ 是	❌ 否（开箱即用）	⭐⭐⭐⭐⭐
useScrollToTop Hook	简单“始终滚顶”，逻辑需复用	❌ 否	❌ 否	⭐⭐⭐⭐
布局组件（ScrollToTopLayout）	需多层嵌套路由统一控制	❌ 否	❌ 否	⭐⭐⭐