gsap-tanstack-router

GSAP TanStack Router

挂载 → 初始状态 → 入场 → 稳定 → 退场 → 结束状态 → 卸载

挂载和卸载由 React 负责；动画负责其间的五个阶段。TanStack Router 会保留共享布局，并可在参数变化时复用路由；待处理 UI 和加载器也会影响新页面出现的时机。

保持用户要求的外观和现有项目惯例。仅在需要时添加 GSAP/插件；除非用户要求，否则不要替换选定的动画库。

此技能决定动画何时运行。至于哪些元素会动，以及如何营造高级感或俏皮感等氛围，如果已安装 animaxxing 技能，也请加载它：其中的配方和氛围探索指南可与此生命周期配合使用。

从项目入手

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

1. 确认项目使用 @tanstack/react-router。Next.js 对应 gsap-nextjs，React Router 对应 gsap-react-router，不带路由器的 React 对应 gsap-react。Solid Router 不在适用范围内。
2. 查看已安装的 @tanstack/react-router 版本，以及（如有）@tanstack/react-start 版本。优先参考它们自带的类型定义，而非依赖记忆：node_modules/@tanstack/router-core/dist/esm/router.d.ts 中的 RouterOptions、RouterState 和 RouterEvents，node_modules/@tanstack/react-router/dist/esm/useBlocker.d.ts 中的拦截器，以及 node_modules/@tanstack/history/dist/esm/index.d.ts 中的历史记录操作。TanStack/router 仓库的 docs/router/ 和 docs/start/ 是权威资料。加载架构在 1.16x 和 1.17x 版本系列期间发生了变化；在 router-core 1.171.2x 中，RouterState.isTransitioning 已被移除，useBlocker 仍标记为实验性功能。
3. 区分基于文件的路由（createFileRoute、routeTree.gen.ts、__root.tsx）和基于代码的路由（createRoute、createRootRoute）。生命周期相同；不同之处仅在于路由选项的位置。
4. 区分 TanStack Start（SSR，使用 HeadContent 和 Scripts 的根文档外壳）与仅客户端的 Vite 应用（将 RouterProvider 渲染到 div 中）。仅客户端应用在 React 运行前不会绘制任何内容，因此不需要绘制前规则。检查每条路由的 ssr、defaultSsr、spa.enabled 和预渲染设置。
5. 阅读路由器选项：defaultPreload、defaultPendingComponent、defaultPendingMs、defaultPendingMinMs、defaultViewTransition、scrollRestoration、defaultStaleTime、defaultRemountDeps。这些选项都会影响页面挂载时机，以及页面加载期间用户看到的内容。

选择动画引擎

对于快照变形或页面交叉淡入淡出，请使用 defaultViewTransition 或 Link/navigate 的 viewTransition。对于会阻止导航的实时 DOM 退场、可中断序列、拆分文本或滚动联动动画，请使用 GSAP。每个元素只使用一种引擎；请参阅组合使用动画引擎。

只阅读你需要的内容

• 不可见入口、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 路由器 API、一次导航的顺序、使用 useBlocker 或被拦截的 Link 在导航前执行退出动画、锁定、前进和后退、待处理 UI、切换间隙、滚动、焦点、View Transitions：TanStack 导航。
• 路由复用与 remountDeps、布局和 Outlet、GSAP 的 React 生命周期、条件内容、TanStack Start SSR 和水合、延迟数据：路由生命周期。
• 五个阶段、GSAP 设置、显示和隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• 使用 Lenis、ScrollSmoother，或在路由间实现缓动式页面滚动：平滑滚动，以及 TanStack 集成。
• 幕帘、首次访问预加载器和共享元素变形：过渡类型，以及 它们在 TanStack Router 中的位置。
• 触控、视口变化和设备预算：设备与输入。
• Tauri、Electron 或 Wails 桌面外壳：桌面 WebView。
• 完成工作前：验证。

在本仓库中安装 GSAP 官方技能。仅在需要时加载 gsap-core 以查看 API 详情，并加载 gsap-react 以设置组件。

规则

• 成功设置时保留不可见的引导页；失败时恢复当前进入页面的所有权。添加隐藏规则前，先遵循初始化约定。
• GSAP 仅在客户端运行。useGSAP 永远不会在服务器上运行；在 Start 于服务器上渲染的文件中，勿在模块作用域调用 GSAP。限定选择器的作用范围。清理每个补间、触发器、分割对象和监听器。
• 使用常规 CSS 和稳定的包装元素预留最终几何布局；让离开的内容与进入的内容重叠，不要增加布局占用空间。
• 先挂载，再设置初始值，然后绘制。成功初始化时，绝不能在引导动画前闪现已稳定的内容。在 Start 中，服务器 HTML 会在 hydration 前绘制，因此只有通过 ScriptOnce 内联脚本设置的根元素属性，且仅在初始阶段，才隐藏引导目标；同时提供无 JavaScript 时的路径。
• 到达稳定状态时清除临时样式。仅在动画期间使用 will-change；它会覆盖 gsap-performance 的静态提示。
• 使用能力查询划分设备层级。触摸状态要能解除；控件无需悬停也能操作。
• 在离场动画和结束状态期间，保持离开的页面已挂载且可见。只有所有阻止器都允许导航且加载器完成后，路由器才会切换；在结束回调中解除阻止器。
• URL 更改前不会触发路由器事件。onBeforeNavigate 在历史记录提交后运行；只有阻止器会在提交前运行。
• 使用新参数导航到同一路由时，会复用组件。针对参数运行一次生命周期，确保 DOM 已持有稳定值，并以参数作为键；或者设置 remountDeps。
• 后退和前进导航会携带 action：BACK、FORWARD 或 GO。绝不要为它们运行离场动画；阻止器运行时，URL 已经改变。滚动恢复后，为它们提供仅运行入场动画的路径。
• 加载开始时，useLocation 会切换到目标位置，此时新页面尚未挂载。不要以它作为路由内容的键；应以已呈现的匹配项或 resolvedLocation 作为键。
• 保留原生链接行为、预加载、activeProps、焦点、滚动和无 JavaScript 时的可读性。
• 减少动态效果时也要达到相同的稳定状态，并仍然触发每个完成回调，包括允许被阻止导航继续进行的回调。
• 明确定义中断和快速点击时的行为；完成时必须恰好释放一次导航等待。
• 条件允许时，在真实浏览器中验证。对于路由、配置、依赖或发布变更，使用生产构建。