Back to Details

gsap-plugins

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GSAP Plugins

GSAP 插件

When to Use This Skill

何时使用本技能

Apply when using or reviewing code that uses GSAP plugins: registering plugins, scroll-to, flip/FLIP animations, draggable elements, SVG (DrawSVG, MorphSVG, MotionPath), text (SplitText, ScrambleText), physics, easing plugins (CustomEase, EasePack, CustomWiggle, CustomBounce), or GSDevTools. ScrollTrigger has its own skill (gsap-scrolltrigger).
Related skills: For core tweens use gsap-core; for ScrollTrigger use gsap-scrolltrigger; for React use gsap-react.
当使用或审查涉及GSAP插件的代码时适用：包括插件注册、滚动定位、Flip/FLIP动画、可拖拽元素、SVG（DrawSVG、MorphSVG、MotionPath）、文本动画（SplitText、ScrambleText）、物理动画、缓动插件（CustomEase、EasePack、CustomWiggle、CustomBounce）或GSDevTools。ScrollTrigger有单独的技能（gsap-scrolltrigger）。
相关技能： 核心补间动画使用gsap-core；ScrollTrigger使用gsap-scrolltrigger；React环境使用gsap-react。

Registering Plugins

插件注册

Register each plugin once so GSAP (and bundlers) know to include it. Use gsap.registerPlugin() with every plugin used in the project:
javascript
import gsap from "gsap";
import { ScrollToPlugin } from "gsap/ScrollToPlugin";
import { Flip } from "gsap/Flip";
import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
  • ✅ Register before using the plugin in any tween or API call.
  • ✅ In React, register at top level or once in the app (e.g. before first useGSAP); do not register inside a component that re-renders. useGSAP is a plugin that needs to be registered before use.
每个插件只需注册一次，让GSAP（及打包工具）知晓要包含该插件。项目中使用到的每个插件都需调用gsap.registerPlugin()：
javascript
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是一个插件，使用前也需要注册。

Scroll

滚动相关

ScrollToPlugin

ScrollToPlugin

Animates scroll position (window or a scrollable element). Use for “scroll to element” or “scroll to position” without ScrollTrigger.
javascript
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 — key config (scrollTo object):
OptionDescription
x
, 
y
Target scroll position (number), or 
"max"
for maximum
element
Selector or element to scroll to (for scroll-into-view)
offsetX
, 
offsetY
Offset in pixels from the target position
用于为滚动位置（窗口或可滚动元素）添加动画。适用于无需ScrollTrigger的“滚动到元素”或“滚动到指定位置”场景。
javascript
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
要滚动到的元素选择器或DOM元素（实现滚动到视图内）
offsetX
, 
offsetY
相对于目标位置的偏移量（像素单位）

ScrollSmoother

ScrollSmoother

Smooth scroll wrapper (smooths native scroll). Requires ScrollTrigger and a specific DOM structure (content wrapper + smooth wrapper). Use when smooth, momentum-style scroll is needed. See GSAP docs for setup; register after ScrollTrigger. DOM structure would look like:
html
<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- ALL YOUR CONTENT HERE --->
		</div>
	</div>
	<!-- position: fixed elements can go outside --->
</body>
平滑滚动包装器（优化原生滚动的流畅度）。需要依赖ScrollTrigger和特定的DOM结构（内容容器 + 平滑容器）。适用于需要平滑、带动量效果的滚动场景。设置方法请参考GSAP文档；需在ScrollTrigger之后注册。DOM结构示例：
html
<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- 所有内容放置于此 --->
		</div>
	</div>
	<!-- position: fixed 元素可放置在外部 --->
</body>

DOM / UI

DOM / UI 动画

Flip

Flip

