gsap-plugins

GSAP Plugins 是一个关于 GSAP 官方插件的技能说明，适用于使用或审查涉及 GSAP 插件的代码场景，包括：注册插件、滚动到指定位置、FLIP 动画、拖拽元素、SVG（DrawSVG、MorphSVG、MotionPath）、文本（SplitText、ScrambleText）、物理效果、缓动插件（CustomEase、EasePack、CustomWiggle、CustomBounce）以及 GSDevTools。ScrollTrigger 有独立技能（gsap-scrolltrigger）。相关技能：核心补间使用 gsap-core；React 场景使用 gsap-react。

一、插件注册每个插件只需注册一次，以便 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：为滚动位置（window 或可滚动元素）添加动画。用于不使用 ScrollTrigger 的“滚动到元素”或“滚动到指定位置”。配置项包括 x、y（目标位置数字，或 "max"）、element（选择器或元素）、offsetX、offsetY。示例：

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" } });

ScrollSmoother：平滑滚动包装器，要求 ScrollTrigger 和特定 DOM 结构（内容包装器 + 平滑包装器），在 ScrollTrigger 之后注册。DOM 结构示例：

<body>
	<div id="smooth-wrapper">
		<div id="smooth-content">
			<!--- ALL YOUR CONTENT HERE --->
		</div>
	</div>
	<!-- position: fixed elements can go outside -->
</body>

三、DOM / UI 相关

Flip：用 Flip.getState() 捕获状态，应用更改后用 Flip.from() 从旧状态动画到新状态（FLIP：First、Last、Invert、Play）。适用于列表、网格、展开/折叠等布局状态之间的动画。配置项包括 absolute、nested、scale、simple、duration、ease。示例：

gsap.registerPlugin(Flip);
const state = Flip.getState(".item");
// change DOM
Flip.from(state, { duration: 0.5, ease: "power2.inOut" });

Draggable：使元素可拖拽、旋转或抛出。适用于滑块、卡片、可重排列表等拖拽交互。配置项包括 type（"x"、"y"、"x,y"、"rotation"、"scroll"）、bounds、inertia、edgeResistance、cursor、onDragStart、onDrag、onDragEnd、onThrowUpdate、onThrowComplete。示例：

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });

Inertia（InertiaPlugin）：与 Draggable 配合实现释放后的惯性，或追踪任意对象属性的速度。示例：

gsap.registerPlugin(Draggable, InertiaPlugin);
Draggable.create(".box", { type: "x,y", inertia: true });
InertiaPlugin.track(".box", "x");
gsap.to(obj, { inertia: { x: "auto" } });

Observer：跨设备统一指针与滚动输入，用于滑动、滚动方向或自定义手势逻辑。配置项包括 target、onUp、onDown、onLeft、onRight、tolerance、type。示例：

gsap.registerPlugin(Observer);
Observer.create({
  target: "#area",
  onUp: () => {},
  onDown: () => {},
  onLeft: () => {},
  onRight: () => {},
  tolerance: 10
});

四、文本相关

SplitText：将元素文本拆分为字符、单词和/或行（各自独立元素），以便错开或逐单位动画。返回带有 chars、words、lines（以及 mask 时的 masks）的实例，用 revert() 还原原始标记。API：SplitText.create(target, vars)。配置项包括 type、charsClass/wordsClass/linesClass、aria、autoSplit、onSplit(self)、mask、tag、deepSlice、ignore、smartWrap、wordDelimiter、prepareText(text, parent)、propIndex、reduceWhiteSpace、onRevert。示例：

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 });

提示：只拆分要动画的部分；自定义字体应在加载后拆分（如 document.fonts.ready.then(...)）或使用 autoSplit: true 配合 onSplit()；拆分字符时如出现字距偏移，可使用 CSS font-kerning: none; text-rendering: optimizeSpeed;；避免 text-wrap: balance;。SplitText 不支持 SVG <text>。

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 元素描边，适用于“绘制”或“擦除”描边。drawSVG 值描述描边的可见段（起止位置），格式为 "start end"（百分比或长度）。元素必须有可见描边（设置 stroke 和 stroke-width），否则不会绘制。示例：

gsap.registerPlugin(DrawSVGPlugin);
gsap.from("#path", { duration: 1, drawSVG: 0 });
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) 可返回描边长度和当前位置。

MorphSVG（MorphSVGPlugin）：通过动画 d 属性将一种 SVG 形状变形为另一种。起点和终点形状无需点数相同。适用于图标变形、形状过渡或基于路径的动画。配置项包括 shape（必填）、type（"linear" 或 "rotational"）、map、shapeIndex、smooth、curveMode、origin、precision、precompile、render、updateTarget。工具方法：convertToPath、rawPathToString、stringToRawPath。示例：

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 }
});

提示：变形扭曲或反转时可设置 shapeIndex（用 "log" 或 findShapeIndex()）；多段路径的 shapeIndex 为数组；precompile 仅用于首帧较慢的情况。

MotionPath（MotionPathPlugin）：让元素沿 SVG 路径移动。配置项包括 path、align、alignOrigin、autoRotate、curviness。示例：

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

MotionPathHelper：MotionPath 的可视化编辑器（用于对齐、偏移），在开发期间使用。原资料在此处截断，后续内容暂未提供。

技能介绍