gsap-react-router

GSAP React Router

挂载 → 初始状态 → 入场动画 → 稳定状态 → 退场动画 → 最终状态 → 卸载

挂载和卸载由 React 管理；动画负责它们之间的五个阶段。React Router 没有离场钩子：使用阻止器暂缓导航，或在导航开始前拦截导航。参数变化可能会复用路由元素。

保持所需的视觉效果和现有项目约定。仅在需要时添加 GSAP/插件；除非收到要求，否则不要替换选定的动画库。

这项技能决定动画何时运行。若还需要确定动画元素以及高级感、活泼感等风格，并且已安装 animaxxing 技能，也请加载它：其中的方案和寻找风格的指南可以融入此生命周期。

从项目入手

阅读仓库说明、现有动画、布局、导航、CSS、无障碍约定和检查项。然后：

1. 确认使用的是 React Router 7 或更高版本，以及所处模式。框架模式包含 react-router.config.ts、routes.ts、root.tsx，以及 entry.client.tsx 中的 HydratedRouter。数据模式包含 createBrowserRouter 和 RouterProvider。声明式模式包含 BrowserRouter，且没有加载器、useNavigation 或阻止器。Remix 2 应用使用 @remix-run/react 中的相同钩子；请说明这一点并映射名称。
2. 从 node_modules/react-router/package.json 读取已安装的版本。该包会在 dist/ 中附带 docs/、CHANGELOG.md 和 .d.ts 文件；请优先查阅这些文件，不要依赖记忆。版本要求：useBlocker（6.19）、viewTransition 和 useViewTransitionState（6.27）、Link mask 和 useTransitions（7.15）、中间件（7.9 中需启用 future.v8_middleware，在 8 中始终启用）。版本 8 仅支持 ESM，需要 React 19.2，并移除了 react-router-dom：RouterProvider 和 HydratedRouter 来自 react-router/dom。
3. 在框架模式下，检查 react-router.config.ts 中的 ssr 和 prerender。服务端渲染和预渲染的页面会在水合前绘制 HTML。ssr: false 会提供一个仅包含根路由及其 HydrateFallback 的 index.html，因此路由内容会在水合后渲染，无需预绘制规则。未进行服务端渲染的数据模式和声明式模式也是如此。

选择动画引擎

在数据模式/框架模式下，使用带有 viewTransition 的 Link、Form 或 navigate 来实现快照变形或页面交叉淡化。使用 GSAP 来实现控制导航时机的实时 DOM 退场动画、可中断序列、拆分文本或滚动联动动画。每个元素只用一个引擎；参见组合使用多个引擎。

只读你需要的内容

• 看不见的入口、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 阻塞式转场的收尾、可感知转场的链接、锁定、待处理状态、前进和后退、切换间隙、滚动、焦点、View Transitions：React Router 导航。
• 模式及其钩子、路由复用与重新挂载、布局和 <Outlet>、SSR 和 SPA 模式下的首次绘制、流式传输、fetcher、模态路由：路由生命周期。
• 五个阶段、GSAP 设置、React 生命周期、显示和隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• 跨路由使用 Lenis、ScrollSmoother 或缓动页面滚动：平滑滚动，以及 React Router 集成。
• 幕帘、首次访问预加载器和共享元素变形：转场范式，以及 它们在 React Router 下的位置。
• 触控、视口变化和设备预算：设备与输入。
• 宣布工作完成前：验证。

请在此仓库中一并安装 GSAP 官方技能。仅在需要时加载 gsap-core 以了解 API 详情，以及加载 gsap-react 以设置组件。

规则

• 成功设置后保留不可见的开场状态；失败时恢复当前进入页面的所有者。添加隐藏规则前，先遵循初始化约定。
• GSAP 仅在浏览器中运行。框架模式会在服务器上评估路由模块，因此请将 GSAP 调用放在 useGSAP 或 effect 中，并在 .client 副作用模块中注册。请从各自的包导入 gsap 和 useGSAP：SSR 期间 .client 导出为 undefined。限定选择器的作用域。清理每个补间、触发器、分割和监听器。
• 使用普通 CSS 和稳定的包装元素预留最终几何布局；让离开页面和进入页面的内容重叠，而不增加双倍布局空间。
• 先挂载，再设置初始值，然后绘制。服务器 HTML 会在 hydration 前绘制：仅在初始阶段，通过根 Layout 中内联脚本设置的根属性隐藏开场目标，并提供无 JavaScript 的路径。
• 稳定后清除临时样式。仅在动画期间使用 will-change；它会覆盖 gsap-performance 的静态提示。
• 使用能力查询划分设备层级。触摸状态要能释放；控件不能依赖悬停才能使用。
• 在退场动画和结束状态期间，保持离开路由已挂载且可见。路由器会在新路由提交时卸载旧路由，因此需要暂缓提交：使用 useBlocker 和结束回调中的 proceed()，或阻止 Link 的默认行为，并在退场动画后调用 navigate。
• 绝不阻止或对 POP 执行退场动画。返回和前进操作只应用初始状态和开场动画，并且要在滚动位置恢复后执行。
• 使用新参数导航到同一路由时会复用元素。为 outlet 设置 location.pathname 作为 key，或者通过依赖 pathname 再次运行生命周期，并针对已持有稳定值的 DOM 执行。
• Loader 会在 proceed() 后运行，因此结束状态要等待数据。根据用户意图预取，并在进入页面的目标准备就绪前遮盖路由容器。
• Fetcher 不属于导航。不要将 fetcher.state 视为页面过渡。
• 每个元素只能由一个引擎控制。同一节点上的具名视图过渡和 GSAP 补间会相互冲突。
• 保留原生链接行为：修饰键点击、target、reloadDocument、外部 URL、prefetch、NavLink 状态、焦点、滚动和无 JavaScript 时的可读性。
• 减少动画效果时仍要到达相同的稳定状态，并触发每个完成回调，包括调用 proceed() 的回调。
• 明确定义中断和快速点击时的行为；完成时必须恰好释放一次导航等待。
• 条件允许时在真实浏览器中验证。路由、配置、依赖或发布内容变更时，使用生产构建。