motion

动效动画库

概述

Motion（包名：motion，曾用名 framer-motion）是行业标准的 React 动画库，数千个应用已在生产环境中使用。它在 GitHub 上拥有 30,200+ 星标和 300+ 个官方示例，提供声明式 API，只需少量代码即可创建复杂动画。

核心功能：

• 手势：拖动、悬停、轻触、平移、聚焦，并支持跨设备使用
• 滚动动画：视口触发、滚动联动、视差效果
• 布局动画：使用 FLIP 技术实现流畅的布局变化和共享元素过渡
• 弹簧物理效果：基于物理的缓动效果，可自定义自然动效
• SVG：路径变形、线条绘制、属性动画
• 退出动画：使用 AnimatePresence 实现卸载过渡
• 性能：硬件加速、ScrollTimeline API、包体积优化（2.3 KB - 34 KB）

推荐技术栈：React 19、Next.js 16、Vite 7、Tailwind v4

---

何时使用此技能

✅ 以下情况适合使用 Motion：

复杂交互：

• 拖放界面（可排序列表、看板、滑块）
• 带缩放／旋转／颜色变化的悬停状态
• 带弹跳／挤压效果的轻触反馈
• 适合移动设备的平移手势控件

基于滚动的动画：

• 带视差图层的主视觉区域
• 滚动触发的显现效果（元素进入视口时淡入）
• 与滚动位置联动的进度条
• 随滚动改变变换效果的粘性页眉

布局过渡：

• 路由之间的共享元素过渡（卡片 → 详情页）
• 展开／折叠时自动播放高度动画
• 网格／列表视图切换时流畅地重新排列
• 带动画下划线的标签页导航

高级功能：

• SVG 线条绘制动画
• 形状之间的路径变形
• 实现自然弹跳的弹簧物理效果
• 编排动画序列（依次显现）
• 带背景模糊的模态对话框

包体积优化：

• 需要 2.3 KB 的动画库（使用 useAnimate mini）
• 希望将 Motion 的体积从 34 KB 减少到 4.6 KB（LazyMotion）

❌ 以下情况不适合使用 Motion：

• 简单的列表动画（改用 auto-animate：3.28 KB，而非 34 KB）
• 没有交互的静态内容
• Cloudflare Workers（过去需要 framer-motion 别名；使用 motion v12.43+ 时，主包可在 Workers 上正常运行——请参阅已知问题）
• 3D 动画（改用 Three.js 或 React Three Fiber）

---

安装

最新稳定版本

bun add motion  # preferred
# or: npm install motion
# or: yarn add motion

当前版本：12.43.0（已于 2026-08-03 验证）

注意：motion 是当前的包名。framer-motion 是一个已弃用的别名，会重新发布相同代码；它仍可使用，并作为安装时别名继续维护（尤其可用作 Cloudflare Workers 的构建变通方案），但新项目应安装 motion。

Cloudflare Workers 的替代方案：

# Use framer-motion if deploying to Cloudflare Workers
bun add framer-motion
# or: npm install framer-motion

包信息

• 包体积：
  • 完整的 motion 组件：压缩后约 34 KB（minified+gzipped）
  • LazyMotion + m 组件：约 4.6 KB
  • useAnimate mini：2.3 KB（体积最小的 React 动画库）
  • useAnimate hybrid：17 KB
• 依赖项：React 18+ 或 React 19+
• TypeScript：内置原生支持（无需 @types 包）

---

核心概念

1. motion 组件

将任何 HTML/SVG 元素转换为可制作动画的组件：

import { motion } from "motion/react"

// Basic animation
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.5 }}
>
  Content fades in and slides up
</motion.div>

// Gesture controls
<motion.button
  whileHover={{ scale: 1.1 }}
  whileTap={{ scale: 0.95 }}
>
  Click me
</motion.button>

属性：

• initial：起始状态（对象或变体名称）
• animate：目标状态（对象或变体名称）
• exit：卸载状态（需要 AnimatePresence）
• transition：时间／缓动配置
• whileHover、whileTap、whileFocus：手势状态
• whileInView：由视口触发的动画
• drag：启用拖动（"x"、"y"，或 true 表示两个方向）
• layout：启用 FLIP 布局动画