Capture state with 
Flip.getState()
, then apply changes (e.g. layout or class changes), then use 
Flip.from()
to animate from the previous state to the new state (FLIP: First, Last, Invert, Play). Use when animating between two layout states (lists, grids, expanded/collapsed).
javascript
gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// change DOM (reorder, add/remove, change classes)
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
Flip — key config (Flip.from vars):
OptionDescription
absolute
Use 
position: absolute
during the flip (default: 
false
)
nested
When true, only the first level of children is measured (better for nested transforms)
scale
When true, scale elements to fit (avoids stretch); default 
true
simple
When true, only position/scale are animated (faster, less accurate)
duration
, 
ease
Standard tween options
使用
Flip.getState()
捕获元素状态，然后修改DOM（例如布局或类名变化），再通过
Flip.from()
实现从之前状态到新状态的动画过渡（FLIP：First、Last、Invert、Play）。适用于在两种布局状态间切换的动画（如列表、网格、展开/收起效果）。
javascript
gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// 修改DOM（重排、增删元素、改变类名）
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
Flip — 关键配置（Flip.from 参数）：
选项说明
absolute
在Flip动画期间使用
position: absolute
定位（默认值：
false
）
nested
设为true时，仅测量第一级子元素（更适合嵌套变换场景）
scale
设为true时，元素会缩放以适配（避免拉伸变形）；默认值
true
simple
设为true时，仅动画化位置/缩放属性（性能更快，但精度较低）
duration
, 
ease
标准补间动画选项

More information

更多信息

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

Draggable

Draggable

Makes elements draggable, spinnable, or throwable with mouse/touch. Use for sliders, cards, reorderable lists, or any drag interaction.
javascript
gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
Draggable.create(".knob", { type: "rotation" });
Draggable — key config options:
OptionDescription
type
"x"
, 
"y"
, 
"x,y"
, 
"rotation"
, 
"scroll"
bounds
Element, selector, or 
{ minX, maxX, minY, maxY }
to constrain drag
inertia
true
to enable throw/momentum (requires InertiaPlugin)
edgeResistance
0–1; resistance when dragging past bounds
cursor
CSS cursor during drag
onDragStart
, 
onDrag
, 
onDragEnd
Callbacks; receive event and target
onThrowUpdate
, 
onThrowComplete
Callbacks when inertia is active
让元素支持鼠标/触摸拖拽、旋转或抛掷。适用于滑块、卡片、可重排列表或任何拖拽交互场景。
javascript
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)

Inertia (InertiaPlugin)

Works with Draggable for momentum after release, or track the inertia/velocity of any property of any object so that it can then seamlessly glide to a stop using a simple tween. Register with Draggable when using 
inertia: true
:
javascript
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });
Or track velocity of a property:
javascript
InertiaPlugin.track(".box", "x");
Then use 
"auto"
to continue the current velocity and glide to a stop:
javascript
gsap.to(obj, { inertia: { x: "auto" } });
与Draggable配合实现释放后的动量效果，或跟踪任意对象任意属性的惯性/速度，以便通过简单补间动画让其平滑停止。当使用
inertia: true
时，需与Draggable一起注册：
javascript
gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });
或跟踪属性的速度：
javascript
InertiaPlugin.track(".box", "x");
然后使用
"auto"
延续当前速度并平滑停止：
javascript
gsap.to(obj, { inertia: { x: "auto" } });

Observer

Observer

Normalizes pointer and scroll input across devices. Use for swipe, scroll direction, or custom gesture logic without tying directly to scroll position like ScrollTrigger.
javascript
gsap.registerPlugin(Observer);

Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});
Observer — key config options:
OptionDescription
target
Element or selector to observe
onUp
, 
onDown
, 
onLeft
, 
onRight
Callbacks when swipe/scroll passes tolerance in that direction
tolerance
Pixels before direction is detected; default 10
type
"touch"
, 
"pointer"
, or 
"wheel"
(default: 
"touch,pointer"
)
跨设备统一指针和滚动输入处理。适用于滑动、滚动方向检测或自定义手势逻辑，无需像ScrollTrigger那样直接绑定滚动位置。
javascript
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"
）

Text

文本动画

SplitText

SplitText

