gsap-astro

GSAP Astro

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

没有 <ClientRouter /> 时，完整文档加载应使用 gsap-vanilla。使用它时，挂载和卸载对应于 body 交换；模块脚本、全局监听器、时间线和持久化元素可能会保留。动画负责交换之间的五个阶段。

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

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

从项目入手

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

1. 查看已安装的 Astro 版本。在依赖记忆之前，先阅读 node_modules/astro/dist/transitions/router.js、swap-functions.js 和 node_modules/astro/components/ClientRouter.astro；该软件包不附带变更日志，因此请查看对应版本的发布说明。版本门槛：<ClientRouter />（5.0；4.x 中为 <ViewTransitions />，6.0 中已移除）、带有 loader 和 newDocument 的生命周期事件（3.6）、表单导航（4.0）、transition:persist-props 和 data-astro-rerun（4.5）、swapFunctions（4.15）。
2. 查找 <ClientRouter /> 的位置：共享 head、部分页面，还是完全没有，以及它的 fallback 属性。若完全没有，则使用 gsap-vanilla，包括 CSS @view-transition。
3. 查找哪些框架集成会渲染岛屿，以及正在使用哪些 client:* 指令。
4. 检查 astro.config 中的 prefetch 和 experimental.clientPrerender。

选择引擎

在 ClientRouter 下，对快照变形、淡入淡出或滑动效果使用 transition:name / transition:animate。对需要暂停交换的实时 DOM 退场、可中断序列、分段文本或与滚动关联的动画，使用 GSAP。每个元素只用一个引擎；请参阅组合使用动画引擎。

只阅读所需内容

• 不可见的入场、初始化失败、索引和首次加载性能：初始化与恢复，以及框架集成。
• 路由器的事件顺序、交换前的退场、清理、传入页面的初始状态、方向、前进和后退、滚动、焦点、预取、回退浏览器：ClientRouter 导航。
• 哪些脚本会再次运行、跨页面存续的监听器、自定义元素、岛屿和 client:* 指令、transition:persist：脚本与岛屿。
• 五个阶段、GSAP 设置、上下文、显示与隐藏、布局稳定性、滚动、文本、插件：生命周期实现。
• 在交换期间使用 Lenis、ScrollSmoother 或缓动式页面滚动：平滑滚动，以及路由器集成。
• 幕布、首次访问预加载器和共享元素变形：转场模式，以及事件映射。
• 触控、视口变化和设备预算：设备与输入。
• Tauri、Electron 或 Wails 桌面外壳：桌面 WebView。
• 在宣布工作完成前：验证。

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

规则

• 成功初始化时保留不可见的入场效果；失败时恢复当前进入的所有者。添加隐藏规则前，先遵循初始化约定。
• GSAP 在目标 DOM 存在后运行。使用 gsap.context 将选择器限定在页面或组件根节点内。在移除所有者的交换发生前，清理每个补间、触发器、分割对象和监听器。
• 模块脚本每次访问运行一次，而不是每个页面运行一次。初始化在 astro:page-load 时运行，并且在新 body 上或同一个 body 上再次运行时都能正常工作。
• document 和 window 上的监听器生命周期长于页面。只在一个位置注册路由器监听器，并让每个处理器在执行操作前查找当前页面。
• 使用常规 CSS 和稳定的包装器预留最终几何布局；让离场内容和入场内容重叠，而不增加布局空间。
• 在绘制前设置初始值，然后再显示内容。首次加载时使用内联 head 脚本；交换后使用 astro:before-swap 和 astro:after-swap。成功初始化时，入场动画开始前绝不会闪现已稳定的内容，也绝不会在没有 JavaScript 时出现空白页面。
• 稳定后清除临时样式。仅在动画期间使用 will-change；它会覆盖 gsap-performance 的静态提示。
• 使用能力查询划分设备层级。触控状态应能释放；控件无需悬停也能使用。
• 退场动画在 astro:before-preparation 中的 event.loader 内对活动 DOM 播放，路由器会等待动画完成。绝不要在 astro:before-swap 中播放动画：用户看到的是快照。
• 后退和前进采用仅入场动画的路径。遍历会触发每个事件，因此要有意在 navigationType === "traverse" 时跳过退场动画。
• 将 transition:persist 元素排除在页面级清理和页面级入场动画之外。它们会连同时间线一起存活并跨越交换。
• 保留原生链接行为、路由器的历史记录、滚动位置恢复和路由公告。不要在路由器旁添加点击拦截器来处理动画；唯一的点击监听器是捕获阶段的守卫，它会在导航进行期间保持锁定。
• 交换前的清理会销毁页面上下文；不会还原它。还原操作会将入场动画的起始值写回仍处于挂载状态的 body。
• 减少动态效果时也会到达相同的稳定状态，并且仍会触发每个完成回调。路由器已在 prefers-reduced-motion 下禁用自身动画。
• 使用时间线编排序列。预先决定快速点击和动画中断时的处理方式：退场动画运行期间，路由器允许第二次点击中止第一次导航，因此若要确保首次点击优先，需要使用锁定守卫。
• 条件允许时，在真实浏览器中进行验证，包括重复访问同一页面、后退、前进，以及在退场动画播放期间点击。