2. 变体（动画编排）

可在组件树中向下传递的命名动画状态：

const variants = {
  hidden: { opacity: 0, y: 20 },
  visible: { opacity: 1, y: 0 }
}

<motion.div variants={variants} initial="hidden" animate="visible">
  Content
</motion.div>

如需高级编排（staggerChildren、delayChildren、动态变体），请加载 references/core-concepts-deep-dive.md。

3. AnimatePresence（退出动画）

在组件卸载时启用动画：

import { AnimatePresence } from "motion/react"

<AnimatePresence>
  {isVisible && (
    <motion.div
      key="modal"
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      exit={{ opacity: 0 }}
    >
      Modal content
    </motion.div>
  )}
</AnimatePresence>

重要规则：

• AnimatePresence 必须保持挂载（不要用条件语句包裹）
• 所有子元素都必须有唯一的 key 属性
• AnimatePresence 包裹条件语句，而不是反过来

常见错误（退出动画不会播放）：

// ❌ Wrong - AnimatePresence unmounts with condition
{isVisible && (
  <AnimatePresence>
    <motion.div>Content</motion.div>
  </AnimatePresence>
)}

// ✅ Correct - AnimatePresence stays mounted
<AnimatePresence>
  {isVisible && <motion.div key="unique">Content</motion.div>}
</AnimatePresence>

4. 布局动画（FLIP）

自动为布局变化添加动画：

<motion.div layout>
  {isExpanded ? <FullContent /> : <Summary />}
</motion.div>

特殊属性：layoutId（共享元素过渡）、layoutScroll（可滚动容器）、layoutRoot（固定定位）。

如需了解高级模式（LayoutGroup、layoutId 编排），请加载 references/core-concepts-deep-dive.md。

5. 滚动动画

// Viewport-triggered
<motion.div
  initial={{ opacity: 0, y: 50 }}
  whileInView={{ opacity: 1, y: 0 }}
  viewport={{ once: true }}
>
  Fades in when entering viewport
</motion.div>

// Scroll-linked (parallax)
import { useScroll, useTransform } from "motion/react"
const { scrollYProgress } = useScroll()
const y = useTransform(scrollYProgress, [0, 1], [0, -300])
<motion.div style={{ y }}>Parallax effect</motion.div>

如需了解高级滚动模式（useScroll 偏移量、useTransform 缓动、视差图层），请加载 references/core-concepts-deep-dive.md。

6. 手势

<motion.div drag="x" dragConstraints={{ left: -200, right: 200 }}>
  Drag me
</motion.div>

可用属性：whileHover、whileTap、whileFocus、whileDrag、whileInView、drag。

如需了解高级拖动控制（动量、弹性、事件处理器），请加载 references/core-concepts-deep-dive.md。

7. 弹簧物理效果

<motion.div
  animate={{ x: 100 }}
  transition={{ type: "spring", stiffness: 100, damping: 10 }}
/>

常用预设：弹跳 { stiffness: 300, damping: 10 }，平滑 { stiffness: 100, damping: 20 }。

如需调整弹簧效果（质量、可视化工具、预设），请加载 references/core-concepts-deep-dive.md。

---

集成指南

Vite：bun add motion → import { motion } from "motion/react"（开箱即用）

Next.js App Router：需要 "use client" 指令或客户端组件包装器

"use client"
import { motion } from "motion/react"

Tailwind：⚠️ 移除 transition-* 类（会与 Motion 动画冲突）

Cloudflare Workers：改用 framer-motion v12.43.0（Motion 存在 Wrangler 构建问题）

如需查看完整集成指南（Next.js 模式、SSR、框架特有问题），请加载 references/nextjs-integration.md。

---

性能优化

包体积：使用 LazyMotion（34 KB → 4.6 KB）：

import { LazyMotion, domAnimation, m } from "motion/react"
<LazyMotion features={domAnimation}>
  <m.div>Only 4.6 KB!</m.div>
</LazyMotion>

大型列表：对于 50 个以上的动画项，使用虚拟化（react-window、react-virtuoso）。