Splits an element’s text into characters, words, and/or lines (each in its own element) for staggered or per-unit animation. Use when animating text character-by-character, word-by-word, or line-by-line. Returns an instance with chars, words, lines (and masks when 
mask
is set). Restore original markup with revert() or let gsap.context() revert. Integrates with gsap.context(), matchMedia(), and useGSAP(). API: SplitText.create(target, vars) (target = selector, element, or array).
javascript
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 });
// later: split.revert() or let gsap.context() cleanup revert
With onSplit() (v3.13.0+), animations run on each split and on re-split when autoSplit is used; returning a tween/timeline from onSplit() lets SplitText clean up and sync progress on re-split:
javascript
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 — key config (SplitText.create vars):
OptionDescription
typeComma-separated: 
"chars"
, 
"words"
, 
"lines"
. Default 
"chars,words,lines"
. Only split what is needed (e.g. 
"words, chars"
if not using lines) for performance. Avoid chars-only without words/lines or use smartWrap: true to prevent odd line breaks.
charsClass, wordsClass, linesClassCSS class on each split element. Append 
"++"
to add an incremented class (e.g. 
linesClass: "line++"
→ 
line1
, 
line2
, …).
aria
"auto"
(default), 
"hidden"
, or 
"none"
. Accessibility: 
"auto"
adds 
aria-label
on the split element and 
aria-hidden
on line/word/char elements so screen readers read the label; 
"hidden"
hides all from readers; 
"none"
leaves aria unchanged. Use 
"none"
plus a screen-reader-only duplicate if nested links/semantics must be exposed.
autoSplitWhen 
true
, reverts and re-splits when fonts finish loading or when the element width changes (and lines are split), avoiding wrong line breaks. Animations must be created inside onSplit() so they target the newly split elements; return the animation from onSplit() for automatic cleanup and time-sync on re-split.
onSplit(self)Callback when split completes (and on each re-split if autoSplit is 
true
). Receives the SplitText instance. Returning a GSAP tween or timeline enables automatic revert/sync of that animation when re-splitting.
mask
"lines"
, 
"words"
, or 
"chars"
. Wraps each unit in an extra element with 
overflow: clip
for mask/reveal effects. Only one type; access wrappers on the instance’s masks array (or use class 
-mask
if a class is set).
tagWrapper element tag; default 
"div"
. Use 
"span"
for inline (note: transforms like rotation/scale may not render on inline elements in some browsers).
deepSliceWhen 
true
(default), nested elements (e.g. 
<strong>
) that span multiple lines are subdivided so lines don’t stretch vertically. Only applies when splitting lines.
ignoreSelector or element(s) to leave unsplit (e.g. 
ignore: "sup"
).
smartWrapWhen splitting chars only, wraps words in a 
white-space: nowrap
span to avoid mid-word line breaks. Ignored if words or lines are split. Default 
false
.
wordDelimiterWord boundary: string (default 
" "
), RegExp, or 
{ delimiter: RegExp, replaceWith: string }
for custom splitting (e.g. zero-width joiner for hashtags, or non-Latin).
prepareText(text, parent)Function that receives raw text and parent element; return modified text before splitting (e.g. to insert break markers for languages without spaces).
propIndexWhen 
true
, adds a CSS variable with index on each split element (e.g. 
--word: 1
, 
--char: 2
).
reduceWhiteSpaceCollapse consecutive spaces; default 
true
. From v3.13.0 also honors line breaks and can insert 
<br>
for 
<pre>
.
onRevertCallback when the instance is reverted.
Tips: Split only what is animated (e.g. skip chars if only animating words). For custom fonts, split after they load (e.g. 
document.fonts.ready.then(...)
) or use autoSplit: true with onSplit(). To avoid kerning shift when splitting chars, use CSS 
font-kerning: none; text-rendering: optimizeSpeed;
. Avoid 
text-wrap: balance
; it can interfere with splitting. SplitText does not support SVG 
<text>
.
Learn more: SplitText
将元素文本拆分为字符、单词和/或行（每个单元独立成元素），用于实现 stagger 动画或逐单元动画。适用于需要逐字符、逐单词或逐行动画文本的场景。返回的实例包含chars、words、lines属性（当设置
mask
时还包含masks）。可通过revert()方法恢复原始标记，或由gsap.context()自动恢复。支持与gsap.context()、**matchMedia()和useGSAP()**集成。API：SplitText.create(target, vars)（target为选择器、元素或数组）。
javascript
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() 自动清理恢复
从v3.13.0版本开始，使用**onSplit()时，动画会在每次拆分（包括
autoSplit
触发的重新拆分）时运行；从onSplit()**返回补间动画或时间线，可让SplitText在重新拆分时自动清理并同步进度：
javascript
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()内部创建，以确保目标是新拆分的元素；返回动画实例可让SplitText在重新拆分时自动清理并同步时间进度。
onSplit(self)拆分完成时触发的回调函数（若
autoSplit
为true，每次重新拆分也会触发）。接收SplitText实例作为参数。返回GSAP补间动画或时间线可实现重新拆分时的自动恢复/同步。
mask可选项：
"lines"
, 
"words"
, 或
"chars"
。为每个单元额外包裹一个
overflow: clip
的元素，用于实现遮罩/ Reveal 效果。仅支持一种类型；可通过实例的masks数组访问包装元素（或通过设置的类名加
-mask
后缀访问）。
tag包裹元素的标签名；默认值为
"div"
。若需行内元素可使用
"span"
（注意：部分浏览器中行内元素可能无法渲染旋转/缩放等变换）。
deepSlice设为true（默认）时，会将跨多行的嵌套元素（例如
<strong>
）拆分，避免行高拉伸。仅在拆分行时生效。
ignore不需要拆分的元素选择器或DOM元素（例如
ignore: "sup"
）。
smartWrap当仅拆分chars时，会将单词包裹在
white-space: nowrap
的span元素中，避免单词被拆分换行。若拆分了单词或行则该选项无效。默认值为
false
。
wordDelimiter单词分隔符：字符串（默认
" "
）、正则表达式，或
{ 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

ScrambleText

Animates text with a scramble/glitch effect. Use when revealing or transitioning text with a scramble.
javascript
gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});
为文本添加乱码/故障艺术风格的动画。适用于以乱码效果揭示或过渡文本的场景。
javascript
gsap.registerPlugin(ScrambleTextPlugin);

