motion

Motion

概述

Motion（包：motion，前身为 framer-motion）是标准的 React 动画库。请从 motion/react 导入。它提供用于手势、滚动联动动画、布局过渡、SVG 路径绘制和弹簧物理效果的声明式属性。它采用混合动画引擎（变换和不透明度使用 WAAPI，滚动联动效果使用 ScrollTimeline）。包体积范围为 2.3 KB（useAnimate mini）到 34 KB（完整版本），使用 LazyMotion 可优化至 4.6 KB。兼容 React 18.2+、React 19、Next.js App Router 和 Vite。

对于简单的列表添加／移除动画，请勿使用 Motion（改用 AutoAnimate，体积仅 3.28 KB）。请勿用于 3D（改用 Three.js / React Three Fiber）。

快速参考

模式	API／属性
挂载时淡入	initial、animate、transition
退出动画	AnimatePresence + exit 属性（必须有唯一的 key）
交错列表	使用 staggerChildren 的 variants
悬停／点击／聚焦	whileHover、whileTap、whileFocus
拖拽	drag、dragConstraints、dragElastic
滚动触发	whileInView、viewport={{ once: true }}
滚动联动／视差	useScroll + useTransform
进度指示器	scrollYProgress + scaleX
布局动画	layout 属性（FLIP 技术）
共享元素	layoutId（不同视图间使用相同 ID）
布局组	用 LayoutGroup 包裹同级列表
页面过渡	AnimatePresence + key={pathname}
SVG 路径绘制	在 motion.path 上使用 pathLength
动画计数器	useSpring + useTransform
命令式控制	useAnimate Hook 返回 [scope, animate]
自定义组件	motion.create(Component) 包装任意组件
优化包体积	LazyMotion + domAnimation + m 组件（4.6 KB）
减少动态效果	MotionConfig reducedMotion="user"

常见错误

错误	正确做法
在条件语句中使用 AnimatePresence	保持 AnimatePresence 挂载；将条件内容放在其中
AnimatePresence 子元素缺少唯一的 key	为每个直接子元素添加唯一的 key，以实现退出动画
Motion 动画属性与 Tailwind transition-* 类同时使用	移除 Tailwind 过渡类，避免动画卡顿
从 framer-motion 导入	使用 import { motion } from "motion/react"（于 2024 年末更名）
未进行虚拟化就为 50 个以上的项目添加动画	对大型列表使用 react-window 或 @tanstack/react-virtual
简单动画也使用完整的 34 KB 包	使用 LazyMotion + domAnimation（4.6 KB）或 useAnimate（2.3 KB）
Next.js App Router 中缺少 "use client"	添加指令或使用 motion/react-client 导入
直接对 width／height 添加动画	使用 layout 属性或 transform: scale，以启用 GPU 加速
未处理 prefers-reduced-motion	使用 MotionConfig reducedMotion="user" 包裹应用

委派

• 审核动画性能和打包体积：使用 Explore Agent 查找较大的导入项、缺少的 LazyMotion，以及会触发重排的属性
• 构建复杂的多步骤动画：使用 Task Agent 实现滚动联动视差、共享布局过渡和交错序列
• 为新项目规划动画架构：使用 Plan Agent 根据需求评估 Motion、AutoAnimate 或纯 CSS 方案

如果有 design-system 技能，请将动画令牌定义和动态设计指南委派给它。

参考资料

• 核心模式 -- 动画模式：淡入、退出、交错、手势、模态框、手风琴、标签页、滚动、布局、拖动、SVG、加载
• 滚动动画 -- useScroll、useTransform、滚动触发、视差、进度指示器、偏移配置
• 性能 -- LazyMotion、useAnimate、硬件加速、虚拟化、生产环境检查清单
• Next.js 集成 -- App Router 模式、motion/react-client、Pages Router、已知问题
• 无障碍与 CSS -- prefers-reduced-motion、MotionConfig、useReducedMotion、CSS 关键帧、Tailwind 动画
• 库选择指南 -- Motion 与 AutoAnimate 的决策指南，包含功能比较和使用场景建议
• 故障排除 -- AnimatePresence 错误、Tailwind 冲突、布局异常、React 19 问题、命名迁移