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`	标准补间选项

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"`）以提高性能。避免仅拆分字符而不拆分单词/行，或使用 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 中，以避免单词中间换行。如果拆分单词或行则忽略。默认 `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: "新消息", 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..."），或对于多边形/折线是点字符串（例如 "240,220 240,70 70,70 70,220"）。对于完整配置，使用对象形式，其中 shape 是唯一必需的属性。

gsap.registerPlugin(MorphSVGPlugin);

// 如果需要，首先将基本形状转换为路径：
MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");

gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
// 对象形式：
gsap.to("#diamond", {
  duration: 1,
  morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
});

MorphSVG — 关键配置（morphSVG 对象）：

选项	描述
shape	(必需。) 目标形状：选择器、元素或原始路径字符串。
type	`"linear"`（默认）或 `"rotational"`。旋转使用角度/长度插值，可以避免变形中途的扭结；当线性看起来不对时尝试。
map	段如何匹配：`"size"`（默认）、`"position"` 或 `"complexity"`。当起始/结束段不对齐时使用；如果都不起作用，则拆分为多个路径并分别变形。
shapeIndex	偏移起始路径中的哪个点映射到结束路径中的第一个点（避免形状“交叉”或反转）。单段路径的数字；多段路径的数组（例如 `[5, 1, -8]`）。负值反转该段。使用 shapeIndex: "log" 一次以记录自动计算的值，然后将数字/数组粘贴到补间中。findShapeIndex(start, end)（单独实用程序）提供交互式 UI 以找到好的值。仅适用于闭合路径。
smooth	（v3.14+）。添加平滑点。数字（例如 `80`）、`"auto"` 或对象：`{ points: 40 \| "auto", redraw: true \| false, persist: true \| false }`。`redraw: false` 保留原始锚点（完美保真度，间距不太均匀）。`persist: false` 在补间结束时移除添加的点。当默认变形看起来锯齿状或不自然时使用。
curveMode	布尔值（v3.14+）。插值控制手柄角度/长度而不是原始 x/y，以避免曲线上的扭结。如果变形有中途扭结，请尝试。
origin	type: "rotational" 的旋转原点。字符串：`"50% 50%"`（默认）或 `"20% 60%, 35% 90%"` 用于不同的起始/结束原点。
precision	输出路径数据的小数位数；默认 `2`。
precompile	预计算路径字符串数组（或使用 precompile: "log" 一次，从控制台复制）。跳过昂贵的启动计算；用于非常复杂的变形。仅适用于 `<path>`（首先转换多边形/折线）。
render	每次更新时调用的函数(rawPath, target)——例如绘制到画布。RawPath 是段数组（每个段 = 交替 x,y 三次贝塞尔坐标的数组）。
updateTarget	使用 render 时（例如仅画布），设置 updateTarget: false 以便不更新原始 `<path>`。MorphSVGPlugin.defaultUpdateTarget 设置默认值。

实用程序： MorphSVGPlugin.convertToPath(selector | element) 在 DOM 中将 circle/rect/ellipse/line/polygon/polyline 转换为 <path>。MorphSVGPlugin.rawPathToString(rawPath) 和 stringToRawPath(d) 在路径字符串和原始数组之间转换。插件在目标上存储原始 d（例如，用于补间返回：morphSVG: "#originalId" 或同一元素）。

提示： 对于扭曲或反转的变形，设置 shapeIndex（使用 "log" 或 findShapeIndex()）。对于多段路径，shapeIndex 是一个数组（每段一个值）。仅当第一帧慢时才预编译；它不会修复补间期间的卡顿（如果需要，简化 SVG 或减小大小）。

了解更多： MorphSVG

MotionPath（MotionPathPlugin）

沿 SVG 路径动画化元素。用于沿路径移动对象（例如曲线或自定义路线）。

gsap.registerPlugin(MotionPathPlugin);

gsap.to(".dot", {
  duration: 2,
  motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] }
});

MotionPath — 关键配置（motionPath 对象）：

选项	描述
`path`	SVG 路径元素、选择器或路径数据字符串
`align`	用于对齐目标的路径元素或选择器
`alignOrigin`	`[x, y]` 原点（0–1）；默认 `[0.5, 0.5]`
`autoRotate`	旋转元素以跟随路径切线
`curviness`	0–2；路径平滑度

MotionPathHelper

MotionPath 的视觉编辑器（对齐、偏移）。在开发期间用于调整路径对齐。

gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);

const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
// 在 UI 中调整，然后在动画中使用 helper.path 或 helper.getProgress()

缓动

CustomEase

自定义缓动曲线（三次贝塞尔或 SVG 路径）。当内置缓动不够时使用。基本用法在 gsap-core 中介绍；使用时注册：

gsap.registerPlugin(CustomEase);
const ease = CustomEase.create("name", ".17,.67,.83,.67");
gsap.to(".el", { x: 100, ease: ease, duration: 1 });

EasePack

添加更多命名缓动（例如 SlowMo、RoughEase、ExpoScaleEase）。注册并在补间中使用缓动名称。

CustomWiggle

摆动/抖动缓动。当值应该“摆动”（多次振荡）时使用。

CustomBounce

具有可配置强度的弹跳式缓动。

物理

Physics2D（Physics2DPlugin）

2D 物理（速度、角度、重力）。当使用简单物理动画化时使用（例如抛射体、弹跳）。

gsap.registerPlugin(Physics2DPlugin);

gsap.to(".ball", {
  duration: 2,
  physics2D: {
    velocity: 250,
    angle: 80,
    gravity: 500
  }
});

PhysicsProps（PhysicsPropsPlugin）

将物理应用于属性值。用于物理驱动的属性动画。

gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(".obj", {
  duration: 2,
  physicsProps: {
    x: { velocity: 100, end: 300 },
    y: { velocity: -50, acceleration: 200 }
  }
});

开发

GSDevTools

用于擦洗时间线、切换动画和调试的 UI。仅在开发期间使用；不要发布。注册并使用时间线引用创建实例。

gsap.registerPlugin(GSDevTools);
GSDevTools.create({ animation: tl });

其他

Pixi（PixiPlugin）

将 GSAP 与 PixiJS 集成，用于动画化 Pixi 显示对象。当使用 GSAP 动画化 Pixi 对象时注册。

gsap.registerPlugin(PixiPlugin);

const sprite = new PIXI.Sprite(texture);
gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });

最佳实践

✅ 在首次使用前使用 gsap.registerPlugin() 注册每个使用的插件。
✅ 使用 Flip.getState() → DOM 更改 → Flip.from() 进行布局过渡；使用 Draggable + InertiaPlugin 进行带动量的拖拽。
✅ 当组件卸载或元素被移除时，恢复插件实例（例如 SplitTextInstance.revert()）。

不要

❌ 在未先注册插件的情况下在补间或 API 中使用插件（gsap.registerPlugin()）。
❌ 将 GSDevTools 或仅开发插件发布到生产环境。

了解更多

https://gsap.com/docs/v3/Plugins/

你可能还喜欢

nextjs-turbopack

239Kfrontend

Next.js 16+ and Turbopack — incremental bundling, FS caching, dev speed, and when to use Turbopack vs webpack.

affaan-m

获取

fix

247Kfrontend

当出现 Lint 报错、代码格式问题，或在提交代码前确保能顺利通过 CI 时使用。

facebook

获取

motion-advanced

237Kfrontend

React / Next.js 高阶动效设计模式——涵盖拖拽交互、手势操作、文本动画、SVG 路径绘制、自定义 Hook、命令式序列动画（useAnimate）、加载器（Loaders）及完整的 API 选型决策树。需先配置 motion-foundations。