gsap.to(".text", {
  duration: 1,
  scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
});

SVG

SVG 动画

DrawSVG (DrawSVGPlugin)

DrawSVG (DrawSVGPlugin)

Reveals or hides the stroke of SVG elements by animating 
stroke-dashoffset
/ 
stroke-dasharray
. Works on 
<path>
, 
<line>
, 
<polyline>
, 
<polygon>
, 
<rect>
, 
<ellipse>
. Use when “drawing” or “erasing” strokes.
drawSVG value: Describes the visible segment of the stroke along the path (start and end positions), not “animate from A to B over time.” Format: 
"start end"
in percent or length. Examples: 
"0% 100%"
= full stroke; 
"20% 80%"
= stroke only between 20% and 80% (gaps at both ends). The tween animates from the element’s current segment to the target segment — e.g. 
gsap.to("#path", { drawSVG: "0% 100%" })
goes from whatever it is now to full stroke. Single value (e.g. 
0
, 
"100%"
) means start is 0: 
"100%"
is equivalent to 
"0% 100%"
.
Required: The element must have a visible stroke — set 
stroke
and 
stroke-width
in CSS or as SVG attributes; otherwise nothing is drawn.
javascript
gsap.registerPlugin(DrawSVGPlugin);

// draw from nothing to full stroke
gsap.from("#path", { duration: 1, drawSVG: 0 });
// or explicit segment: from 0–0 to 0–100%
gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
// stroke only in the middle (gaps at ends)
gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
Caveats: Only affects stroke (not fill). Prefer single-segment 
<path>
elements; multi-segment paths can render oddly in some browsers. Contents of 
<use>
cannot be visually changed. DrawSVGPlugin.getLength(element) and DrawSVGPlugin.getPosition(element) return stroke length and current position.
Learn more: DrawSVG
通过动画
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
，否则不会有任何绘制效果。
javascript
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)

