GSAP 外掛整合包

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 不再是付費方案，沒有任何外掛需要會員資格、授權金鑰或認證令牌——這包括過去僅限俱樂部的外掛（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 vars）：

選項	說明
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 vars）：

選項	說明
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 中，以避免單字中間換行。如果分割單字或行則忽略。預設 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	實例被還原時的回呼。

提示： 僅分割需要動畫的部分（例如如果只動畫單字則跳過 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: "新訊息", chars: "01", revealDelay: 0.5 }
});

SVG

DrawSVG（DrawSVGPlugin）

透過動畫化 stroke-dashoffset / stroke-dasharray 來揭示或隱藏 SVG 元素的描邊。適用於 <path>、<line>、<polyline>、<polygon>、<rect>、<ellipse>。用於「繪製」或「擦除」描邊。

drawSVG 值： 描述沿著路徑的可見描邊片段（起點和終點位置），而不是「隨著時間從 A 動畫到 B」。格式: "起點 終點"（百分比或長度）。範例: "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..."），或對於 polygon/polyline 可以是點字串（例如 "240,220 240,..."）。

• shapeIndex（用於路徑或選擇器樣本）: 選擇用來比較的起始形狀的索引，以決定如何將點從起始映射到結束（預設 "logical"）。
• 0 使用具有最多點的路徑；1、2 等選擇特定的起始形狀。"logical"（預設）在可能的情況下智慧匹配，否則退回到 0。

gsap.registerPlugin(MorphSVGPlugin);

// 將一個路徑變形為另一個
gsap.to("#moon", { morphSVG: "#sun", duration: 1 });

// 或使用序列中的特定 shapeIndex

gsap.to("#moon", { morphSVG: { shape: "#sun", shapeIndex: 2 }, duration: 1 });

了解更多： MorphSVG

MotionPath

沿著動作路徑（SVG 路徑）動畫化元素——不需手動設定曲線貝塞爾或計算位置；MotionPath 會處理所有轉換。使用 path 屬性指向 SVG <path> 元素（選擇器或元素）或路徑資料陣列。

import { MotionPathPlugin } from "gsap/MotionPathPlugin";
gsap.registerPlugin(MotionPathPlugin);

gsap.to("#rocket", { motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5], autoRotate: true, start: 0, end: 1 }, duration: 3 });

路徑選擇： 字串（.path-cls、#path-id、元素）或路徑資料陣列。align 將元素對齊到路徑（可選）。alignOrigin 設置元素的對齊點（預設 [0.5, 0.5] 為中心）。autoRotate 使元素面向路徑方向。start / end 定義路徑的進入/退出百分比（0 - 1）。

了解更多： MotionPath

物理

Physics2D

使用物理屬性（速度、加速度、角度、摩擦力）對 2D 空間中的元素進行動畫，以創造自然運動。可用 track 來追蹤物體態並讓動畫順暢地從先前的交互中流動。PhysicsPropsPlugin（與 Physics2D 相同的文檔）為任何數字屬性添加物理特性，不僅限於 2D 空間。

gsap.registerPlugin(Physics2DPlugin, PhysicsPropsPlugin);

gsap.to("#particle", {
  physics2D: { velocity: 500, angle: 45, gravity: 200, friction: 0.1 }
});

// PhysicsProps — 為任何屬性添加物理
gsap.to("#box", {
  physicsProps: { x: { velocity: 200, acceleration: 50 }, rotation: { velocity: 10 } }
});

Physics2D — 關鍵配置

選項	說明
velocity	初始速度（像素/秒）
angle	運動角度（度）
gravity	重力（像素/秒²）
friction	摩擦力（0 = 無摩擦, 1 = 立即停止）
acceleration	加速度（像素/秒²，沿角度方向）

了解更多： Physics2D / PhysicsProps

緩動效果

CustomEase

透過在 GSAP 的 ease 特殊屬性中提供自訂 SVG 路徑或函數來建立自訂緩動曲線。路徑必須是尺寸為 100×100 的立方貝塞爾曲線。

gsap.registerPlugin(CustomEase);

CustomEase.create("myCustomEase", "M0,0 C0.2,0 0.4,1 1,1");
gsap.to(".box", { duration: 1, ease: "myCustomEase", x: 200 });

EasePack

提供額外的緩動函數，如 "slow(0.7, 0.7)"（在中間創建鬆弛效果）、"rough" 和 CustomBounce。可以在 ease 中作為字串或 GSAP 更新的 ease 屬性使用。使用 EasePack 時，會得到: SlowMo、SteppedEase、RoughEase 和 ExpoScaleEase。

gsap.registerPlugin(EasePack);
gsap.to(".box", { duration: 2, ease: "slow(0.7, 0.7)", x: 400 });
gsap.to(".box", { duration: 2, ease: "rough({strength: 0.5, points: 20, template: 'none'})", x: 400 });

CustomWiggle

