gsap-vanilla

GSAP Vanilla

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

在完整文档加载时，由浏览器负责挂载和卸载，动画负责两者之间的五个阶段。在同一文档内切换时，由路由器负责替换节点，持久资源需要显式清理。

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

此技能决定动画何时运行。对于要动的内容，以及高级或俏皮之类的风格，如果已安装，也请加载 animaxxing 技能：其中的动画方案和风格定位指南可融入此生命周期。

从项目入手

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

1. 弄清页面的生成方式：手写 HTML、不使用客户端框架的静态生成器、不使用 UI 框架的打包工具（如 Vite），或 Swup、Barba、Taxi 之类的转场库。如果页面由组件框架渲染，请说明此技能不适用，并使用该框架对应的技能。
2. 弄清 GSAP 的加载方式：npm 导入、导入映射或脚本标签。保持现状。
3. 弄清脚本的运行方式：内联、defer 或 type="module"。这决定 DOM 何时存在，以及脚本运行前页面是否可以绘制。
4. 检查目标浏览器。跨文档 View Transitions、pageswap 和 pagereveal、Navigation API 以及 blocking="render" 并非所有浏览器都支持。阅读已安装的转场库文档和类型定义，并对浏览器 API 进行特性检测，不要依赖记忆；同时确保这些功能都不可用时，网站仍能正常运行。

选择导航模式

编写生命周期代码前，先确定导航模式。每次导航都应由一个对象负责；即使是同一文档路由器，也可能需要完整加载作为回退。

• 完整文档加载。 每个链接都会替换整个文档。跟随链接前播放退场动画；新页面加载时播放入场动画。这是默认模式，无需路由器。
• 使用跨文档 View Transitions 的完整文档加载。 浏览器会对旧页面进行快照，并将其动画过渡到新页面。对于一对快照无法实现的效果，由 GSAP 补充。
• 同一文档内导航。 脚本会获取下一页面并就地替换内容，因此页面框架、状态和时间轴会持续存在。除非项目已有路由器，或有其他理由，否则请使用维护中的库。请参阅同一文档内导航。

选择引擎

对于快照变形或页面交叉淡入淡出，使用跨文档 View Transitions，并提供即时切换回退。对于会阻止导航的实时 DOM 退场动画、可中断序列、分割文本或滚动关联动画，使用 GSAP。每个元素只使用一个引擎；请参阅组合使用引擎。

只阅读所需内容

• 不可见的进入效果、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 首次绘制、脚本时序、字体、导航类型、预渲染、bfcache、隐藏标签页，以及带有退场动画地离开页面：页面加载与卸载。
• @view-transition、pageswap、pagereveal、类型、渲染阻塞，以及在浏览器和 GSAP 之间移交控制权：跨文档导航。
• Fetch 和 swap 路由器、链接拦截、历史记录、滚动、焦点、脚本重新执行，以及何时使用库：同文档导航。
• 五个阶段、GSAP 设置、上下文、显示和隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• Lenis、ScrollSmoother，或跨文档和交换页面时带缓动的页面滚动：平滑滚动，以及每个文档各自的滚动容器和交换路由器下的单一滚动容器。
• 幕布、首次访问预加载器和共享元素变形：过渡模式，以及完整文档和同文档集成。
• 触摸、视口变化和设备预算：设备与输入。
• 在确认工作完成之前：验证。

请在此仓库旁安装官方 GSAP 技能。加载 gsap-core 以查看 API 详情，并仅在需要时加载相关插件技能。

规则

• 成功设置时保留不可见的入场状态；失败时恢复当前进入内容的所有者。添加隐藏规则前，先遵循初始化约定。
• GSAP 只在其目标 DOM 存在后运行。使用 gsap.context 将选择器限定在页面或组件根节点内。所有者离开时，清理每个补间、触发器、分割对象和监听器。
• 使用常规 CSS 和稳定的包装元素预留最终几何布局；让离开和进入的内容重叠，而不增加布局空间。
• 在首次绘制前设置初始值，然后显示内容。成功初始化时，已稳定的内容绝不会在入场效果前闪现；没有 JavaScript 时，页面也绝不会空白。
• 在稳定状态时清除临时样式。仅在动画期间使用 will-change；这会覆盖 gsap-performance 的静态提示。
• 使用能力查询划分设备等级。触摸状态应能释放；控件不得依赖悬停才能使用。
• 在退场效果和结束状态期间，保持离开的内容留在 DOM 中且可见。仅在结束回调中跟随链接、移除节点或执行交换。
• 后退和前进绝不运行退场效果。通过历史记录到达的新文档采用仅入场路径，而 bfcache 恢复则完全不运行入场效果。
• 预渲染的页面应立即设置初始状态，并等待激活后再播放动画。
• 保留原生链接行为、焦点、滚动恢复和无 JavaScript 时的可读性。
• 绝不为动画添加 unload 或 beforeunload 监听器。它们会禁用 bfcache。请使用 pagehide。
• 减少动态效果时也应到达相同的稳定状态，并仍然触发每个完成回调。
• 明确中断和快速点击时的行为；完成时必须恰好释放一次导航等待。
• 条件允许时，在真实浏览器中验证，包括重新加载、后退、前进，以及从后台标签页发起的点击。