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() 捕捉狀態，然後套用變更（例如佈局或 class 變更），再使用 Flip.from() 從先前的狀態動畫到新狀態（FLIP：First、Last、Invert、Play）。用於在兩個佈局狀態之間動畫（列表、網格、展開/收合）。

gsap.registerPlugin(Flip);

const state = Flip.getState(".item");
// 變更 DOM（重新排序、新增/移除、變更 class）
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"`）以提升效能。避免僅 chars 而沒有 words/lines，或使用 smartWrap: true 以防止異常換行。
charsClass, wordsClass, linesClass	每個分割元素的 CSS class。附加 `"++"` 可加入遞增的 class（例如 `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 陣列存取包裝器（如果設定了 class，則使用 class `-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 }` 用於自訂分割（例如零寬度連字用於 hashtag，或非拉丁語系）。
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()。為避免分割字元時的字距偏移，使用 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,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>`（先轉換 polygon/polyline）。
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）

沿著 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

自訂緩動曲線（cubic-bezier 或 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 顯示物件。在動畫化 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/

您可能也喜歡

prompt-optimizer

230Kfrontend

Analyze raw prompts, identify intent and gaps, match ECC components (skills/commands/agents/hooks), and output a ready-to-paste optimized prompt. Advisory role only — never executes the task itself. TRIGGER when: user says "optimize prompt", "improve my prompt", "how to write a prompt for", "help me prompt", "rewrite this prompt", or explicitly asks to enhance prompt quality. Also triggers on Chinese equivalents: "优化prompt", "改进prompt", "怎么写prompt", "帮我优化这个指令". DO NOT TRIGGER when: user wants the task executed directly, or says "just do it" / "直接做". DO NOT TRIGGER when user says "优化代码", "优化性能", "optimize performance", "optimize this code" — those are refactoring/performance tasks, not prompt optimization.

affaan-m

獲取

frontend-code-review

149Kfrontend

Review Dify frontend code for correctness, accessibility, component design, dify-ui usage, data/query boundaries, performance, and tests. Trigger for `.tsx`, `.ts`, `.js`, UI, React, Next.js, pending-change, or focused frontend review requests.

langgenius

獲取

design-system

106Kfrontend

Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables, spacing/typography scales, component specs, strategic slide creation. Use for design tokens, systematic design, brand-compliant presentations.

nextlevelbuilder

獲取

繼續探索

瀏覽 frontend 熱門 Skills 最近更新