如需查看完整优化指南（硬件加速、内存分析、生产环境基准测试），请加载 references/performance-optimization.md。

---

无障碍

遵循 prefers-reduced-motion 设置：

import { MotionConfig } from "motion/react"
<MotionConfig reducedMotion="user">
  <App />
</MotionConfig>

键盘支持：使用 whileFocus 实现由键盘触发的动画。

<motion.button whileFocus={{ scale: 1.1 }} tabIndex={0}>
  Keyboard accessible
</motion.button>

如需查看完整无障碍指南（ARIA 模式、屏幕阅读器、AnimatePresence 解决方法、测试），请加载 references/accessibility-guide.md。

---

常见模式

模态对话框（AnimatePresence + 背景遮罩）：

<AnimatePresence>
  {isOpen && (
    <motion.dialog exit={{ opacity: 0 }}>Content</motion.dialog>
  )}
</AnimatePresence>

手风琴（高度动画）：

<motion.div animate={{ height: isOpen ? "auto" : 0 }}>
  Content
</motion.div>

如需了解 15 种以上的生产环境模式（轮播、标签页、滚动显现、视差、通知），请加载 references/common-patterns.md。

---

已知问题与解决方案

问题 1：AnimatePresence 退出动画不起作用（最常见）

症状：组件瞬间消失，没有退出动画。

解决方案：AnimatePresence 必须保持挂载，并包裹条件语句（不能被条件语句包裹）：

// ❌ Wrong
{isVisible && <AnimatePresence><motion.div>Content</motion.div></AnimatePresence>}

// ✅ Correct
<AnimatePresence>
  {isVisible && <motion.div key="unique">Content</motion.div>}
</AnimatePresence>

问题 2：Next.js 缺少 "use client"

症状：构建失败，并出现 "motion is not defined" 或 SSR 错误。

解决方案：添加 "use client" 指令：

"use client"
import { motion } from "motion/react"

问题 3：Tailwind 过渡效果冲突

症状：动画卡顿或不起作用。

解决方案：移除 transition-* 类（Motion 会覆盖 CSS 过渡效果）：

// ❌ Wrong: <motion.div className="transition-all" animate={{ x: 100 }} />
// ✅ Correct: <motion.div animate={{ x: 100 }} />

问题 4：Cloudflare Workers 构建错误

症状：使用 motion 包时，Wrangler 构建失败。

解决方案：改用 framer-motion v12.43.0（GitHub issue #2918）：

bun add framer-motion  # Same API, works with Workers

问题 5：大型列表性能问题

症状：50–100 个以上的动画项会导致严重卡顿。

解决方案：使用虚拟化（react-window、react-virtuoso）。

如需了解 5 个以上的其他问题（layoutScroll、layoutRoot、AnimatePresence + layoutId），请加载 references/nextjs-integration.md 或 references/core-concepts-deep-dive.md。

---

何时加载参考资料

Claude 应根据用户需求加载这些参考资料：

在以下情况下加载 references/core-concepts-deep-dive.md：

• 用户询问变体编排（staggerChildren、delayChildren、动态变体）
• 用户需要高级布局动画（layoutId 共享过渡、LayoutGroup）
• 用户想要滚动联动动画（useScroll offsets、useTransform 缓动、视差图层）
• 用户需要复杂的拖拽模式（动量、弹性、事件处理器、约束）
• 用户询问弹簧物理参数调优（mass 参数、可视化工具、自定义预设）

在以下情况下加载 references/performance-optimization.md：

• 用户想将包体积缩减至 4.6 KB 以下（useAnimate mini、LazyMotion 对比）
• 用户提到“应用运行缓慢”“动画卡顿”“不流畅”或“性能问题”
• 用户的列表中有 50 个以上的动画项目（需要虚拟化）
• 用户需要内存分析或生产环境基准测试

在以下情况下加载 references/nextjs-integration.md：

• 用户正在使用 Next.js 开发（App Router 或 Pages Router）
• 用户遇到 SSR 错误、“use client”错误或 hydration 问题
• 用户询问路由过渡或页面导航动画
• 用户需要 Next.js 专属的变通方案（Reorder 组件、AnimatePresence 软导航）