MorphSVG (MorphSVGPlugin)

Morphs one SVG shape into another by animating the 
d
attribute (path data). Start and end shapes do not need the same number of points — MorphSVG converts to cubic beziers and adds points as needed. Use for icon-to-icon morphs, shape transitions, or path-based animations. Works on 
<path>
, 
<polyline>
, and 
<polygon>
; 
<circle>
, 
<rect>
, 
<ellipse>
, and 
<line>
are converted internally or via MorphSVGPlugin.convertToPath(selector | element) (replaces the element in the DOM with a 
<path>
).
morphSVG value: Can be a selector (e.g. 
"#lightning"
), an element, raw path data (e.g. 
"M47.1,0.8 73.3,0.8..."
), or for polygon/polyline a points string (e.g. 
"240,220 240,70 70,70 70,220"
). For full config use the object form with shape as the only required property.
javascript
gsap.registerPlugin(MorphSVGPlugin);

// convert primitives to path first if needed:
MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");

gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
// object form:
gsap.to("#diamond", {
  duration: 1,
  morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
});
MorphSVG — key config (morphSVG object):
OptionDescription
shape(Required.) Target shape: selector, element, or raw path string.
type
"linear"
(default) or 
"rotational"
. Rotational uses angle/length interpolation and can avoid kinks mid-morph; try it when linear looks wrong.
mapHow segments are matched: 
"size"
(default), 
"position"
, or 
"complexity"
. Use when start/end segments don’t line up; if none work, split into multiple paths and morph each.
shapeIndexOffsets which point in the start path maps to the first point in the end path (avoids shape “crossing over” or inverting). Number for single-segment paths; array for multi-segment (e.g. 
[5, 1, -8]
). Negative reverses that segment. Use shapeIndex: "log" once to log the auto-calculated value, then paste the number/array into the tween. findShapeIndex(start, end) (separate utility) provides an interactive UI to find a good value. Only applies to closed paths.
smooth(v3.14+). Adds smoothing points. Number (e.g. 
80
), 
"auto"
, or object: 
{ points: 40 | "auto", redraw: true | false, persist: true | false }
. 
redraw: false
keeps original anchors (perfect fidelity, less even spacing). 
persist: false
removes added points when the tween ends. Use when the default morph looks jagged or unnatural.
curveModeBoolean (v3.14+). Interpolates control-handle angle/length instead of raw x/y to avoid kinks on curves. Try if a morph has a mid-morph kink.
originRotation origin for type: "rotational". String: 
"50% 50%"
(default) or 
"20% 60%, 35% 90%"
for different start/end origins.
precisionDecimal places for output path data; default 
2
.
precompileArray of precomputed path strings (or use precompile: "log" once, copy from console). Skips expensive startup calculations; use for very complex morphs. Only for 
<path>
(convert polygon/polyline first).
renderFunction(rawPath, target) called each update — e.g. draw to canvas. RawPath is an array of segments (each segment = array of alternating x,y cubic bezier coords).
updateTargetWhen using render (e.g. canvas-only), set updateTarget: false so the original 
<path>
is not updated. MorphSVGPlugin.defaultUpdateTarget sets default.
Utilities: MorphSVGPlugin.convertToPath(selector | element) converts circle/rect/ellipse/line/polygon/polyline to 
<path>
in the DOM. MorphSVGPlugin.rawPathToString(rawPath) and stringToRawPath(d) convert between path strings and raw arrays. The plugin stores the original 
d
on the target (e.g. for tweening back: 
morphSVG: "#originalId"
or the same element).
Tips: For twisted or inverted morphs, set shapeIndex (use 
"log"
or findShapeIndex()). For multi-segment paths, shapeIndex is an array (one value per segment). Precompile only when the first frame is slow; it does not fix jank during the tween (simplify the SVG or reduce size if needed).
Learn more: MorphSVG
通过动画
d
属性（路径数据）实现一个SVG形状到另一个形状的变形。起始和结束形状无需拥有相同数量的顶点——MorphSVG会将其转换为三次贝塞尔曲线并按需添加顶点。适用于图标变形、形状过渡或基于路径的动画场景。支持
<path>
、
<polyline>
和
<polygon>
元素；
<circle>
、
<rect>
、
<ellipse>
和
<line>
元素会被内部转换，或通过**MorphSVGPlugin.convertToPath(selector | element)**方法转换（会将DOM中的元素替换为
<path>
）。
morphSVG 值： 可以是选择器（例如
"#lightning"
）、DOM元素、原始路径数据（例如
"M47.1,0.8 73.3,0.8..."
），或针对多边形/折线的顶点字符串（例如
"240,220 240,70 70,70 70,220"
）。若需完整配置，可使用对象形式，其中shape为必填属性。
javascript
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（必填） 目标形状：选择器、DOM元素或原始路径字符串。
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)——例如绘制到Canvas。rawPath是线段数组（每个线段为交替的x,y三次贝塞尔坐标数组）。
updateTarget当使用render（例如仅Canvas绘制）时，设为updateTarget: false可避免修改原始
<path>
元素。MorphSVGPlugin.defaultUpdateTarget可设置全局默认值。
工具方法： **MorphSVGPlugin.convertToPath(selector | element)**可将circle/rect/ellipse/line/polygon/polyline转换为DOM中的
<path>
元素。**MorphSVGPlugin.rawPathToString(rawPath)和stringToRawPath(d)**方法可在路径字符串和原始数组之间转换。插件会在目标元素上存储原始的
d
属性（例如可通过
morphSVG: "#originalId"
或同一元素实现反向变形）。
提示： 若变形出现扭曲或反转，设置shapeIndex（使用
"log"
或findShapeIndex()工具）。多线段路径需使用数组形式的shapeIndex（每个线段对应一个值）。仅在首帧加载缓慢时使用预编译；它无法解决动画过程中的卡顿问题（若卡顿需简化SVG或缩小尺寸）。
更多信息： MorphSVG

