Motion Patterns
可直接複製貼上最常見的 UI 動畫需求模式。
此處的所有模式都建構在 motion-foundations 的代幣與彈簧之上。請勿在此定義新的持續時間或緩動值——請從那裡匯入。
啟用時機
- 為按鈕、卡片、選單或提示通知加入動畫
- 使用交錯效果構建列表進場
- 在 Next.js App Router 中設定頁面轉場
- 為條件式內容加入進場或離開動畫
- 實作滾動觸發顯示、滾動相關進度或黏性故事章節
- 構建可擴展卡片、手風琴或共享元素轉場
產出
此技能產出:
- 無障礙且 SSR 安全的標準 UI 元件動畫
- 使用
AnimatePresence包裹的條件渲染,具有正確的離開行為 - 用於 Next.js App Router 的頁面轉場包裹元件
- 使用
useScroll+useTransform的滾動觸發顯示與滾動相關模式 - 用於擴展與交叉淡變元素的佈局動畫模式 (
layout、layoutId)
原則
- 每個模式都從
motion-foundations匯入。沒有原始數值。 - 每個條件渲染都使用
AnimatePresence包裹,並帶有key。 - 離開動畫永遠與進入動畫同時定義——絕不是事後才想到的。
layout僅用於小範圍的獨立位移。大型子樹應使用明確的變換。
規則
- 務必將條件渲染包裹在帶有
key的AnimatePresence中,且key置於直接子元素上。缺少key,離開動畫永遠不會觸發。 - 定義
initial+animate時務必同時定義exit。 沒有離開動畫的動畫是不完整的。 - 頁面轉場務必使用
mode="wait"。 進入動畫必須等到離開動畫完成後才能開始。 - 切勿在超過 ~5 個子元素或深層巢狀 DOM 的子樹上使用
layout。 應改用明確的x/y變換。 - 交錯間隔必須維持在
0.05s到0.10s之間。 低於此範圍感覺機械化;高於此則感覺遲緩。 - 選單必須始終包含: 焦點陷阱、Escape 鍵關閉、滾動鎖定、
role="dialog"、aria-modal="true"。 - 滾動觸發顯示使用
viewport={{ once: true }}。 滾出後重複播放會分散注意力,而非提供資訊。 - 所有代幣值都從
motion-foundations匯入。 沒有行內數值。
決策指引
選擇正確的模式
| 情境 | 模式 |
|---|---|
| 元素顯示 / 消失 | AnimatePresence |
| 列表項目依序載入 | 交錯變體 |
| 在路由之間導航 | 頁面轉場包裹元件 |
| 元素在原位改變大小 | layout prop |
| 相同元素跨頁面上下文移動 | layoutId |
| 元素在滾動到視野時進入 | whileInView |
| 值與滾動位置綁定 | useScroll + useTransform |
使用 mode="wait" 與 mode="sync" 的時機
| 模式 | 適用時機 |
|---|---|
wait | 頁面轉場、內容切換(一次一個) |
sync | 堆疊通知、列表項目(重疊可以接受) |
popLayout | 從重排列表中移除項目 |
核心概念
AnimatePresence 約定
三件事必須永遠成立:
AnimatePresence包裹了條件式- 直接子元素有
key - 子元素有
exitprop
任何一項缺失都會導致離開動畫無聲失敗。
layout 與 layoutId 的區別
layout— 動畫化元素本身在原位的大小/位置變化layoutId— 連結兩個不同的元素,在渲染之間對它們進行交叉淡變
在可擴展容器內部的文字上使用 layout="position",以防止文字重排跟著動畫化。
程式碼範例
按鈕回饋
"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
<motion.button
whileHover={{ scale: motionTokens.scale.pop }}
whileTap={{ scale: motionTokens.scale.press }}
transition={springs.snappy}
/>
交錯列表
"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
const container = {
hidden: {},
visible: {
transition: {
staggerChildren: 0.08, // 在 0.05–0.10 的規則內
delayChildren: 0.1,
},
},
}
const item = {
hidden: { opacity: 0, y: motionTokens.distance.md },
visible: { opacity: 1, y: 0, transition: springs.gentle },
}
<motion.ul variants={container} initial="hidden" animate="visible">
{items.map((i) => (
<motion.li key={i.id} variants={item} />
))}
</motion.ul>
選單
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
// 在呼叫處包裹:
// <AnimatePresence>{isOpen && <Modal key="modal" />}</AnimatePresence>
export function Modal({ onClose }: { onClose: () => void }) {
return (
<>
{/* 遮罩 */}
<motion.div
className="fixed inset-0 bg-black/50"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
onClick={onClose}
/>
{/* 面板 — 無障礙要求:焦點陷阱、Escape 關閉、
滾動鎖定、role="dialog"、aria-modal="true" */}
<motion.div
role="dialog"
aria-modal="true"
className="fixed inset-x-4 top-1/2 -translate-y-1/2 rounded-xl bg-white p-6"
initial={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
animate={{ opacity: 1, scale: 1, y: 0 }}
exit={{
opacity: 0,
scale: motionTokens.scale.press,
y: motionTokens.distance.sm,
}}
transition={springs.gentle}
/>
</>
)
}
提示堆疊
"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<AnimatePresence mode="sync">
{toasts.map((t) => (
<motion.div
key={t.id}
layout
initial={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
animate={{ opacity: 1, x: 0, scale: 1 }}
exit={{
opacity: 0,
x: motionTokens.distance.xl,
scale: motionTokens.scale.subtle,
}}
transition={springs.snappy}
/>
))}
</AnimatePresence>
頁面轉場 (Next.js App Router)
// components/page-transition.tsx
"use client"
import { motion, AnimatePresence } from "motion/react"
import { usePathname } from "next/navigation"
import { motionTokens } from "@/lib/motion-tokens"
const variants = {
initial: { opacity: 0, y: motionTokens.distance.sm },
enter: { opacity: 1, y: 0 },
exit: { opacity: 0, y: -motionTokens.distance.sm },
}
export function PageTransition({ children }: { children: React.ReactNode }) {
const pathname = usePathname()
return (
<AnimatePresence mode="wait">
<motion.div
key={pathname}
variants={variants}
initial="initial"
animate="enter"
exit="exit"
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
>
{children}
</motion.div>
</AnimatePresence>
)
}
滾動觸發顯示
"use client"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
<motion.div
initial={{ opacity: 0, y: motionTokens.distance.lg }}
whileInView={{ opacity: 1, y: 0 }}
viewport={{ once: true, margin: "-80px" }} // once: true — 規則 7
transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>
滾動進度條
"use client"
import { motion, useScroll } from "motion/react"
export function ScrollProgress() {
const { scrollYProgress } = useScroll()
return (
<motion.div
className="fixed top-0 left-0 h-1 bg-indigo-500 origin-left w-full"
style={{ scaleX: scrollYProgress }}
/>
)
}
可擴展卡片
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"
export function ExpandingCard({ title, body }: { title: string; body: string }) {
const [expanded, setExpanded] = useState(false)
return (
<motion.div layout onClick={() => setExpanded(!expanded)} className="cursor-pointer">
{/* layout="position" 可防止文字重排跟著動畫化 */}
<motion.h2 layout="position" className="font-semibold">
{title}
</motion.h2>
<AnimatePresence>
{expanded && (
<motion.p
key="body"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: motionTokens.duration.fast }}
>
{body}
</motion.p>
)}
</AnimatePresence>
</motion.div>
)
}
共享元素交叉淡變
// 來源上下文
<motion.img layoutId="hero-image" src={src} className="w-16 h-16 rounded" />
// 目標上下文(相同的 layoutId — motion 處理轉場)
<motion.img layoutId="hero-image" src={src} className="w-full rounded-xl" />
手風琴
<motion.div
initial={false}
animate={{ opacity: open ? 1 : 0, scaleY: open ? 1 : 0 }}
style={{ transformOrigin: "top", overflow: "hidden" }}
transition={{
duration: motionTokens.duration.normal,
ease: motionTokens.easing.smooth,
}}
> {children}
</motion.div>
完整範例
一個在掛載時進場、處理條件性存在,並尊重減少動畫設定的交錯列表——結合代幣、彈簧、AnimatePresence 以及 motion-foundations 的無障礙鉤子:
"use client"
import { useState } from "react"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
const containerVariants = {
hidden: {},
visible: {
transition: { staggerChildren: 0.08, delayChildren: 0.1 },
},
}
function ListItem({ label, onRemove }: { label: string; onRemove: () => void }) {
const safe = useSafeMotion(motionTokens.distance.sm)
return (
<motion.li
variants={{
hidden: safe.initial,
visible: safe.animate,
}}
exit={safe.exit}
transition={springs.gentle}
className="flex items-center justify-between p-3 rounded-lg bg-white shadow-sm"
>
<span>{label}</span>
<button onClick={onRemove}>Remove</button>
</motion.li>
)
}
export function AnimatedList({ items, onRemove }: {
items: { id: string; label: string }[]
onRemove: (id: string) => void
}) {
return (
<motion.ul
variants={containerVariants}
initial="hidden"
animate="visible"
className="space-y-2"
>
<AnimatePresence mode="popLayout">
{items.map((item) => (
<ListItem
key={item.id}
label={item.label}
onRemove={() => onRemove(item.id)}
/>
))}
</AnimatePresence>
</motion.ul>
)
}
限制 / 非目標
此技能不涵蓋:
- 代幣與彈簧定義 → 請參考
motion-foundations - 拖曳互動、滑動手勢、可排序列表 → 請參考
motion-advanced - 文字動畫(字詞/字元揭示、計數器) → 請參考
motion-advanced - SVG 路徑繪製或變形 → 請參考
motion-advanced - 自訂動畫鉤子 → 請參考
motion-advanced - 不使用
motion/react的純 CSS 轉場
反模式
| 反模式 | 違反規則 | 修正方法 |
|---|---|---|
AnimatePresence 子元素缺少 key | 規則 1 | 在直接子元素上添加穩定的 key |
只有 initial + animate 而沒有 exit | 規則 2 | 永遠同時定義三者 |
頁面轉場沒有 mode="wait" | 規則 3 | 在 AnimatePresence 上添加 mode="wait" |
在包含 50 個項目的列表上使用 layout | 規則 4 | 使用 mode="popLayout" 或明確的變換 |
在包含 10 個項目的列表上設定 staggerChildren: 0.2 | 規則 5 | 限制在 0.08–0.10 之間 |
| 選單沒有焦點陷阱 | 規則 6 | 添加 focus-trap-react 或 Radix Dialog |
whileInView 沒有 viewport={{ once: true }} | 規則 7 | 重複進場會分散注意力而非提供資訊 |
行內使用 transition={{ duration: 0.3 }} | 規則 8 | 使用 motionTokens.duration.normal |
相關技能
motion-foundations— 定義此處所有模式匯入的代幣、彈簧、useSafeMotion鉤子與 SSR 保護。必須優先設定。motion-advanced—— 以拖曳、手勢、SVG、文字、自訂鉤子與指令式排序擴展這些模式。不會重新定義此技能的任何模式。