手把手教你用 Componentry 打造 macOS 风格磁吸导航栏 Magnetic Dock

原创2026-11-09 14:10:301,868 阅读

手把手教你用 Componentry 打造 macOS 风格磁吸导航栏 Magnetic Dock

Componentry 是一个免费开源的 React UI 组件库,主打"复制即用"的交互式动画组件。它内置的 Magnetic Dock(磁吸导航栏) 组件能帮你几行代码做出 macOS Dock 那种"鼠标靠近图标就放大"的磁吸跟随效果,无需自己写任何动画逻辑,新手也能 5 分钟上手。🧲

Componentry 开源 React UI 组件库横幅,包含 macOS 风格磁吸导航栏 Magnetic Dock 组件

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 中查看组件的完整注册信息)。

Componentry 官网首页截图,展示可交互 UI 组件库的整体风格

磁吸 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 中,是"生产级组件"该有的样子。

Componentry 组件目录预览图,展示更多可交互 UI 组件的缩略效果

写在最后

到这里,你只需要一条安装命令 + 一个 items 数组,就拥有了 macOS 质感的磁吸导航栏 🎉。完整属性和官方示例代码可以在 apps/web/components/docs/magnetic-dock.tsx 查看;想继续拓展网站交互,packages/ui/src/components/ 下还有 50+ 个同风格的动画组件(文字变形、滚动编排、WebGL 液态效果等),安装方式完全一样。

去试试吧,让你的网站少一点"静态感",多一点"原生 App 味"!

登录后查看全文
componentry