Motion Advanced
複雜、互動且基於物理的動畫模式。
需要先設定好 motion-foundations。
當 motion-patterns 不足以應付時使用。
啟動時機
- 建置拖曳關閉式面板、滑動手勢或可重新排序的清單
- 逐詞、逐字動畫文字,或作為即時計數器
- 繪製 SVG 路徑、變形圖示或動畫圓形進度條
- 撰寫自訂動畫 Hook(
useScrollReveal、磁性按鈕、游標跟隨器) - 使用
useAnimate以指令式方式編排多步驟動畫序列 - 建置旋轉器、微光骨架、脈衝指示器或按鈕載入狀態
產出
此技能產出以下內容:
- 拖曳互動:可拖曳卡片、拖曳關閉式面板、
Reorder.Group清單 - 手勢 Hook:滑動偵測、長按、捏合輪廓
- 文字動畫元件:文字揭示、打字機效果、數字計數器
- SVG 動畫:路徑繪製、圖示變形、筆劃進度環
- 自訂 Hook:
useScrollReveal、useHoverScale、useNavigationDirection、useInViewOnce - 透過
useAnimate實現的指令式序列,具備中斷安全的async/await - 載入器元件:旋轉器、微光、脈衝點、進度條、按鈕載入狀態
原則
- 對於直接操作,基於物理的運動(
useSpring、springs.*)總是比基於持續時間的更自然。 useMotionValue+useTransform計算衍生值而不觸發重新渲染。useAnimate序列是指令式且中斷安全的 — 在中途呼叫animate()會自動取消先前的動畫。- Motion 值(
useMotionValue、useSpring)是 SSR 安全的,不會導致水合錯誤。
規則
- 拖曳互動必須在觸控裝置上測試,而不僅僅是滑鼠。
drag屬性在兩者上都有效,但感覺和閾值不同。 - 當
document.visibilityState === "hidden"時,無限動畫必須暫停。 背景分頁不得消耗 GPU/CPU。 - 滑動閾值必須明確。 切勿僅透過速度來推斷意圖;應結合
offset和velocity檢查。 useAnimate的作用域 ref 必須附加到已掛載的 DOM 元素上。 在掛載前呼叫animate()會無聲地拋出錯誤。- Motion 值不得在渲染時重新建立。 在元件主體內部使用
useMotionValue(0)是正確的;在渲染中使用new MotionValue(0)則否。 - 所有令牌值都從
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 span 上進行錯開 |
| SVG 繪製開啟 | pathLength 0 → 1 |
| SVG 變形 | d 屬性補間(相等指令) |
| 圓形進度 | strokeDashoffset 補間 |
何時使用 useSpring 與 spring 過渡效果
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]。scope 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:結合 offset 和 velocity
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 }}
/>
)
}
微光骨架
"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
className="w-4 h-4 rounded-full bg-indigo-500"
animate={controls}
/>
)
}
相關技能
motion-foundations— 先決條件。提供springs和motionTokens。motion-patterns— 用於共通、標準的動畫模式。motion-tokens— 用於調整和建立新的令牌。