手把手教你用 Componentry 打造 macOS 风格磁吸导航栏 Magnetic Dock
手把手教你用 Componentry 打造 macOS 风格磁吸导航栏 Magnetic Dock
Componentry 是一个免费开源的 React UI 组件库,主打"复制即用"的交互式动画组件。它内置的 Magnetic Dock(磁吸导航栏) 组件能帮你几行代码做出 macOS Dock 那种"鼠标靠近图标就放大"的磁吸跟随效果,无需自己写任何动画逻辑,新手也能 5 分钟上手。🧲
Componentry 是什么?为什么值得用?
一句话理解:Componentry = 可复制粘贴的生产级 React 组件。
- 📦 不是 npm 依赖:组件代码直接复制进你的项目,代码完全归你所有,想怎么改就怎么改
- ✨ 交互感拉满:基于 React + Tailwind CSS + Framer Motion 打造,磁吸缩放、弹簧动画开箱即用
- 🌗 深色模式:所有组件自动支持亮色 / 暗色两套外观
- 🛡️ 无障碍友好:原生 button 元素 + 键盘焦点支持 + 系统"减弱动态效果"偏好适配
- ⌨️ TypeScript 全类型:属性补全、类型提示一步到位
组件源码集中在 packages/ui/src/components/ 目录,每个组件都是独立文件,维护起来很轻松。
一键安装步骤
Magnetic Dock 兼容 shadcn CLI,在你的项目根目录执行下面这条命令,组件就会被自动复制进去:
npx shadcn@latest add @componentry/magnetic-dock
💡 其他包管理器也可以:
pnpm dlx、yarn dlx、bunx --bun替换npx即可。 该组件依赖framer-motion,安装命令会自动帮你处理依赖声明(可在 apps/web/public/r/magnetic-dock.json 中查看组件的完整注册信息)。
磁吸 Dock 里有什么?先认识一下功能
安装完成后,组件文件位于 components/ui/magnetic-dock.tsx。它内置了 7 个 macOS 风味的预设图标,直接拿来就能拼出一个标准 Dock:
| 图标 | 用途示例 |
|---|---|
DockIconHome |
首页 / 主导航 |
DockIconSearch |
搜索入口 |
DockIconFolder |
文件 / 文件夹 |
DockIconMail |
消息(可带红点角标) |
DockIconMusic |
媒体播放 |
DockIconSettings |
设置页 |
DockIconTrash |
回收站 |
核心效果是怎么来的?组件会实时追踪鼠标在 Dock 上的位置,计算鼠标与每个图标中心的距离,距离越近缩放越大,再叠加一层弹簧物理(stiffness 300、damping 20)让缩放"回弹"得自然,具体实现可以看看 magnetic-dock.tsx 的 useSpring 配置。
除此之外它还自带这些细节:
- 🔍 Tooltip 标签:悬停或键盘聚焦时,图标上方弹出应用名
- 🔴 角标 Badge:像未读消息一样显示数字,超过 99 自动显示 "99+"
- ⚪ 激活指示点:当前所在页面的图标下方会有小圆点
- 👆 按压回弹:点击瞬间图标会轻微缩小,手感更像原生 Dock
快速上手:5 行代码搭出你的 Dock
items 是唯一必传属性,一个数组搞定全部图标。完整用法可参考 magnetic-dock-preview.tsx 的官方预览示例:
const items = [
{ id: "home", label: "Home", icon: <DockIconHome />, isActive: true },
{ id: "search", label: "Search", icon: <DockIconSearch /> },
{ id: "mail", label: "Mail", icon: <DockIconMail />, badge: 3 },
]
<MagneticDock items={items} />
每个 item 支持 6 个字段:
id:唯一标识(字符串)label:悬停时显示的名称icon:任意的 React 节点,预设图标或你自己的图片、SVG 都行onClick:点击回调,接路由跳转最简单isActive:标记当前激活项,会显示底部小圆点badge:红色角标数字
把 onClick 接到你的路由切换上,就立刻变成一个真正的底部导航栏。
常用参数速查表:调出你喜欢的磁吸手感
所有配置项一览(详细类型定义见 magnetic-dock.tsx):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items |
DockItem[] |
必填 | 图标数组 |
iconSize |
number |
56 |
图标基础尺寸(px) |
maxScale |
number |
1.5 |
鼠标正上方的最大放大倍数 |
magneticDistance |
number |
150 |
磁吸生效的像素范围 |
showLabels |
boolean |
true |
是否显示悬停 Tooltip |
position |
"bottom" | "top" | "left" | "right" |
"bottom" |
Dock 摆放方位,左右会自动切换为纵向排列 |
variant |
"glass" | "solid" | "transparent" |
"glass" |
背景风格:毛玻璃 / 实色 / 透明 |
想玩出"夸张版"磁吸效果,参考这个组合:
<MagneticDock
items={items}
iconSize={48}
maxScale={2}
magneticDistance={200}
/>
maxScale 调大、magneticDistance 调大,放大范围和力度都会明显增强,官方预览页就有一个 Large Scale 示例可以对比效果。
细节加分项:无障碍与"减弱动态"
很多炫技组件会忽略可访问性,Magnetic Dock 没有:
- 每个图标是原生
<button>,支持 Tab 键聚焦,聚焦时同样显示 Tooltip 和焦点环 - 图标自带
aria-label,激活项携带aria-current="page",屏幕阅读器友好 - 使用
useReducedMotion检测系统偏好:用户开启"减弱动态效果"后,所有缩放动画自动关闭,图标保持固定尺寸,体验降级但功能完整
这些逻辑都在 magnetic-dock.tsx 中,是"生产级组件"该有的样子。
写在最后
到这里,你只需要一条安装命令 + 一个 items 数组,就拥有了 macOS 质感的磁吸导航栏 🎉。完整属性和官方示例代码可以在 apps/web/components/docs/magnetic-dock.tsx 查看;想继续拓展网站交互,packages/ui/src/components/ 下还有 50+ 个同风格的动画组件(文字变形、滚动编排、WebGL 液态效果等),安装方式完全一样。
去试试吧,让你的网站少一点"静态感",多一点"原生 App 味"!


