進階動畫
複雜、互動式且基於物理的動畫模式。
需先設定好 motion-foundations。
當 motion-patterns 不足時使用這些模式。
啟動時機
- 建立拖曳關閉面板、滑動手勢或可重新排序列表
- 逐字、逐字元或即時計數器動畫文字
- 繪製 SVG 路徑、變形圖示或動畫環形進度條
- 編寫自訂動畫 Hook(
useScrollReveal、磁性按鈕、游標跟隨器) - 使用
useAnimate強制編排多步驟動畫 - 建立 Spinner、Shimmer 骨架、脈衝指示器或按鈕載入狀態
產出
此技能產生:
- 拖曳互動:可拖曳卡片、拖曳關閉面板、
Reorder.Group列表 - 手勢 Hook:滑動偵測、長按、縮放手勢輪廓
- 文字動畫元件:單字顯現、打字機效果、數字計數器
- SVG 動畫:路徑繪製、圖示變形、描邊進度環
- 自訂 Hook:
useScrollReveal、useHoverScale、useNavigationDirection、useInViewOnce - 使用
useAnimate搭配可中斷的async/await進行強制序列 - 載入器元件:Spinner、Shimmer、脈衝點、進度條、按鈕載入狀態
原則
- 基於物理的動畫(
useSpring、springs.*)在直接操作時,總是比基於時間的動畫更自然。 useMotionValue+useTransform可計算衍生數值,且不觸發重新渲染。useAnimate序列是強制且可中斷的 — 在動畫進行中呼叫animate()會自動取消之前的動畫。- Motion 值(
useMotionValue、useSpring)支援 SSR,不會造成 hydration 錯誤。
規則
- 拖曳互動必須在觸控裝置上測試,而不僅在滑鼠上。
drag屬性在兩者上均可使用,但手感與閾值不同。 - **無限動畫必須在
document.visibilityState === "hidden"時暫停。**背景分頁不得消耗 GPU/CPU。 - **滑動閾值必須明確指定。**切勿僅從速度推斷意圖;應同時檢查
offset與velocity。 - **
useAnimate範圍 ref 必須附加到已掛載的 DOM 元素。**在掛載前呼叫animate()會靜默失敗。 - **Motion 值不得在渲染時重新建立。**在元件本體內使用
useMotionValue(0)是正確的;在渲染過程中使用new MotionValue(0)則不正確。 - **所有 Token 值皆從
motion-foundations匯入。**不得使用內聯數字。 - **自訂 Hook 必須處理清理作業。**每個
window.addEventListener都需要在useEffect的回傳中加入對應的removeEventListener。 - **SVG 變形需要路徑命令數量相等。**具有不同命令結構的路徑會產生快照而非內插。
決策指南
選擇合適的進階 API
| 情境 | API |
|---|---|
| 鬆開時具物理效果的拖曳 | drag + dragTransition: springs.release |
| 可排序的拖曳列表 | Reorder.Group + Reorder.Item |
| 根據拖曳位移關閉 | drag="y" + 偏移量檢查 onDragEnd |
| 向左/向右滑動 | drag="x" + 偏移量檢查 onDragEnd |
| 長按 | useLongPress Hook |
| 隨時間平滑的數值 | useSpring |
| 從另一數值衍生的數值 | useTransform |
| 多步驟序列 | useAnimate 搭配 async/await |
| 一次性強制動畫 | 來自 motion 的 animate() |
| 逐字文字進入 | 在 inline-block 範圍上設定交錯 |
| SVG 繪製 | pathLength 0 → 1 |
| SVG 變形 | d 屬性補間(命令數量相等) |
| 環形進度 | strokeDashoffset 補間 |
何時使用 useSpring vs 彈簧過渡
useSpring | transition: springs.* | |
|---|---|---|
| 適用於 | 游標跟隨器、指標追蹤數值 | 離散狀態變更 |
| 更新方式 | 連續,每幀更新 | 由狀態變更觸發 |
| 中斷方式 | 平滑 — 物理從速度繼續 | 從當前數值重新開始 |
核心概念
useMotionValue + useTransform
無重新渲染的反應式計算:
const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// opacity 在 x 改變時每幀更新 — 無 setState,無重新渲染
useAnimate
回傳 [scope, animate]。範圍 ref 必須附加到 DOM 元素。
animate() 呼叫是可中斷的 — 在動畫進行中呼叫會取消之前的執行。
const [scope, animate] = useAnimate()
async function play() {
await animate(".step-1", { opacity: 1 }, { duration: 0.3 })
await animate(".step-2", { x: 0 }, { duration: 0.4 })
animate(".step-3", { scale: 1 }, { duration: 0.25 }) // 觸發後即忘
}
return <div ref={scope}>...</div>
程式碼範例
可拖曳卡片
"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
<motion.div
drag
dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
dragElastic={0.1}
whileDrag={{
scale: motionTokens.scale.pop,
boxShadow: "0 16px 40px rgba(0,0,0,0.2)",
}}
dragTransition={springs.release}
/>
拖曳關閉面板
"use client"
import { motion, useMotionValue, useTransform } from "motion/react"
export function BottomSheet({ onClose }: { onClose: () => void }) {
const y = useMotionValue(0)
const opacity = useTransform(y, [0, 200], [1, 0])
return (
<motion.div
drag="y"
dragConstraints={{ top: 0 }}
style={{ y, opacity }}
onDragEnd={(_, info) => {
// 規則 3:結合偏移量與速度
if (info.offset.y > 120 || info.velocity.y > 500) onClose()
}}
/>
)
}
可排序列表
"use client"
import { Reorder } from "motion/react"
export function SortableList() {
const [items, setItems] = useState(initialItems)
return (
<Reorder.Group axis="y" values={items} onReorder={setItems}>
{items.map((item) => (
<Reorder.Item key={item.id} value={item}>
{item.label}
</Reorder.Item>
))}
</Reorder.Group>
)
}
滑動偵測
"use client"
import { motion } from "motion/react"
const OFFSET_THRESHOLD = 50
const VELOCITY_THRESHOLD = 300
<motion.div
drag="x"
dragConstraints={{ left: 0, right: 0 }}
onDragEnd={(_, info) => {
const swipedRight = info.offset.x > OFFSET_THRESHOLD || info.velocity.x > VELOCITY_THRESHOLD
const swipedLeft = info.offset.x < -OFFSET_THRESHOLD || info.velocity.x < -VELOCITY_THRESHOLD
if (swipedRight) onSwipeRight()
if (swipedLeft) onSwipeLeft()
}}
/>
長按 Hook
import { useRef } from "react"
export function useLongPress(callback: () => void, ms = 600) {
const timerRef = useRef<ReturnType<typeof setTimeout>>()
return {
onPointerDown: () => { timerRef.current = setTimeout(callback, ms) },
onPointerUp: () => clearTimeout(timerRef.current),
onPointerLeave: () => clearTimeout(timerRef.current),
}
}
逐字顯現
"use client"
import { motion } from "motion/react"
import { springs } from "@/lib/motion-tokens"
export function AnimatedText({ text }: { text: string }) {
return (
<motion.p
variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
initial="hidden"
animate="visible"
>
{text.split(" ").map((word, i) => (
<motion.span
key={i}
className="inline-block mr-1"
variants={{
hidden: { opacity: 0, y: 12 },
visible: { opacity: 1, y: 0, transition: springs.gentle },
}}
>
{word}
</motion.span>
))}
</motion.p>
)
}
數字計數器
"use client"
import { useRef, useEffect } from "react"
import { animate } from "motion"
import { motionTokens } from "@/lib/motion-tokens"
export function Counter({ to }: { to: number }) {
const nodeRef = useRef<HTMLSpanElement>(null)
useEffect(() => {
const controls = animate(0, to, {
duration: motionTokens.duration.crawl,
ease: motionTokens.easing.smooth,
onUpdate: (v) => {
if (nodeRef.current) nodeRef.current.textContent = Math.round(v).toString()
},
})
return controls.stop // 規則 7:清理
}, [to])
return <span ref={nodeRef} />
}
SVG 路徑繪製
"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
<motion.path
d="M 0 100 Q 50 0 100 100"
initial={{ pathLength: 0, opacity: 0 }}
animate={{ pathLength: 1, opacity: 1 }}
transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>
描邊進度環
"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
const CIRCUMFERENCE = 2 * Math.PI * 40 // r=40
export function ProgressRing({ progress }: { progress: number }) {
return (
<svg width="100" height="100" viewBox="0 0 100 100">
<circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
<motion.circle
cx="50" cy="50" r="40"
fill="none" stroke="#6366f1" strokeWidth="8"
strokeLinecap="round"
strokeDasharray={CIRCUMFERENCE}
animate={{ strokeDashoffset: CIRCUMFERENCE - (progress / 100) * CIRCUMFERENCE }}
transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
style={{ rotate: -90, transformOrigin: "center" }}
/>
</svg>
)
}
useScrollReveal Hook
"use client"
import { useRef } from "react"
import { useScroll, useTransform } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function useScrollReveal() {
const ref = useRef(null)
const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
const opacity = useTransform(scrollYProgress, [0, 0.3], [0, 1])
const y = useTransform(scrollYProgress, [0, 0.3], [motionTokens.distance.lg, 0])
return { ref, style: { opacity, y } }
}
// 用法
const { ref, style } = useScrollReveal()
<motion.section ref={ref} style={style} />
游標跟隨器
"use client"
import { useEffect } from "react"
import { motion, useMotionValue, useSpring } from "motion/react"
import { springs } from "@/lib/motion-tokens"
export function CursorFollower() {
const x = useMotionValue(-100)
const y = useMotionValue(-100)
const sx = useSpring(x, springs.gentle)
const sy = useSpring(y, springs.gentle)
useEffect(() => {
const move = (e: MouseEvent) => { x.set(e.clientX); y.set(e.clientY) }
window.addEventListener("mousemove", move)
return () => window.removeEventListener("mousemove", move) // 規則 7
}, [])
return (
<motion.div
className="fixed top-0 left-0 w-6 h-6 rounded-full bg-indigo-500
pointer-events-none -translate-x-1/2 -translate-y-1/2 z-50"
style={{ x: sx, y: sy }}
/>
)
}
Shimmer 骨架
"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function ShimmerSkeleton({ className = "" }: { className?: string }) {
const controls = useAnimation()
useEffect(() => {
const play = () =>
controls.start({
x: ["-100%", "100%"],
transition: {
repeat: Infinity,
duration: motionTokens.duration.crawl,
ease: motionTokens.easing.linear,
},
})
const handleVisibility = () => {
if (document.visibilityState === "hidden") controls.stop()
else void play()
}
void play()
document.addEventListener("visibilitychange", handleVisibility)
return () => {
controls.stop()
document.removeEventListener("visibilitychange", handleVisibility)
}
}, [controls])
return (
<div className={`relative overflow-hidden bg-gray-200 rounded ${className}`}>
<motion.div
className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent"
initial={{ x: "-100%" }}
animate={controls}
/>
</div>
)
}
按鈕載入狀態
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
export function LoadingButton({
loading,
label,
onClick,
}: {
loading: boolean
label: string
onClick: () => void
}) {
return (
<motion.button
onClick={onClick}
animate={{ opacity: loading ? 0.7 : 1 }}
whileTap={loading ? {} : { scale: motionTokens.scale.press }}
transition={springs.snappy}
disabled={loading}
>
<AnimatePresence mode="wait">
{loading ? (
<motion.span
key="loading"
initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
…
</motion.span>
) : (
<motion.span
key="label"
initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
{label}
</motion.span>
)}
</AnimatePresence>
</motion.button>
)
}
含可見度暫停的無限動畫
"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"
export function PulseDot() {
const controls = useAnimation()
useEffect(() => {
const pulse = () =>
controls.start({
scale: [1, 1.4, 1],
opacity: [1, 0.6, 1],
transition: { repeat: Infinity, duration: motionTokens.duration.crawl },
})
// 規則 2:分頁隱藏時暫停
const handleVisibility = () => {
if (document.visibilityState === "hidden") controls.stop()
else void pulse()
}
void pulse()
document.addEventListener("visibilitychange", handleVisibility)
return () => {
controls.stop()
document.removeEventListener("visibilitychange", handleVisibility)
}
}, [controls])
return <motion.div animate={controls} className="w-3 h-3 rounded-full bg-indigo-500" />
}