滾動動畫
一個通往十種滾動動畫模式的路由器。除了 JOS 之外的所有模式都建立在相同的 React + Framer Motion 基礎元件上——useScroll + useTransform（以及用於平滑化的 useSpring）——因此請先閱讀此檔案以了解共享的心智模型，然後僅載入符合使用者需求的參考檔案。
共享心智模型（Framer Motion 模式）
此技能中幾乎每個效果都遵循相同的骨架：
import { motion, useScroll, useSpring, useTransform } from "framer-motion";
import { useRef } from "react";
const containerRef = useRef<HTMLDivElement>(null);
const { scrollYProgress } = useScroll({
target: containerRef,
offset: ["start start", "end end"],
});
const smoothProgress = useSpring(scrollYProgress, {
damping: 25, // 20–30：數值越高 = 彈跳越少
stiffness: 200, // 150–300：數值越高 = 反應越靈敏
mass: 0.5, // 0.5–0.8：數值越低 = 更輕/更快
});
const someValue = useTransform(smoothProgress, [0, 1], [startVal, endVal]);
- 容器高度控制速度/戲劇性。 更多
vh= 更慢、更具電影感的滾動。典型範圍：150vh（敏捷）到400vh（冥想）。 position: sticky; top: 0將內容固定在視口，同時高大的容器提供滾動空間來執行動畫。- 始終將原始
scrollYProgress包裹在useSpring中——否則動作會感覺機械/線性而非物理自然。 - 多元素效果（堆疊、網格、軌道元素）為每個項目分配一個視窗：
start = index / total，end = start + 1 / total，然後將[start, end]（或針對中間峰值效果的 5 點鐘形曲線）對應到該項目的變換。 - 尊重
prefers-reduced-motion：對於有此請求的使用者，回退到靜態佈局或簡單的淡入效果。
選擇模式 — 挑選指南
請閱讀 references/ 中對應的參考檔案以取得完整的元件程式碼、變體、關鍵規則與排錯表格。不要憑記憶猜測變換數值——參考檔案中提供了已調整好的可用數值。
| 使用者要求... | 閱讀此參考檔案 |
|---|---|
| 卡片堆疊/黏著滾動、通用的「堆疊卡片」、3D 傾斜堆疊、多層堆疊、水平卡片堆疊 | references/scroll-stack.md |
| 特別指「Chronos 風格」堆疊、強烈的電影感卡片後退效果，伴隨陰影/圓角增長 | references/chronos-scroll-stack.md |
| 多速深度層、背景/前景以不同速度移動、「瘋狂」/戲劇性的視差效果、浮動裝飾形狀 | references/insane-parallax.md |
| Apple 風格的英雄區縮放至圖片、焦點拉近模糊效果、縮放圖片上的分層文字揭示、電影感的產品發布縮放 | references/immersive-scroll-zoom.md |
| 圖庫圖片在進入視野時縮放、產品焦點縮放、帶滾動驅動縮放的圖片網格 | references/image-zoom-scrolling.md |
| 圖片分裂成兩半/四分之一並分離、對角碎裂、帶 3D 傾斜的代理商作品集風格揭示 | references/image-split-3d.md |
| 軌道元素、圓形進度環、徑向/螺旋圖庫、沿圓形路徑的文字 | references/circular-scroll.md |
| 卡片/圖塊在活躍時成長/縮放、鐘形曲線網格展開、點擊展開的瀑布流 | references/expanding-cards-scroll.md |
| 逐格掃描、「翻頁書」滾動、Canvas 圖片序列、綁定到滾動位置的產品揭示影片 | references/scroll-image-sequences.md |
| 簡單的淡入/滑入/縮放揭示、交錯揭示、不使用 React/Framer Motion 或明確要求「JOS」 | references/jos-animation.md |
如果要求不明確或可能適用多種模式（例如「讓英雄區在滾動時更動態」），對於英雄區段，偏好 insane-parallax.md 或 immersive-scroll-zoom.md，僅在真正不清楚時才提問——否則選擇最接近的模式並註明假設。
跨模式規則（無論何種模式皆適用）
- 僅限 Framer Motion（除 JOS 外）——不使用 GSAP、原生滾動監聽程式碼，除非使用者明確要求非 Framer Motion 的實作。
- 彈簧預設值在大多數情況下效果良好：
damping: 20–30，stiffness: 150–300，mass: 0.5–0.8。每個參考檔案都給出了該模式確切的調整數值——當兩者不同時，請使用參考檔案中的數值而非這些通用預設值。 willChange: "transform, opacity"套用在動畫元素上，以保持在合成器執行緒中。- z-index 數學用於任何堆疊元素：通常為
total - index，使較早的元素在後退時位於上方。 - 不要過度動畫。 3–8 個卡片/畫面/層通常是甜蜜點；更多會讓人疲勞或損害行動裝置效能。
- 行動裝置：柔化縮放範圍，減少層/畫面數量，並在戲劇性非必要時偏好使用
whileInView而非長滾動驅動序列。
組合模式
這些模式可以組合。一個登陸頁面可能在英雄區使用 insane-parallax，功能區使用 scroll-stack，並在同一頁面的其他地方使用 jos-animation 進行簡單的交錯淡入。獨立閱讀每個相關的參考檔案——它們之間沒有依賴關係，除非有特別說明（例如，scroll-stack.md 會指向 chronos-scroll-stack.md 以取得完整的電影感變體）。