MotionPath (MotionPathPlugin)

MotionPath (MotionPathPlugin)

Animates an element along an SVG path. Use when moving an object along a path (e.g. a curve or custom route).
javascript
gsap.registerPlugin(MotionPathPlugin);

gsap.to(".dot", {
  duration: 2,
  motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] }
});
MotionPath — key config (motionPath object):
OptionDescription
path
SVG path element, selector, or path data string
align
Path element or selector to align the target to
alignOrigin
[x, y]
origin (0–1); default 
[0.5, 0.5]
autoRotate
Rotate element to follow path tangent
curviness
0–2; path smoothing
让元素沿SVG路径运动。适用于让对象沿路径（例如曲线或自定义路线）移动的场景。
javascript
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

MotionPathHelper

Visual editor for MotionPath (alignment, offset). Use during development to tune path alignment.
javascript
gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);

const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
// adjust in UI, then use helper.path or helper.getProgress() in your animation
MotionPath的可视化编辑器（用于调整对齐、偏移）。适用于开发阶段调优路径对齐效果。
javascript
gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);

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

Easing

缓动效果

CustomEase

CustomEase

Custom easing curves (cubic-bezier or SVG path). Use when a built-in ease is not enough. Basic usage is covered in gsap-core; register when using:
javascript
gsap.registerPlugin(CustomEase);
const ease = CustomEase.create("name", ".17,.67,.83,.67");
gsap.to(".el", { x: 100, ease: ease, duration: 1 });
自定义缓动曲线（贝塞尔曲线或SVG路径）。适用于内置缓动效果无法满足需求的场景。基础用法可参考gsap-core；使用时需注册：
javascript
gsap.registerPlugin(CustomEase);
const ease = CustomEase.create("name", ".17,.67,.83,.67");
gsap.to(".el", { x: 100, ease: ease, duration: 1 });

EasePack

EasePack

