gsap-react

gsap-react 技能概览

gsap-react 是做什么的

gsap-react 是官方的 GSAP 技能，面向 React 以及基于 React 的框架，比如 Next.js。它帮助你用正确的 React 安全模式来做动画：useGSAP()、作用域选择器、gsap.context()，以及自动清理。需要在组件里加动效，又不想被重新渲染、卸载或 DOM 选择 bug 反复折腾时，就该用 gsap-react 技能。

适合谁使用

这个技能适合已经会 React、想要稳定动画方案的前端工程师，而不是给零基础动画入门准备的通用教程。尤其适合你在判断 React 应用里要不要用 GSAP、动画在路由切换后失效，或者需要了解 gsap-react 安装与集成流程时使用。

它有什么不同

它的核心价值是 React 相关的安全性。gsap-react 不会让你直接写一个普通的 useEffect() 动画再手动清理，而是引导你使用 useGSAP() 和作用域目标，让动画行为更可预测。它还可以帮你避开那些常见、却很影响落地的问题：选择器未作用域化、插件没注册、以及对 SSR 相关问题的误解。

如何使用 gsap-react 技能

安装 GSAP 和 React 包

做 gsap-react 安装时，需要把这两个包都加到你的应用里：

npm install gsap
npm install @gsap/react

然后在使用 useGSAP() 或其他 GSAP 代码之前先注册插件：

import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);

如果跳过这一步，hook 的行为就不会符合预期。

把模糊目标变成可执行的提示词

最好的 gsap-react 用法，不是先说“让它看起来更好”，而是先给出具体动画目标。请包含：组件类型、哪些元素要动、什么时候开始、是否需要循环、以及效果是否必须在路由切换后继续生效或在卸载时清理。

一个更强的提示词可以像这样：

• “在 Next.js 客户端组件里，页面加载时让三个卡片依次滑入，并且只作用于这个容器。”
• “把这个 useEffect() GSAP 动画改成带清理的 useGSAP()，并补上 refs。”
• “加上 hover 和滚动触发的动效，但选择器要限定在组件内部。”

先读对文件

先从 SKILL.md 开始，再查看仓库副本里定义行为和约束的部分。在这个技能里，真正有用的路径很短，所以先读核心说明，再按需查看关联示例或上下文文档。对于 gsap-react，最关键的判断点在 When to Use This Skill、Installation 和 Prefer the useGSAP() Hook 这几部分。

使用 React 安全的工作流

默认工作流是：导入 useGSAP、注册插件、创建一个 ref、把选择器限定到这个 ref 上，并把动画代码放进 hook 里。相比直接使用全局 document 选择器或未作用域化的 timeline，这种做法更稳。如果你需要稍后才触发的回调，使用 contextSafe，这样延迟交互也能正确清理。

gsap-react 技能 FAQ

在 React 里做每个 GSAP 动画都需要 gsap-react 吗？

不需要。如果动画很小，而且你在技术栈的其他部分已经有成熟方案，这个技能可能就没必要。只有当代码会碰到组件生命周期、清理、受限 DOM 定位，或者 React/Next.js 的框架特定行为时，才更适合用 gsap-react。

它和普通提示词有什么区别？

普通提示词也许能生成可运行的动画代码，但 gsap-react 额外加入了生产环境里很重要的 React 集成规则：插件注册、useGSAP()、作用域选择器和清理行为。这能减少调试时间，也让输出在真实应用代码里更容易复用。

gsap-react 适合初学者吗？

适合，只要使用者能描述组件和想要的动效。它不是动画理论入门课，而是一个实用的 gsap-react 指南，帮助你把粗略的界面想法变成安全的 React 代码。初学者如果能提供组件结构和预期触发条件，效果最好。

什么时候不该用它？

不要在非 React 框架里选 gsap-react，也不要在你需要一个与库无关的动画答案时使用它。对于 Vue、Svelte 和其他技术栈，应使用对应框架的 GSAP 技能。如果你只需要核心 tween 或 timeline 语法，其他 GSAP 技能可能更合适。

如何改进 gsap-react 技能

给结构，不要只给意图

想让 gsap-react 的输出更好，最关键的是具体。请提供组件的 markup、你已经有的选择器或 refs，以及明确的触发条件。“给 hero 做动画”太弱；“标题淡入、CTA 左滑进入、功能卡片首次渲染时依次错开出现”则能给技能足够细节，产出可用代码。

提前说明会改变实现方式的约束

尽早说明 SSR、路由切换、减少动态效果和清理预期。这些约束会直接决定答案该用 useGSAP()、客户端组件、作用域 refs，还是另一种动画方式。如果你的应用是 Next.js，请在提示词里明确写出来。

先检查第一次结果里的作用域问题

常见失败模式包括：选择器未作用域化、动画触发过早、代码忽略组件卸载。如果第一次输出用了像 .box 这样的宽泛选择器，却没有 scope，就要求它改写成基于 ref 的版本。如果回调会延迟触发，就在后续追问里要求加入 contextSafe 处理。

按你真正想要的动效逐步迭代

第一次结果出来后，每次只改一个变量：时长、缓动、stagger、触发条件或清理行为。一个好的 gsap-react 使用循环通常是：先实现基础动画，在组件里测试，然后再做有针对性的调整，比如“移动端别这么激进”或者“把触发条件改成只在 hover 时生效”。