在以下情况下加载 references/accessibility-guide.md：

• 用户询问“prefers-reduced-motion”或无障碍合规性
• 用户需要 ARIA 集成模式（角色、标签、播报）
• 用户希望兼容屏幕阅读器
• 用户提到无障碍审计或 WCAG 合规性
• 用户询问 AnimatePresence 的 reducedMotion 变通方案（已知问题 #1567）

在以下情况下加载 references/common-patterns.md：

• 用户询问特定 UI 模式（模态框、折叠面板、轮播图、选项卡、下拉菜单、提示消息等）
• 用户需要可在生产环境中使用的复制粘贴代码示例
• 用户想查看 15 种以上真实场景中的动画模式

在以下情况下加载 references/motion-vs-auto-animate.md：

• 用户正在 Motion 和 AutoAnimate 库之间做选择
• 用户提到“简单列表动画”或“包体积方面的顾虑”
• 用户询问“我应该使用哪个动画库？”或“Motion 是否杀鸡用牛刀？”
• 用户需要功能对比或决策矩阵

---

模板

此技能在 templates/ 目录中包含 5 个可用于生产环境的模板：

1. motion-vite-basic.tsx - 包含常见动画的基础 Vite + React + TypeScript 配置
2. motion-nextjs-client.tsx - 带有客户端组件包装器的 Next.js App Router 模式
3. scroll-parallax.tsx - 滚动动画、视差效果和视口触发器
4. ui-components.tsx - 带有共享下划线的模态框、折叠面板、轮播图和选项卡
5. layout-transitions.tsx - FLIP 布局动画和共享元素过渡

将模板复制到你的项目中，并按需自定义。

---

参考资料

此技能包含 4 份全面的参考指南：

• motion-vs-auto-animate.md - 决策指南：何时使用 Motion，何时使用 AutoAnimate
• performance-optimization.md - 包体积、LazyMotion、虚拟化、硬件加速
• nextjs-integration.md - App Router 与 Pages Router、“use client”、已知问题
• common-patterns.md - 15 种精选模式及完整代码示例

详细指南请参阅 references/ 目录。

---

脚本

此技能包含 2 个自动化脚本：

• init-motion.sh - 一键配置并检测框架（Vite、Next.js、Cloudflare Workers）
• optimize-bundle.sh - 将现有 Motion 代码转换为 LazyMotion，以缩减包体积

自动化工具请参阅 scripts/ 目录。

---

官方文档

• 官方网站：https://motion.dev
• GitHub：https://github.com/motiondivision/motion（30,200+ 个星标）
• 示例：https://motion.dev/examples（300+ 个示例）

相关技能：auto-animate（简单列表）、tailwind-v4-shadcn（样式）、nextjs（App Router）、cloudflare-worker-base

Motion 与 AutoAnimate 对比：加载 references/motion-vs-auto-animate.md 查看详细对比。

---

Token 效率指标

Token 节省：约 83%（30k → 5k tokens）| 错误防范：100%（29 个以上错误）| 时间节省：约 85%（2–3 小时 → 20–30 分钟）

---

软件包版本（已于 2026-08-03 验证）

软件包	版本	状态
motion	12.43.0	✅ 最新稳定版
framer-motion	12.43.0	✅ motion 的已弃用别名（Cloudflare Workers 变通方案）
react	19.2.0	✅ 最新稳定版
vite	7.3.0	✅ 最新稳定版

---

贡献

发现问题或有建议？

• 提交问题：https://github.com/secondsky/claude-skills/issues
• 查看模板和参考资料，了解详细示例

---

推荐技术栈：✅ React 19 + Next.js 16 + Vite 7 + Tailwind v4 Token 节省：约 83% 错误防范：100%（已防范 29 个以上有记录的错误） 包体积：2.3 KB（精简版）– 34 KB（完整版），使用 LazyMotion 可优化至 4.6 KB 无障碍支持：MotionConfig 支持 reducedMotion 立即开始使用！ 使用 /plugin install motion@claude-skills 安装