GSAP 插件 是做什么的?
何时使用此技能
在代码中使用或审查 GSAP 插件时应用:注册插件、滚动到(scroll-to)、翻转/FLIP 动画、可拖动元素、SVG(DrawSVG、MorphSVG、MotionPath)、文本(SplitText、ScrambleText)、物理效果、缓动插件(CustomEase、EasePack、CustomWiggle、CustomBounce)或 GSDevTools。ScrollTrigger 有自己的技能(gsap-scrolltrigger)。
相关技能: 核心补间请使用 gsap-core;ScrollTrigger 请使用 gsap-scrolltrigger;React 请使用 gsap-react。
许可与安装(重要)
每个 GSAP 插件都是免费的,包括商业用途。自 Webflow 收购 GSAP 以来,Club GSAP 不再是付费层级,任何插件都不需要会员、许可证密钥或认证令牌——这包括以前仅限 Club 的插件(SplitText、MorphSVG 等)。
- ✅ 从公共
gsapnpm 包安装所有内容:npm install gsap。所有插件都包含在内——按gsap/SplitText、gsap/MorphSVGPlugin等导入。 - ❌ 不要生成带有 GreenSock 认证令牌的
.npmrc,不要建议使用私有npm.greensock.com注册表,也不要告诉用户注册 Club GSAP 以访问插件。这些说明已过时。
注册插件
每个插件注册一次,以便 GSAP(和打包工具)知道包含它。使用 gsap.registerPlugin() 处理项目中使用的每个插件:
import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";
gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
- ✅ 在任何补间或 API 调用中使用插件之前进行注册。
- ✅ 在 React 中,在顶层或应用内注册一次(例如,在第一次使用 useGSAP 之前);不要在会重新渲染的组件内部进行注册。useGSAP 是一个插件,需要在使用前注册。
滚动
ScrollToPlugin
动画化滚动位置(窗口或可滚动元素)。用于无需 ScrollTrigger 的“滚动到元素”或“滚动到位置”。
gsap.registerPlugin(ScrollToPlugin);
gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
ScrollToPlugin — 关键配置(scrollTo 对象):
| 选项 | 描述 |
|---|---|
x, y | 目标滚动位置(数字),或 "max" 表示最大值 |
element | 要滚动到的选择器或元素(用于滚动到视图) |
offsetX, offsetY | 距离目标位置的像素偏移 |
ScrollSmoother
平滑滚动包装器(平滑化原生滚动)。需要 ScrollTrigger 和特定的 DOM 结构(内容包装器 + 平滑包装器)。当需要平滑、动量式滚动时使用。设置请参阅 GSAP 文档;在 ScrollTrigger 之后注册。DOM 结构如下:
<body>
<div id="smooth-wrapper">
<div id="smooth-content">
<!--- 所有内容放在这里 --->
</div>
</div>
<!-- position: fixed 元素可以放在外面 --->
</body>
DOM / UI
Flip
使用 Flip.getState() 捕获状态,然后应用更改(例如布局或类更改),然后使用 Flip.from() 从先前状态动画化到新状态(FLIP:First、Last、Invert、Play)。在两种布局状态之间进行动画时使用(列表、网格、展开/折叠)。
gsap.registerPlugin(Flip);
const state = Flip.getState(".item");
// 更改 DOM(重新排序、添加/删除、更改类)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
Flip — 关键配置(Flip.from vars):
| 选项 | 描述 |
|---|---|
absolute | 在翻转期间使用 position: absolute(默认:false) |
nested | 为 true 时,仅测量第一级子级(对于嵌套变换更好) |
scale | 为 true 时,缩放元素以适应(避免拉伸);默认 true |
simple | 为 true 时,仅对位置/缩放进行动画(更快,精度较低) |
duration, ease | 标准补间选项 |
更多信息
https://gsap.com/docs/v3/Plugins/Flip
Draggable
使元素可通过鼠标/触摸拖动、旋转或抛出。用于滑块、卡片、可重新排序列表或任何拖动交互。
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });
Draggable — 关键配置选项:
| 选项 | 描述 |
|---|---|
type | "x"、"y"、"x,y"、"rotation"、"scroll" |
bounds | 元素、选择器或 { minX, maxX, minY, maxY } 以限制拖动 |
inertia | true 以启用抛出/动量(需要 InertiaPlugin) |
edgeResistance | 0–1;拖出边界时的阻力 |
cursor | 拖动期间的 CSS 光标 |
onDragStart, onDrag, onDragEnd | 回调函数;接收事件和目标 |
onThrowUpdate, onThrowComplete | 惯性激活时的回调函数 |
Inertia(InertiaPlugin)
与 Draggable 配合使用,在释放后产生动量,或者跟踪任何对象任何属性的惯性/速度,以便它可以使用简单补间无缝滑动到停止。在使用 inertia: true 时与 Draggable 一起注册:
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });
或者跟踪属性的速度:
InertiaPlugin.track(".box", "x");
然后使用 "auto" 继续当前速度并滑动到停止:
gsap.to(obj, { inertia: { x: "auto" } });
Observer
跨设备标准化指针和滚动输入。用于滑动、滚动方向或自定义手势逻辑,无需像 ScrollTrigger 那样直接绑定滚动位置。
gsap.registerPlugin(Observer);
Observer.create({
target: "#area",
onUp: () => {},
onDown: () => {},
onLeft: () => {},
onRight: () => {},
tolerance: 10
});
Observer — 关键配置选项:
| 选项 | 描述 |
|---|---|
target | 要观察的元素或选择器 |
onUp, onDown, onLeft, onRight | 当滑动/滚动超出该方向容差时的回调函数 |
tolerance | 在检测方向之前的像素数;默认 10 |
type | "touch"、"pointer" 或 "wheel"(默认:"touch,pointer") |
文本
SplitText
将元素的文本拆分为字符、单词和/或行(每个都在自己的元素中),用于交错或逐单元动画。当逐字符、逐词或逐行动画文本时使用。返回一个包含 chars、words、lines 的实例(当设置 mask 时还有 masks)。使用 revert() 恢复原始标记,或让 gsap.context() 恢复。与 gsap.context()、matchMedia() 和 useGSAP() 集成。API:SplitText.create(target, vars)(target = 选择器、元素或数组)。
gsap.registerPlugin(SplitText);
const split = SplitText.create(".heading", { type: "words, chars" });
gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
// 稍后:split.revert() 或让 gsap.context() 清理恢复
使用 onSplit()(v3.13.0+),动画在每次拆分和重新拆分时运行(当使用 autoSplit 时);从 onSplit() 返回一个补间/时间线,让 SplitText 清理并在重新拆分时同步进度:
SplitText.create(".split", {
type: "lines",
autoSplit: true,
onSplit(self) {
return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
}
});
SplitText — 关键配置(SplitText.create vars):
| 选项 | 描述 |
|---|---|
| type | 逗号分隔:"chars"、"words"、"lines"。默认 "chars,words,lines"。仅拆分所需的部分(例如,如果不使用行,则使用 "words, chars")以提高性能。避免仅拆分 chars 而不包含 words/lines,或使用 smartWrap: true 以防止奇怪的换行。 |
| charsClass, wordsClass, linesClass | 每个拆分元素上的 CSS 类。追加 "++" 以添加递增类(例如 linesClass: "line++" → line1、line2、…)。 |
| aria | "auto"(默认)、"hidden" 或 "none"。辅助功能:"auto" 在拆分元素上添加 aria-label,并在行/单词/字符元素上添加 aria-hidden,以便屏幕阅读器读取标签;"hidden" 对所有阅读器隐藏所有内容;"none" 保持 aria 不变。如果必须暴露嵌套链接/语义,请使用 "none" 加上仅屏幕阅读器的副本。 |
| autoSplit | 当为 true 时,在字体加载完成或元素宽度更改(并且行被拆分)时恢复并重新拆分,避免错误的换行。动画必须在 onSplit() 内部创建,以便它们针对新拆分的元素;从 onSplit() 返回动画以在重新拆分时自动清理和时间同步。 |
| onSplit(self) | 拆分完成时的回调函数(如果 autoSplit 为 true,则在每次重新拆分时也触发)。接收 SplitText 实例。返回 GSAP 补间或时间线,可在重新拆分时自动恢复/同步该动画。 |
| mask | "lines"、"words" 或 "chars"。将每个单元包装在带有 overflow: clip 的额外元素中以实现遮罩/揭示效果。仅一种类型;通过实例的 masks 数组访问包装器(如果设置了类,则使用类 -mask)。 |
| tag | 包装器元素标签;默认 "div"。对于内联使用 "span"(注意:在某些浏览器中,旋转/缩放等变换可能不会在内联元素上渲染)。 |
| deepSlice | 当为 true(默认)时,跨越多个行的嵌套元素(例如 <strong>)被细分,以便行不会垂直拉伸。仅在拆分行时适用。 |
| ignore | 保持不拆分的选择器或元素(例如 ignore: "sup")。 |
| smartWrap | 仅拆分 chars 时,将单词包裹在带有 white-space: nowrap 的 span 中以避免词内换行。如果拆分 words 或 lines,则忽略。默认 false。 |
| wordDelimiter | 单词边界:字符串(默认 " ")、RegExp 或 { delimiter: RegExp, replaceWith: string } 用于自定义拆分(例如,用于标签的零宽度连接符,或非拉丁语)。 |
| prepareText(text, parent) | 一个函数,接收原始文本和父元素;在拆分前返回修改后的文本(例如,为没有空格的插入换行标记)。 |
| propIndex | 当为 true 时,在每个拆分元素上添加带有索引的 CSS 变量(例如 --word: 1、--char: 2)。 |
| reduceWhiteSpace | 折叠连续空格;默认 true。从 v3.13.0 起也尊重换行符,并且可以为 <pre> 插入 <br>。 |
| onRevert | 实例恢复时的回调函数。 |
提示: 仅拆分要动画的部分(例如,如果仅动画单词,则跳过 chars)。对于自定义字体,在它们加载后拆分(例如 document.fonts.ready.then(...))或使用 autoSplit: true 结合 onSplit()。为避免拆分 chars 时的字距偏移,请使用 CSS font-kerning: none; text-rendering: optimizeSpeed;。避免 text-wrap: balance;它可能会干扰拆分。SplitText 不支持 SVG <text>。
了解更多: SplitText
ScrambleText
使用乱码/故障效果动画化文本。在显示或转换文本并带有乱码效果时使用。
gsap.registerPlugin(ScrambleTextPlugin);
gsap.to(".text", {
duration: 1,
scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});
SVG
DrawSVG(DrawSVGPlugin)
通过动画化 stroke-dashoffset / stroke-dasharray 来显示或隐藏 SVG 元素的描边。适用于 <path>、<line>、<polyline>、<polygon>、<rect>、<ellipse>。在“绘制”或“擦除”描边时使用。
drawSVG 值: 描述沿路径的描边的可见段(起始和结束位置),而不是“随时间从 A 动画到 B”。格式:百分比或长度的 "start end"。示例:"0% 100%" = 完整描边;"20% 80%" = 仅 20% 到 80% 之间的描边(两端有空隙)。补间从元素的当前段动画到目标段——例如 gsap.to("#path", { drawSVG: "0% 100%" }) 从当前状态变为完整描边。单个值(例如 0、"100%")意味着起始为 0:"100%" 等同于 "0% 100%"。
必需: 元素必须有可见的描边——在 CSS 或 SVG 属性中设置 stroke 和 stroke-width;否则不会绘制任何内容。
gsap.registerPlugin(DrawSVGPlugin);
// 从无到完整描边进行绘制
gsap.from("#path", { duration: 1, drawSVG: 0 });
// 或显式段:从 0–0 到 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// 仅中间部分描边(两端有空隙)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
注意事项: 仅影响描边(不影响填充)。首选单段 <path> 元素;多段路径在某些浏览器中可能渲染异常。<use> 元素的内容无法在视觉上更改。DrawSVGPlugin.getLength(element) 和 DrawSVGPlugin.getPosition(element) 返回描边长度和当前位置。
了解更多: DrawSVG
MorphSVG(MorphSVGPlugin)
通过动画化 d 属性(路径数据)将一个 SVG 形状变形为另一个。起始和结束形状不需要相同数量的点——MorphSVG 将其转换为三次贝塞尔曲线并根据需要添加点。用于图标到图标的变形、形状过渡或基于路径的动画。适用于 <path>、<polyline> 和 <polygon>;<circle>、<rect>、<ellipse> 和 <line> 在内部转换或通过 MorphSVGPlugin.convertToPath(selector | element) 转换(替换 DOM 中的元素为 <path>)。
morphSVG 值: 可以是选择器(例如 "#lightning")、元素、原始路径数据(例如 "M47.1,0.8 73.3,0.8..."),或者对于 polygon/polyline 是点字符串(例如 "240,220 240,280 320,280 320,220")。默认情况下,它找到从起始形状到结束形状的最短动画路径。添加 shapeIndex 以覆盖特定形状索引(当 GSAP 选择的不是您想要的时)。使用 "log" 获取控制台日志,了解 GSAP 如何解释形状。
gsap.registerPlugin(MorphSVGPlugin);
// 将 #star 变形为 #circle
gsap.to("#star", {
duration: 1,
morphSVG: "#circle",
ease: "power2.inOut"
});
MorphSVG — 关键配置:
| 选项 | 描述 |
|---|---|
shapeIndex | 起始形状的索引(用于多段路径) |
map | "size"、"position"、"both" 或 "none"(如果形状以不同方式缩放/定位,则帮助映射) |
fill | "color" 以动画填充颜色(如果使用 autoCSS,则自动) |
stroke | "color" 以动画描边颜色(如果使用 autoCSS,则自动) |
autoCSS | 为 true 时,自动动画化 CSS 属性如 fill 和 stroke(同步) |
points | 仅用于 polygon 和 polyline 的字符串:将 points 属性动画化而不是转换为路径(更快,但如果点计数不同,则可能或将失败) |
type | "rotational" 或 "linear";默认自动检测 |
了解更多: MorphSVG
MotionPath(MotionPathPlugin)
沿 SVG 路径或自定义路径坐标动画化任何 DOM 元素或对象。用于将元素从 A 点移动到 B 点,而不是描边绘制。
gsap.registerPlugin(MotionPathPlugin);
gsap.to("#element", {
duration: 1,
motionPath: {
path: "#path",
align: "#path",
alignOrigin: [0.5, 0.5]
}
});
MotionPath — 关键配置选项:
| 选项 | 描述 |
|---|---|
path | 路径选择器("#path")、元素或点数组:[{x, y}, ...] |
align | 将元素与路径对齐;路径选择器、元素或 "auto" |
alignOrigin | 对齐点 [x, y](例如 [0.5, 0.5] 为中心) |
start | 路径的起始百分比(0–1) |
end | 路径的结束百分比(0–1) |
curviness | 路径曲线的分辨率(0–10) |
autoRotate | 为 true 时,元素沿路径旋转;从 v3.12.6 起可设置为度数或字符串 |
动画与缓动
CustomEase
在 GSAP / SVG / canvas 时间线中创建自定义缓动曲线。使用提供的手绘风格或自定义贝塞尔曲线。用法:CustomEase.create(name, "M0,0 C0.25,0 0.7,0.5 ...")。
gsap.registerPlugin(CustomEase);
CustomEase.create("myEase", "M0,0 C0.055,0.015 0.195,0.215 0.4,0.7 0.535,1 0.695,1 1,1");
gsap.to(".box", { duration: 1, ease: "myEase" });
EasePack
额外的宽松缓动函数,例如 RoughEase、SlowMo 和 SteppedEase。
gsap.registerPlugin(EasePack);
gsap.to(".box", { duration: 1, ease: "roughEase" });
gsap.to(".box", { duration: 1, ease: "slowMo(0.7, 0.7)" });
gsap.to(".box", { duration: 1, ease: "steps(10)" });
CustomWiggle
创建自定义抖动缓动曲线(来回振荡,逐渐衰减)。
gsap.registerPlugin(CustomWiggle);
CustomWiggle.create("myWiggle", { wiggles: 6, type: "ease-out" });
gsap.to(".box", { duration: 1, ease: "myWiggle" });
CustomBounce
创建自定义弹跳缓动曲线,控制弹跳的高度、频率和衰减。
gsap.registerPlugin(CustomBounce);
CustomBounce.create("myBounce", { strength: 0.7, squash: 2, squashDuration: 0.2 });
gsap.to(".box", { duration: 1, ease: "myBounce" });
物理
Physics2DPlugin
模拟 2D 物理(速度、加速度、角度、重力)。对粒子效果、下落元素或任何简单 2D 运动有用。
gsap.registerPlugin(Physics2DPlugin);
gsap.to(".particle", {
physics2D: {
velocity: 400,
angle: 45,
gravity: 200
},
duration: 2
});
Physics2DPlugin — 关键配置:
| 选项 | 描述 |
|---|---|
velocity | 初始速度(像素/秒) |
angle | 运动角度(度) |
gravity | 重力加速度(像素/秒²,如果无重力则为 0) |
acceleration | 自定义加速度向量 {x, y} |
friction | 0–1 之间的摩擦系数 |
PhysicsPropsPlugin
动画一个对象的任意属性的物理行为(如弹性或弹簧运动),而不受 2D 平面约束。常用于弹簧、缩放或颜色过渡。
gsap.registerPlugin(PhysicsPropsPlugin);
gsap.to(obj, {
physicsProps: {
x: { velocity: 500, acceleration: 200 },
rotation: { velocity: 360 }
},
duration: 2
});
调试
GSDevTools
一个 UI 控件,用于在开发期间在播放、暂停、重置、快进、提高/降低速度等之间切换。只需在创建任何补间或时间线后,在 GSMasterTimeline 或特定时间线(或仅 "gsap" 用于全局 GSAP 时间线——如果找到,严格使用全局时间线)上调用它。必须注册 ScrollTrigger 和 GSDevTools。在开发期间使用,不得包含在生产构建中。
gsap.registerPlugin(GSDevTools);
gsap.to(".box", { duration: 1, x: 200 });
GSDevTools.create({ minimal: true });
GSDevTools — 常见配置选项:
| 选项 | 描述 |
|---|---|
container | 放置控件的选择器或元素 |
id | 为特定 GSDevtools 实例添加 ID |
animations | 要控制在 GSDevtools 中的动画或时间线数组 |
minimal | 为 true 时,显示更紧凑的 UI,带有更少的控件 |
tween | 在 GSDevtools 显示中定位特定的补间对象 |
timeline | 在 GSDevtools 显示中定位特定的时间线 |
了解更多: GSDevTools
零碎插件
更多信息: https://gsap.com/docs/v3/Plugins/
- AttrPlugin:动画任意 HTML 或 SVG 属性(
x、y、cx、r等)。使用attr: { r: 50, fill: "blue" }。对于不在内部 GSAP 坐标中的 SVG 属性很有用。 - DirectionalRotationPlugin:按特定方向(最短、顺时针、逆时针)旋转。使用
directionalRotation: { rotation: "short" }。 - EndArrayPlugin:将数组的最终值作为目标进行动画。使用
endArray: [100, 200, 300]。 - MotionPathHelper:视觉拖放编辑器,用于生成 MotionPath 路径坐标,无需手动编写
d数据。需要 GSDevTools 才能运行。使用MotionPathHelper.install(someAnimation)。 - PixiPlugin:将 GSAP 补间应用于 PixiJS 显示对象(用于渲染器 2D WebGL 游戏引擎)。
- PositionCache:避免在调整大小时重新计算弹性/文本元素的布局(仅历史上常见;不再主要使用)。
- RoundPropsPlugin:在动画期间将数值四舍五入为整数。使用
roundProps: "x,y"(或在一个补间中的对象中使用{ end: 200, round: true })。