gsap-nextjs

GSAP Next.js

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

挂载和卸载由 React 管理；动画负责两者之间的五个阶段。启用 cacheComponents 时，请将路由隐藏视为卸载，并将再次显示视为在保留的 DOM 上重新挂载。

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

本技能决定动画何时运行。至于动画对象以及高级感、活泼感等风格，如果已安装 animaxxing 技能，也请加载它：其中的方案和风格定位指南可与此生命周期配合使用。

从项目入手

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

1. 确认项目使用 App Router。如果项目使用 Pages Router，请改用与版本匹配的 Pages Router 指南，不要使用本技能。
2. 查看已安装的 Next.js 版本。优先查阅 node_modules/next/dist/docs/ 中随 Next.js 提供的文档，而非依赖记忆。版本要求：onNavigate 和 useLinkStatus（15.3）、<ViewTransition> 和 transitionTypes（16.2）、启用 cacheComponents 时的 <Activity> 路由保留（16.0，可选）。
3. 检查 Next 配置中的 cacheComponents。它会影响路由的存续时长。

选择动画引擎

在已安装的 Next.js 版本支持时，使用 React <ViewTransition> 实现共享元素变形、页面交叉淡化和 Suspense 切换。使用 GSAP 实现需要阻止导航的实时 DOM 退场动画、可中断序列、拆分文本或滚动联动动画。每个元素只使用一种引擎；请参阅组合使用动画引擎。

仅阅读所需内容

• 不可见的入场动画、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 加载/身份验证闪烁和异步区域布局偏移：数据就绪，以及 React 数据集成。
• 页面入场和退场动画、支持过渡的链接、前进和后退、焦点、路由切换：App Router 导航。
• 五个阶段、GSAP 设置、React 生命周期、显示和隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• Lenis、ScrollSmoother 或跨路由的缓动页面滚动：平滑滚动，以及 App Router 集成。
• 遮罩、首次访问预加载器和共享元素变形：过渡模式，以及它们在 App Router 中的位置。
• 触控、视口变化和设备预算：设备与输入。
• 完成工作前：验证。

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

规则

• 成功初始化时保留不可见的开场状态；失败时恢复当前进入的所有者。添加隐藏规则前，先遵循初始化约定。
• GSAP 仅在客户端运行。限定选择器的作用范围。清理每个补间、触发器、分割对象和监听器。
• 使用常规 CSS 和稳定的包装器预留最终几何布局；让离场和进入的内容重叠，而不增加双倍布局空间。
• 每个所有者的结构化数据就绪后再显示；未解决的身份验证或查询不得伪装成访客状态或空内容。
• 先挂载，再设置初始值，然后绘制。成功初始化时，开场动画之前绝不会闪现已稳定的内容。
• 在动画结束后清除临时样式。仅在动画期间使用 will-change；这会覆盖 gsap-performance 的静态提示。
• 使用能力查询区分设备层级。触摸状态要能释放；控件不能依赖悬停才能工作。
• 在离场动画和结束状态期间，保持离场页面和组件挂载且可见。只有在结束回调执行后才卸载，或让路由器隐藏它们。
• 在 cacheComponents 下，页面重新显示时，其生命周期会在已保存稳定值的 DOM 上再次运行。绝不要假设节点是全新的。
• 返回和前进时绝不运行离场动画。为它们提供仅播放入场动画的路径。
• 保留原生链接行为、焦点、滚动和无 JavaScript 时的可读性。
• 减少动态效果时也要到达相同的稳定状态，并仍然触发每个完成回调。
• 明确中断和快速点击时的行为；完成时必须恰好释放一次导航等待。
• 条件允许时，在真实浏览器中验证。涉及路由、配置、依赖项或发布变更时，使用生产构建。