gsap-plugins

GSAP 插件

使用时机

当使用或审查使用了 GSAP 插件的代码时使用：注册插件、滚动到元素、翻转/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 等）。

• ✅ 从公共 gsap npm 包中安装所有内容：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 变量）：

选项	描述
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 变量）：

选项	描述
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	实例被恢复时的回调。

提示： 只拆分需要动画的部分（例如，如果只动画化单词，则跳过字符）。对于自定义字体，在字体加载后拆分（例如 document.fonts.ready.then(...)）或使用 autoSplit: true 配合 onSplit()。为避免拆分字符时的字距偏移，使用 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(选择器 | 元素) 转换（在 DOM 中将元素替换为 <path>）。

morphSVG 值： 可以是选择器（例如 "#lightning"）、元素、原始路径数据（例如 "M47.1,0.8 73.3,0.8..."），或者对于多边形/折线，可以是点字符串（例如 "240,220,240,280"）。

  gsap.registerPlugin(MorphSVGPlugin);

// 从一个元素变形到另一个
  gsap.to("#moon", { morphSVG: "#sun" });
// 变形为原始路径数据
gsap.to("#icon", { morphSVG: "M10,10 L50,10 L50,50 Z" });

MorphSVG 关键配置：

选项	描述
shapeIndex	起始路径上用于对齐的点索引（"auto" 自动计算最佳对齐；"log" 自动记录哪些点对齐）。对于复杂变形，如果结果扭曲，手动设置 shapeIndex: 10 等。
type	"rotational"（默认）或 "linear"。旋转类型在点之间寻找最短的弧形路径；线性类型寻找直线路径。
map	将起始点映射到结束点的函数：(startPoints, endPoints, shapeIndex) => { return {start: ..., end: ...} }。用于完全控制哪些点映射到哪些点。
prependTo	一个补间实例，MorphSVG 将在其开头插入其值，允许链条中较早的补间控制动画的较早部分。

了解更多： MorphSVG

缓动

CustomEase

定义完全自定义的缓动曲线（贝塞尔曲线或点）。使用任意数量的控制点创建平滑曲线，或通过点数组({x, y})定义严格的点对点路径。

gsap.registerPlugin(CustomEase);

// 贝塞尔曲线
CustomEase.create("myEase", "M0,0 C0.2,0 0.4,0.8 1,1");
gsap.to(".box", { duration: 1, ease: "myEase", x: 500 });

// 逐点缓动（严格遵循点）
CustomEase.create("bounceSteps", [
  { x: 0, y: 0 },
  { x: 0.25, y: 1 },
  { x: 0.5, y: 0.4 },
  { x: 0.75, y: 0.9 },
  { x: 1, y: 1 }
]);

了解更多： CustomEase

EasePack

一组额外的缓动函数。包括："sine.in", "sine.out", "sine.inOut", "circ.in", "circ.out", "circ.inOut", "back.in(1.7)", "back.out(2)", "back.inOut(1.5)", "slow(0.7,0.7)", "steps(12)", "expoScale"。

gsap.registerPlugin(EasePack);
gsap.to(".box", { x: 500, duration: 1, ease: "back.out(2)" });

CustomWiggle

创建复杂的摆动/弹性缓动曲线，无需数学知识。CustomWiggle.create(name, config) 其中配置可以是对象或回调。

gsap.registerPlugin(CustomWiggle);

// 使用配置对象
CustomWiggle.create("myWiggle", { wiggles: 6, type: "easeOut" });
gsap.to(".box", { x: 200, duration: 2, ease: "myWiggle" });

// 使用回调（频率：每秒摆动次数）
CustomWiggle.create("customFreq", () => gsap.utils.random(0, 10, 1));

CustomWiggle 关键配置选项：

选项	描述
wiggles	摆动次数（默认：10）
type	"easeIn", "easeOut", "easeInOut"（默认："easeOut"）
amplitude	摆动幅度；值越大摆动幅度越大（默认：1）

CustomBounce

从头开始创建自定义弹跳缓动曲线（不是基于现有曲线）。CustomBounce.create(name, config)。

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { strength: 0.7, endAtStart: false, squash: 1 });
gsap.to(".box", { y: 300, duration: 1.5, ease: "myBounce" });

CustomBounce 关键配置选项：

选项	描述
strength	0–1；每次弹跳的动力/强度（默认：0.7）
endAtStart	当为 true 时，动画在起始点结束（向下然后向上弹跳）；默认 false
squash	压扁效果量（0–1）；默认 1（完全不压扁设为 0）

开发工具

GSDevTools

添加一个 UI 控件面板，用于控制 GSAP 动画的播放、暂停、重启、scrub（擦除）和速度控制。用于调试或向他人展示动画。创建 GSDevTools 实例时，会自动检测作用域内的补间（它们在实例化时存在/已创建）。未检测到的补间可以使用 add() 方法手动添加到实例中。

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { duration: 1, x: 200 });
tl.to(".circle", { duration: 0.5, scale: 2 });

GSDevTools.create({ animation: tl });

了解更多： GSDevTools

相关技能

• gsap-core — 动画化目标、补间、时间线、stagger、回调、实用方法
• gsap-scrolltrigger — 基于滚动的动画、scrub、固定/钉住元素、标记、视口检测
• gsap-react — 使用 GSAP 的 React 模式、useGSAP、refs、严格模式、最佳实践