Adds more named eases (e.g. SlowMo, RoughEase, ExpoScaleEase). Register and use the ease names in tweens.
添加更多命名缓动效果（例如SlowMo、RoughEase、ExpoScaleEase）。注册后可在补间动画中直接使用这些缓动名称。

CustomWiggle

CustomWiggle

Wiggle/shake easing. Use when a value should “wiggle” (multiple oscillations).
摆动/抖动风格的缓动效果。适用于让值产生“摆动”效果（多次振荡）的场景。

CustomBounce

CustomBounce

Bounce-style easing with configurable strength.
可配置强度的弹跳风格缓动效果。

Physics

物理动画

Physics2D (Physics2DPlugin)

Physics2D (Physics2DPlugin)

2D physics (velocity, angle, gravity). Use when animating with simple physics (e.g. projectiles, bouncing).
javascript
gsap.registerPlugin(Physics2DPlugin);

gsap.to(".ball", {
  duration: 2,
  physics2D: {
    velocity: 250,
    angle: 80,
    gravity: 500
  }
});
2D物理效果（速度、角度、重力）。适用于模拟简单物理的动画场景（例如抛射物、弹跳效果）。
javascript
gsap.registerPlugin(Physics2DPlugin);

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

PhysicsProps (PhysicsPropsPlugin)

PhysicsProps (PhysicsPropsPlugin)

Applies physics to property values. Use for physics-driven property animation.
javascript
gsap.registerPlugin(PhysicsPropsPlugin);

gsap.to(".obj", {
  duration: 2,
  physicsProps: {
    x: { velocity: 100, end: 300 },
    y: { velocity: -50, acceleration: 200 }
  }
});
为属性值应用物理效果。适用于基于物理驱动的属性动画场景。
javascript
gsap.registerPlugin(PhysicsPropsPlugin);

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

Development

开发工具

GSDevTools

GSDevTools

UI for scrubbing timelines, toggling animations, and debugging. Use during development only; do not ship. Register and create an instance with a timeline reference.
javascript
gsap.registerPlugin(GSDevTools);
GSDevTools.create({ animation: tl });
用于 scrub 时间线、切换动画和调试的UI工具。仅适用于开发阶段；请勿部署到生产环境。注册后需传入时间线实例创建：
javascript
gsap.registerPlugin(GSDevTools);
GSDevTools.create({ animation: tl });

Other

其他插件

Pixi (PixiPlugin)

Pixi (PixiPlugin)

Integrates GSAP with PixiJS for animating Pixi display objects. Register when animating Pixi objects with GSAP.
javascript
gsap.registerPlugin(PixiPlugin);

const sprite = new PIXI.Sprite(texture);
gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });
将GSAP与PixiJS集成，用于动画Pixi显示对象。当使用GSAP动画Pixi对象时需注册。
javascript
gsap.registerPlugin(PixiPlugin);

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

Best practices

最佳实践

  • ✅ Register every plugin used with gsap.registerPlugin() before first use.
  • ✅ Use Flip.getState() → DOM change → Flip.from() for layout transitions; use Draggable + InertiaPlugin for drag with momentum.
  • ✅ Revert plugin instances (e.g. 
    SplitTextInstance.revert()
    ) when components unmount or elements are removed.
  • ✅ 使用**gsap.registerPlugin()**注册所有用到的插件，且需在首次使用前完成注册。
  • ✅ 布局过渡使用Flip.getState() → 修改DOM → Flip.from()的流程；带动量的拖拽效果使用Draggable + InertiaPlugin。
  • ✅ 当组件卸载或元素被移除时，恢复插件实例（例如
    SplitTextInstance.revert()
    ）。

Do Not

禁忌操作

  • ❌ Use a plugin in a tween or API without registering it first (gsap.registerPlugin()).
  • ❌ Ship GSDevTools or development-only plugins to production.
  • ❌ 在未注册插件（未调用gsap.registerPlugin()）的情况下，在补间动画或API中使用该插件。
  • ❌ 将GSDevTools或仅开发阶段使用的插件部署到生产环境。

Learn More

更多学习资源

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