运动基础
运动系统的基础层。定义了所有下游技能(motion-patterns、motion-advanced)继承的值、约束和规则。在任何动画工作开始之前,请先加载此技能。
何时激活
- 从头开始创建任何动画组件时
- 设置 tokens、spring 预设或缓动值时
- 实现
prefers-reduced-motion支持时 - 调试由动画初始状态引起的水合不匹配时
- 评估某个动画是否应该存在时
输出
本技能产生:
- 一个共享的
motionTokens对象(持续时间、缓动函数、位移距离、缩放比例) - 一个共享的
springs预设映射(5 个已命名的配置) - 所有组件使用的
shouldAnimate()入口函数 - 通过
useReducedMotion实现的无障碍合规动画默认值 - 零水合警告的 SSR 安全初始状态
原则
动画必须至少满足以下条件之一,否则必须移除:
- 引导注意力
- 传达状态
- 保持空间连续性
响应性始终优于流畅性。一个会导致输入延迟的 60 fps 动画比没有动画更糟糕。
规则
这些规则不可协商。它们适用于系统中的每个组件。
- 仅使用
motion/react。 永远不要从framer-motion导入。切勿在同一组件树中混用二者。 initial必须与服务器输出匹配。 如果服务器渲染了opacity: 1,则initial属性也必须是opacity: 1。没有例外。- 弱化运动覆盖一切。 当
useReducedMotion()返回true或prefersReduced为true时,所有变换都将被禁用。仅允许 ≤ 0.2s 的仅透明度淡入淡出作为备选方案。 - 永远不要动画化布局属性。
width、height、top、left、margin、padding禁止在animate中使用。仅使用transform和opacity。 - 所有 token 值都来自
motionTokens。 禁止在组件文件中硬编码持续时间和缓动函数。 - 所有 spring 配置都来自
springs映射。 禁止内联stiffness/damping值。 - 每个导入
motion/react的文件都需要"use client"。 - 永远不要在模块级别读取
window或navigator。 始终使用typeof window !== "undefined"进行保护。
决策指南
选择持续时间
| Token | 使用时机 |
|---|---|
instant | 工具提示显隐、焦点环、徽章更新 |
fast | 按钮反馈、图标切换、标签切换 |
normal | 模态框打开、卡片展开、页面元素入场 |
slow | 英雄区域入场、全页面过渡 |
crawl | 刻意叙事;谨慎使用 |
选择 Spring
| 预设 | 使用时机 |
|---|---|
snappy | 默认 UI — 按钮、标签、导航项 |
gentle | 卡片、模态框、面板柔和着陆 |
bouncy | 有趣时刻 — 空状态、引导页 |
instant | 工具提示、弹出框、下拉菜单 |
release | 拖拽释放 — 自然物理感受 |
何时完全禁用动画
当以下情况时禁用(使 shouldAnimate() 返回 false):
prefersReduced为trueisLowEnd为true且动画非必需- 元素在屏幕外且永远不会进入视口
- 动画纯粹是装饰性的,没有 UX 目的
核心概念
Token 系统
// lib/motion-tokens.ts
export const motionTokens = {
duration: {
instant: 0.08,
fast: 0.18,
normal: 0.35,
slow: 0.6,
crawl: 1.0,
},
easing: {
smooth: [0.22, 1, 0.36, 1],
sharp: [0.4, 0, 0.2, 1],
bounce: [0.34, 1.56, 0.64, 1],
linear: [0, 0, 1, 1],
},
distance: {
xs: 4,
sm: 8,
md: 16,
lg: 24,
xl: 48,
},
scale: {
subtle: 0.98,
press: 0.95,
pop: 1.04,
},
}
export const springs = {
snappy: { type: "spring", stiffness: 300, damping: 30 },
gentle: { type: "spring", stiffness: 120, damping: 14 },
bouncy: { type: "spring", stiffness: 400, damping: 10 },
instant: { type: "spring", stiffness: 600, damping: 35 },
release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}
运行时标志
// lib/motion-config.ts
export const motionConfig = {
isLowEnd() {
return (
typeof navigator !== "undefined" &&
navigator.hardwareConcurrency <= 4
)
},
prefersReduced() {
return (
typeof window !== "undefined" &&
window.matchMedia("(prefers-reduced-motion: reduce)").matches
)
},
shouldAnimate({ essential = false } = {}) {
if (this.prefersReduced()) return false
if (!essential && this.isLowEnd()) return false
return true
},
duration() {
return this.isLowEnd() || this.prefersReduced()
? motionTokens.duration.instant
: motionTokens.duration.normal
},
}
无障碍
优先级顺序(从高到低):
prefers-reduced-motion: reduce— 禁用所有变换,限制透明度过渡时间 ≤ 0.2s- 低端设备检测 — 减少持续时间,移除非必要动画
- 设计偏好 — 其他所有情况
运动必须优雅地降级。绝不能突然消失,导致布局偏移或用户方向感混乱。
// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"
export function useSafeMotion(fullY: number = 16) {
const reduce = useReducedMotion()
return {
initial: { opacity: 0, y: reduce ? 0 : fullY },
animate: { opacity: 1, y: 0 },
exit: { opacity: 0, y: reduce ? 0 : -fullY },
}
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
.motion-safe-transition { transition: opacity 0.15s; }
.motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>
SSR / 水合安全性
规则:initial 必须始终与服务器渲染的输出匹配。
// 错误 — 服务器渲染 opacity:1 但 initial 说 opacity:0 → 水合不匹配
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
// 正确 — 使用 AnimatePresence 或推迟到客户端挂载
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
<motion.div
initial={{ opacity: mounted ? 0 : 1 }}
animate={{ opacity: 1 }}
/>
代码示例
端到端:tokens + springs + 无障碍 + SSR 守卫
// components/fade-in-card.tsx
"use client"
import { useState, useEffect } from "react"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
import { motionConfig } from "@/lib/motion-config"
interface FadeInCardProps {
children: React.ReactNode
delay?: number
}
export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
// SSR 守卫 — initial 必须与服务器输出匹配(opacity: 1)
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
// 无障碍 — 当偏好弱化运动时禁用变换
const safeMotion = useSafeMotion(motionTokens.distance.md)
// 设备守卫 — 在低端硬件上跳过动画
if (!motionConfig.shouldAnimate() || !mounted) {
return <div>{children}</div>
}
return (
<motion.div
initial={safeMotion.initial}
animate={safeMotion.animate}
exit={safeMotion.exit}
transition={{
...springs.gentle,
delay,
}}
whileHover={{ scale: motionTokens.scale.pop }}
whileTap={{ scale: motionTokens.scale.press }}
>
{children}
</motion.div>
)
}
约束 / 非目标
本技能 不 涵盖:
- UI 组件模式(按钮、模态框、交错动画)→ 参见
motion-patterns - 拖拽、手势、SVG、文本动画、自定义 hooks → 参见
motion-advanced - 纯 CSS 动画或不使用
motion/react的 Tailwindanimate-*类 - 第三方动画库(GSAP、anime.js 等)
- 运动设计决策(何时动画化、强调什么)— 这是设计关注点,而非代码约束
反模式
| 反模式 | 违反的规则 | 修复方式 |
|---|---|---|
import { motion } from "framer-motion" | 规则 1 | 使用 motion/react |
在 SSR 组件上使用 initial={{ opacity: 0 }} | 规则 2 | 添加挂载守卫 |
跳过 useReducedMotion 检查 | 规则 3 | 使用 useSafeMotion hook |
animate={{ width: "100%" }} | 规则 4 | 改用 scaleX 变换 |
内联 transition={{ duration: 0.4 }} | 规则 5 | 使用 motionTokens.duration.normal |
内联 { stiffness: 300, damping: 30 } | 规则 6 | 使用 springs.snappy |
缺少 "use client" 指令 | 规则 7 | 添加到文件顶部 |
在模块级别使用 navigator.hardwareConcurrency | 规则 8 | 包裹在 typeof navigator !== "undefined" 中 |
相关技能
motion-patterns— 使用在此定义的 tokens 和 springs 构建按钮、模态框、交错、页面过渡和滚动模式。不重新定义任何值。motion-advanced— 使用在此定义的 tokens 和 springs 实现拖拽、SVG、文本和手势模式。在此基础上增加useAnimate序列和自定义 hooks。