gsap-nuxt

GSAP Nuxt

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

挂载和卸载属于 Vue；动画负责它们之间的五个阶段。Nuxt 页面离开时，组件会被销毁，而根元素会保留到调用 done 为止。过渡钩子（css: false）必须独立于组件清理来负责退场动画。

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

这项技能决定动画何时运行。至于动画内容，以及高级感或活泼等风格，如果已安装 animaxxing 技能，也请加载它：其中的配方和寻找风格指南可以配合这一生命周期使用。

从项目入手

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

1. 确认项目使用 Nuxt，且有 pages/ 目录。如果项目是使用 Vue Router 的纯 Vue 项目，没有 Nuxt，请说明这项技能不适用，并使用 gsap-frameworks。
2. 从 node_modules 中读取已安装的 Nuxt、Vue 和 Vue Router 版本。优先参考已安装的类型及其 JSDoc（node_modules/@nuxt/schema、node_modules/nuxt/dist、node_modules/@vue/runtime-core/dist、node_modules/vue-router/dist），以及对应版本的文档，而不是依赖记忆。版本要求：onPrehydrate（3.12）、useRuntimeHook（3.14）、app/ 源码目录（4）、视图过渡类型（4.4）、<NuxtLink custom> 插槽中的 prefetch（4.5）。
3. 阅读 nuxt.config：ssr、srcDir、app.pageTransition、app.layoutTransition、app.keepalive、experimental.viewTransition、future.compatibilityVersion。Nuxt 4 将 pages/、layouts/、middleware/、plugins/、composables/、app.vue 和 router.options.ts 放在 app/ 下；Nuxt 3 则将它们放在根目录下。两者中的 ~/ 都会解析到源码目录。

选择动画引擎

简单的页面淡入淡出或滑动使用 Vue Transition CSS；快照变形使用 experimental.viewTransition；实时 DOM 退场动画、动画编排、中断或受控重叠使用 GSAP JavaScript 钩子。每个元素只使用一种引擎，且不要在同一次导航中同时运行 Vue 钩子和视图过渡。参见视图过渡。

只阅读所需内容

• 隐形入场动画、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 钩子、done、模式、离开开始时会销毁什么、首次加载、布局、方向、中断：页面过渡。
• 页面键、keepalive、Nuxt 应用钩子、滚动和焦点、导航前退场动画、前进和后退、视图过渡、SSR 和首次绘制：导航。
• 五个阶段、GSAP 设置、Vue 生命周期、显示和隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• Lenis、ScrollSmoother 或跨路由的缓动页面滚动：平滑滚动，以及钩子映射。
• 遮罩、首次访问预加载器和共享元素变形：过渡范式，以及 app.vue 集成和共享元素。
• 触摸、视口变化和设备预算：设备与输入。
• Tauri、Electron 或 Wails 桌面外壳：桌面 WebView。
• 完成工作前：验证。

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

规则

• 成功初始化时保留不可见的引导动画；失败时恢复当前进入页面的所有权。添加隐藏规则前，先遵循初始化约定。
• GSAP 只在客户端运行。使用 import.meta.client、onMounted 或 <ClientOnly> 进行保护。限定选择器的作用范围。清理每个补间动画、触发器、分割效果和监听器。
• 使用常规 CSS 和稳定的包装元素预留最终几何布局；让离场和入场内容重叠，不要让布局空间加倍。页面和布局必须只有一个根元素，否则过渡不会运行。
• 先挂载，再设置初始值，然后绘制。onBeforeEnter 在入场根元素插入前运行，onEnter 紧接着运行，在浏览器绘制前执行。成功初始化时，已完成状态的内容绝不会在引导动画前闪现。
• 在状态稳定后清除临时样式。只在动画期间使用 will-change；它会覆盖 gsap-performance 的静态提示。
• 使用能力查询适配不同设备层级。触摸状态要能释放；控件不能依赖悬停才能工作。
• 始终调用 done：在 onComplete 中、在 onInterrupt 中，以及在减少动态效果时同步调用。如果离场操作从未调用 done，旧页面就会永远留在 DOM 中。
• 离场开始时，页面组件就会卸载；在 keepalive 下则会停用，而不是等离场结束后才卸载或停用。其上下文回退和 onUnmounted 会在离场动画播放期间运行。在 onLeave 中使用 el 构建离场动画，并放在由钩子管理的上下文中。
• 在离场动画和结束状态期间，始终将离场页面和组件保留在 DOM 中。只要 done 延后调用，Vue 就会做到这一点。
• 入场页面完成解析前，离场动画无法开始。应妥善设计等待过程：旧页面会继续显示且可交互。
• 在 keepalive 下，页面生命周期在重新激活时会再次运行，但此时 DOM 中已经保留了稳定状态的值。不要假设节点是新创建的。
• 后退和前进会触发与点击相同的钩子。自行检测历史导航，并为其提供更轻柔的过渡方式。不要伪造实际并未发生的离场动画。
• 不要在服务端渲染的页面上使用 appear：Vue 会将 <Transition appear> 的子元素包装在 <template> 中，因此在水合完成前，且没有 JavaScript 时，页面会一片空白。
• 保留原生链接行为、焦点、滚动，以及无 JavaScript 时的可读性。
• 减少动态效果时，应达到相同的稳定状态，并仍然调用 done 和每个完成回调。
• 明确中断和快速点击时的行为；完成后必须恰好释放一次导航等待。
• 条件允许时，在真实浏览器中验证。涉及路由、配置、依赖或发布的更改，应使用生产构建进行验证。