Motion Patterns 是做什么的?
可直接复制粘贴的最常见 UI 动画模式。
此处的每个模式均基于 motion-foundations 的令牌和弹性曲线构建。
请勿在此定义新的时长或缓动值——而是导入它们。
何时激活
- 为按钮、卡片、弹窗或 Toast 通知添加动画
- 构建带有交错效果的列表入场
- 在 Next.js App Router 中设置页面过渡
- 为条件内容添加入场或出场动画
- 实现滚动揭示、滚动关联进度或粘滞故事区块
- 构建展开卡片、手风琴或共享元素过渡
产出
本技能将产出:
- 适用于所有标准 UI 组件的无障碍、SSR 安全的动画
- 使用
AnimatePresence包裹的条件渲染,确保正确的出场行为 - 适用于 Next.js App Router 的页面过渡包装组件
- 使用
useScroll+useTransform的滚动揭示和滚动关联模式 - 用于展开和淡入淡出元素的布局动画模式(
layout、layoutId)
原则
- 每个模式都从
motion-foundations导入。没有原始数字。 - 每个条件渲染都用带有
key的AnimatePresence包裹。 - 出场动画始终与入场动画一起定义——绝不留到事后。
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 属性 |
| 同一元素在页面间移动 | layoutId |
| 元素在滚动进入视口时显现 | whileInView |
| 值与滚动位置绑定 | useScroll + useTransform |
何时使用 mode="wait" 与 mode="sync"
| 模式 | 适用场景 |
|---|---|
wait | 页面过渡、内容切换(一次一个) |
sync | 堆叠通知、列表项(允许重叠) |
popLayout | 在重排列表中移除的项目 |
核心概念
AnimatePresence 契约
必须始终满足三点:
AnimatePresence包裹条件表达式- 直接子元素具有
key - 子元素具有
exit属性
缺少任何一条,出场动画都会静默失败。
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}
/>
</>
)
}
Toast 堆叠
"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 的无障碍 hook:
"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 - 自定义动画 hook → 参见
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—— 定义所有令牌、弹性曲线、useSafeMotionhook 以及此处的每个模式所导入的 SSR 保护。必须先设置好。motion-advanced—— 扩展这些模式,涵盖拖拽、手势、SVG、文本、自定义 hook 和命令式编排。不会重新定义本技能的任何模式。