建立自訂的擺動緩動曲線。

gsap.registerPlugin(CustomWiggle);

CustomWiggle.create("myWiggle", { wiggles: 7, type: "easeOut" });
gsap.to(".box", { duration: 2, ease: "myWiggle", x: 200 });

CustomBounce

建立自訂的彈跳緩動曲線。

gsap.registerPlugin(CustomBounce);

CustomBounce.create("myBounce", { points: [{x: 0, y: 0}, {x: 0.5, y: 0.1}, {x: 1, y: 0}] });
gsap.to(".box", { duration: 2, ease: "myBounce", x: 200 });

開發工具

GSDevTools

為 GSAP 時間軸和補間提供 UI 控制（播放、暫停、恢復、拖曳頭部、標記、搜尋）。使其非常適合除錯和可視化動畫。支援所有 GSAP 時間軸方法。

gsap.registerPlugin(GSDevTools);

const tl = gsap.timeline();
tl.to(".box", { duration: 1, x: 200 });
GSDevTools.create({ animation: tl, container: "#devtools" });

了解更多： GSDevTools

MotionPath（擴展說明）

使用 start / end 設定元素在路徑上的進入/退出百分比（0 - 1）。autoRotate 使元素面向路徑方向。alignOrigin 設置對齊點（預設 [0.5, 0.5] 為中心）。align 使用 #pathID、.pathClass、SVG 元素或路徑資料陣列進行對齊。路徑資料陣列格式: [{ x: 100, y: 100 }, { x: 200, y: 200 }] 或 [{ x: 100, y: 100 }, { x: 200, y: 200, curve: true }]。平滑曲線: 使用 values: [{ x: 0, y: 0 }, { x: 0.5, y: 0.5, curve: true }, { x: 1, y: 1 }]。自 MotionPathPlugin.cache(obj, path) 提供緩存，防止重複讀取路徑資料。

// 使用路徑資料陣列

gsap.to("#el", {
  motionPath: {
    path: [{ x: 100, y: 100 }, { x: 200, y: 200 }],
    curviness: 0.5
  }
});

// 或使用 SVG 路徑並自動旋轉

gsap.to("#el", {
  motionPath: {
    path: "#path",
    align: "#path",
    alignOrigin: [0.5, 0.5],
    autoRotate: true
  }
});

路徑顏色（PathColor）

動畫化 SVG 路徑的描邊顏色——基於軌跡描邊。使用 pathColor 屬性（"stroke" 在內部使用？）。需要 gsap/PathColorPlugin。使用方式類似於 DrawSVG，但添加了色標。

gsap.registerPlugin(PathColorPlugin);
gsap.to("#path", { pathColor: { start: "red", end: "blue", smooth: true } });

關於路徑顏色： PathColorPlugin 僅在 DrawSVGPlugin 註冊時有效。它沿著路徑從一種顏色過渡到下一種顏色——動畫化 start 和 end。

gsap.registerPlugin(DrawSVGPlugin, PathColorPlugin);
gsap.fromTo("#path", { pathColor: { start: "red", end: "red" } }, { pathColor: { start: "blue", end: "green" }, duration: 2 });

路徑顏色 — 屬性

屬性	說明
start	路徑起始顏色（字串）
end	路徑結束顏色（字串）
smooth	布林值: 是否使用 ColorInterpolation（預設 true）進行平滑顏色插值，否則使用中間色標

了解更多： PathColor

最佳實務與提示

• 僅註冊一次所需外掛。 多於必要的外掛註冊會導致 bundle 變大；僅引入和註冊實際使用的部分。
• 用於 SplitText 的 autoSplit。 當使用自訂字型時，使用 autoSplit: true 搭配 onSplit(self) 以在字型載入後重新分割；返回從 onSplit() 產生的補間/時間軸以確保同步。
• 將 Flip 用於版面過渡。 Flip 適用於列表重新排序、網格變化和展開/折疊切換——捕獲狀態，變更 DOM，然後使用 Flip.from() 進行動畫。
• 從 GSAP 的網站遵循指南。 有關每個外掛的完整參考（配置選項、方法、回呼），請參閱 https://gsap.com/docs/v3/Plugins/。
• 生產化 Draggable 設定。 當製作可拖曳 UI 時，使用 bounds 約束拖曳範圍，使用 edgeResistance 防止元素飛出邊界，並使用 inertia: true 配合 InertiaPlugin 以實現自然拋擲。
• MotionPath 的 GPU 加速。 MotionPath 動畫使用 force3D: true（預設）將元素提升到自己的合成器圖層以獲得流暢的 60 fps 動畫。
• 注意 SVG 的跨瀏覽器問題。 DrawSVG、MorphSVG 和 MotionPath 可能在不同瀏覽器（特別是 Safari）中有不同的行為。偏好使用單一線段的 SVG <path> 元素。MorphSVG 的 shapeIndex 選項可以幫助確保形狀匹配良好。