拆解 Componentry Magnetic Dock:Framer Motion 弹簧物理打造磁吸放大的秘密
拆解 Componentry Magnetic Dock:Framer Motion 弹簧物理打造磁吸放大的秘密
Componentry 是一个提供动画化、可直接用于生产环境的 React UI 组件库,而 Magnetic Dock 正是其中最有"手感"的组件之一:鼠标靠近图标时放大上浮、移开时弹回原位,完整复刻了 macOS Dock 的磁吸放大体验。本文将拆解它如何用 Framer Motion 的 useMotionValue、useTransform 和 useSpring 三个工具函数,以极少的代码实现自然流畅的弹簧物理动画。
这个磁吸 Dock 能做什么?✨
在 magnetic-dock.tsx 中,Magnetic Dock 支持以下开箱即用的能力:
- 🧲 磁吸放大:图标随鼠标距离平滑放大,最近处达到
maxScale(默认 1.5 倍),并同步向上"悬浮" - 💬 悬浮提示:悬停或键盘聚焦时弹出 tooltip 标签
- 🔴 消息角标:支持 badge 数字角标(超过 99 自动显示
99+),进出场带缩放动画 - 🎨 多种外观:
glass毛玻璃 /solid实体 /transparent透明背景,支持明暗双模式 - 📍 四向布局:可放在页面
bottom/top/left/right任意一侧 - ♿ 无障碍:
aria-label、aria-current活跃指示点,并通过useReducedMotion尊重系统"减少动态效果"设置
三步看懂磁吸放大的核心原理 🔍
整个磁吸效果的核心逻辑只有三行关键代码,全部集中在 magnetic-dock.tsx 的 DockItem 中。
第 1 步:用 MotionValue 追踪鼠标(不触发重渲染)
Dock 容器用一个共享的 MotionValue 记录鼠标位置(magnetic-dock.tsx):
const mousePosition = useMotionValue(Infinity) // 初始值 Infinity 表示"鼠标不在场"
关键点:useMotionValue 的更新不经过 React 状态,因此鼠标移动时不会引起整棵组件树重渲染,动画全程在浏览器合成层完成,性能非常稳。鼠标离开 Dock 时只需 mousePosition.set(Infinity),所有图标会自动归位。
第 2 步:距离 → 缩放系数的分段插值
每个图标先计算鼠标到自身中心的距离,再用 useTransform 做分段线性映射(magnetic-dock.tsx):
const scale = useTransform(
distance,
[-magneticDistance, 0, magneticDistance], // 输入区间:-150px → 0 → +150px
[1, maxScale, 1] // 输出区间:1倍 → 1.5倍 → 1倍
)
这张"映射表"就是磁吸曲线的灵魂:只有进入 magneticDistance(默认 150px)范围内的图标才会被放大,距离越近放大越多,范围外保持原样——相邻图标因此呈现错落有致的波浪形放大。
第 3 步:useSpring 让变化拥有物理质感
直接把插值结果贴到元素上会显得机械。Magnetic Dock 用 useSpring 给缩放加上弹簧动力学(magnetic-dock.tsx):
const springConfig = { damping: 20, stiffness: 300, mass: 0.5 }
const smoothScale = useSpring(scale, springConfig)
stiffness: 300:弹簧刚度偏高,回弹干脆利落,不拖沓damping: 20:适度阻尼,允许轻微过冲,产生"Q 弹"感mass: 0.5:质量减半,响应更灵敏
随后两个派生值完成细节渲染:size = smoothScale × iconSize 决定图标宽高,y = (scale - 1) × -10 让放大的图标同步上浮最多 10px,悬浮感立刻就有了。
参数速查:一键调节磁吸手感 🎛️
| 参数 | 默认值 | 作用 |
|---|---|---|
iconSize |
56 |
图标基础尺寸(px) |
maxScale |
1.5 |
鼠标正上方时的最大放大倍率 |
magneticDistance |
150 |
磁吸生效的像素半径,越大"磁场"越宽 |
showLabels |
true |
悬停是否显示 tooltip |
position |
"bottom" |
Dock 摆放方位 |
variant |
"glass" |
背景风格 |
想制造更夸张的"巨物感",只需像文档示例一样同时调大两个参数(见 magnetic-dock.tsx 的 Large Scale 示例):iconSize={48} maxScale={2} magneticDistance={200}。
一键安装与最小可用示例 🚀
Magnetic Dock 采用 shadcn 风格的 copy & paste 分发,不是 npm 依赖,代码完全属于你:
npx shadcn@latest add @componentry/magnetic-dock
唯一的外部依赖是 framer-motion(声明见 magnetic-dock.json)。使用时传入 items 数组即可,官方还内置了 7 个预设图标(Home / Search / Folder / Mail / Music / Settings / Trash),参考 magnetic-dock.tsx:
<MagneticDock
items={[
{ id: "home", label: "Home", icon: <DockIconHome />, isActive: true },
{ id: "mail", label: "Mail", icon: <DockIconMail />, badge: 3 },
]}
/>
细节设计:为什么它看起来很"高级" 💎
- 按压反馈:
whileTap={{ scale: 0.9 }}让点击瞬间图标轻微下压,像真实按钮 - 动画出入场:角标、活跃指示点、tooltip 都用
AnimatePresence管理,消失时也能优雅退场 - 性能优先:全链路
MotionValue驱动,鼠标移动零重渲染 - 动效降级:
useReducedMotion检测到系统偏好减少动效时,自动关闭放大与悬浮,仅保留静态布局
相关文件导读 📁
- 组件源码:packages/ui/src/components/magnetic-dock.tsx
- 文档页(含预览与参数表):apps/web/components/docs/magnetic-dock.tsx
- 官方预览示例:apps/web/components/docs/previews/magnetic-dock-preview.tsx
- 注册表定义(安装命令与依赖):apps/web/public/r/magnetic-dock.json
- 组件创建指南:docs/COMPONENT_CREATION_GUIDE.md
总结一句:一段距离插值曲线 + 一组弹簧参数,就是 Magnetic Dock 磁吸放大效果的全部秘密。理解了这套 MotionValue → Transform → Spring 的组合拳,你也可以把它移植到自己的导航栏、工具坞或任何需要"磁性手感"的场景中。

