Gatsby 滚动位置恢复Scroll Restoration完全指南用 useScrollRestoration 管理自定义滚动容器【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby滚动位置恢复Scroll Restoration是 Gatsby 构建 SPA 时保证用户体验的重要机制当用户在页面间前进、后退时浏览器与框架需要把页面以及页面内可滚动容器的滚动位置恢复到离开时的状态。本文围绕 Gatsby 官方路由指南中的 scroll-restoration.md 展开结合gatsby-react-router-scroll包的源码实现讲解 Gatsby 默认的窗口滚动恢复行为、useScrollRestorationHook 的使用方法、其底层存储原理Session Storage 键值格式以及如何用shouldUpdateScroll自定义滚动行为。读完本文你将能在自己的 Gatsby 站点中为任意内部滚动容器实现精确的滚动位置记忆与恢复。什么是滚动位置恢复滚动位置恢复Scroll Restoration指 History API 上的scrollRestoration属性。该属性允许浏览器在用户导航到新页面时恢复其滚动位置——例如用户向下滚动到长文章的中段后点击链接跳走再按后退键返回时浏览器应把页面滚回离开时的位置而不是回到顶部。Gatsby 在绝大多数场景下会自动处理滚动恢复在 scroll-handler.tsx 中ScrollHandler组件会在挂载时监听全局scroll事件把window.scrollY写入内部存储_saveScroll并在位置变化componentDidUpdate或重新挂载时恢复若 URL 中存在 hash则优先滚动到对应锚点scrollToHash调用node.scrollIntoView()否则恢复上一次保存的窗口滚动位置windowScroll调用window.scrollTo(0, position)。然而当你渲染了自带滚动值的容器overflow: auto/scroll的元素时这些容器内部的滚动位置通常会在页面切换之间丢失——因为框架默认只跟踪窗口本身的滚动。此时就需要使用useScrollRestorationHook把「需要被跟踪并恢复的滚动容器」显式告知 Gatsby。useScrollRestoration Hook 的基本用法useScrollRestoration从gatsby包中导出它实际由gatsby-react-router-scroll包实现见 index.ts 中的export { useScrollRestoration }。下面是一个官方文档中的完整示例用useScrollRestoration渲染一个带overflow滚动行为的国家列表ul元素import { useScrollRestoration } from gatsby import countryList from ../utils/country-list export default function PageComponent() { const ulScrollRestoration useScrollRestoration(page-component-ul-list) return ( ul style{{ height: 200, overflow: auto }} {...ulScrollRestoration} {countryList.map(country ( li{country}/li ))} /ul ) }用法要点useScrollRestoration(identifier)接收一个字符串标识符上例为page-component-ul-list它用于唯一标识该滚动容器Hook 返回一个包含ref与onScroll两个属性的对象直接展开spread到目标元素上即可目标元素必须设置有限高度并启用overflowauto/scroll/hidden等才会产生内部滚动值标识符在同一页面内应保持唯一否则多个容器会互相覆盖滚动记录不同页面之间则天然隔离见下文存储键格式。从 use-scroll-restoration.ts 的源码可以看到它的完整工作流export function useScrollRestorationT extends HTMLElement( identifier: string ): IScrollRestorationPropsT { const location useLocation() const state useContext(ScrollContext) const ref useRefT(null) useLayoutEffect((): void { if (ref.current) { const position state.read(location, identifier) ref.current.scrollTo(0, position || 0) } }, [location.key]) return { ref, onScroll(): void { if (ref.current) { state.save(location, identifier, ref.current.scrollTop) } }, } }该实现分两个阶段协作读取恢复在useLayoutEffect中依赖location.key即每次路由位置变化时触发通过ScrollContext中的存储读取该容器此前保存的scrollTop并调用ref.current.scrollTo(0, position || 0)恢复若无记录则回到 0写入保存把返回的onScroll绑定到元素上用户滚动时把当前ref.current.scrollTop写入存储。这里的ScrollContext由 scroll-handler.tsx 中的ScrollContext.Provider提供displayName 为GatsbyScrollContext默认值是SessionStorage实例因此 Hook 与全局滚动恢复共用同一套存储机制。存储原理Session Storage 中的键值格式useScrollRestoration记录的滚动位置保存在**浏览器会话级存储Session Storage**中因此数据仅在当前浏览器会话tab内有效关闭标签页后即清空不同页面之间通过键中的路径名天然隔离——导航到另一页面时目标组件会恢复到该页面上次访问时的滚动位置同一会话内。官方文档描述存储键的形态为scroll/your-page-name/your-key。结合 session-storage.ts 的源码可以给出更精确的实现级格式const STATE_KEY_PREFIX scroll| const GATSBY_ROUTER_SCROLL_STATE ___GATSBY_REACT_ROUTER_SCROLL getStateKey(location: Path, key: string): string { const stateKeyBase ${STATE_KEY_PREFIX}${location.pathname} return key null || typeof key undefined ? stateKeyBase : ${stateKeyBase}|${key} }即实际存储键为scroll|页面路径|标识符scroll|统一前缀标识这是滚动恢复数据页面路径location.pathname实现「每个页面各自记录」的关键|标识符页面内滚动容器的唯一 key。例如在/products/页面使用useScrollRestoration(list)其存储键即为scroll|/products/|list。你可以在 Chrome DevTools 的Application Storage Session Storage面板中查看这些条目——它们记录的就是对应容器的scrollTopy 轴偏移数值。此外源码中的SessionStorage.read/save都带有降级逻辑当sessionStorage不可用如某些隐私模式时会回退到window[___GATSBY_REACT_ROUTER_SCROLL]这个全局内存对象并在非生产环境下输出[gatsby-react-router-scroll] Unable to access sessionStorage...之类的警告保证功能在极端环境下依然可用。更精细的控制shouldUpdateScroll除了自动恢复gatsby-react-router-scroll还暴露了shouldUpdateScroll回调用于自定义「何时执行滚动」的判断逻辑。在 scroll-handler.tsx 中shouldUpdateScroll ( prevRouterProps: LocationContext | undefined, routerProps: LocationContext ): boolean { const { shouldUpdateScroll } this.props if (!shouldUpdateScroll) { return true } // Hack to allow accessing this._stateStorage. return shouldUpdateScroll.call(this, prevRouterProps, routerProps) }若不传shouldUpdateScroll默认总是允许滚动更新返回true若传入函数则在每次恢复前调用返回false可跳过本次滚动恢复——典型场景如「只希望在用户按后退时恢复普通点击跳转时回顶部」「某些页面禁止自动滚动」等。ScrollHandler同时是全局滚动恢复的载体它在componentDidMount时挂载window的scroll监听器并通过requestAnimationFrame节流保存见_isTicking/_latestKnownScrollY逻辑卸载时移除监听componentDidUpdate时根据新位置的hash或已保存位置决定滚动到锚点还是恢复位置。注释中还说明了一个历史背景由于reach/router对浏览器POP前进/后退原生滚动恢复存在 bug因此实现选择始终以 URL 为唯一事实来源——URL 含 hash 就滚动到锚点否则恢复存储位置从而保证前进/后退时滚动行为的一致性。测试验证行为如何被保障gatsby-react-router-scroll包带有完整的单元测试位于tests/use-scroll-restoration.tsx用testing-library/react jsdom 环境验证了上述全部行为测试用例验证的行为stores current scroll position in storage触发元素scroll事件scrollTop123后session.read(location, test)返回 123即滚动位置被正确写入存储scrolls to stored offset on render预先写入 684渲染后元素scrollTop恢复为 684scrolls to 0 on render when session has no entry无存储记录时滚动到 0updates scroll position on location change导航到/another-location后新页面的元素滚动位置为 0不继承上一页面restores scroll position when navigating back滚动到 356 → 导航离开 →history.navigate(-1)返回后元素scrollTop恢复为 356最后一个用例正是文档所述「同一会话内回到某页时滚动位置恢复到上次离开时的状态」的代码级证明也是本文核心机制的完整闭环。若想深入了解该包的背景可阅读 packages/gatsby-react-router-scroll/README.md——它说明本包是从react-router-scroll分叉并改造为兼容reach/router的滚动管理库。实践建议与注意事项优先依赖 Gatsby 的默认行为普通页面窗口级滚动Gatsby 已自动处理无需额外代码只为真正需要的容器使用 Hook无内部滚动内容不溢出的元素不需要useScrollRestoration过度使用反而增加 Session Storage 写入标识符命名约定使用语义化且与组件/页面关联的名称如page-component-ul-list确保同一页面内唯一便于在 DevTools 中排查理解会话边界滚动位置仅保存在 Session Storage 中跨会话关闭标签页不保留这是设计预期而非缺陷需要精细控制时结合shouldUpdateScroll实现「仅后退时恢复」「忽略 hash 变化」等自定义策略版本兼容当前仓库中useScrollRestoration由gatsby-react-router-scroll实现并通过gatsby包对外导出使用时直接从gatsby导入即可无需单独安装该内部包。掌握滚动位置恢复机制能显著提升长页面、无限列表、分页目录等场景下站点的可用性——而useScrollRestoration正是 Gatsby 为这类「页面内滚动容器」提供的官方解决方案配合 Session Storage 的按页隔离存储让每次返回都精准落回用户离开的位置。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考