Dock

dock

一排会随鼠标靠近放大的图标快捷入口

用法

常驻底部导航（选中态）

activeKey + onSelect 是受控范式，与 NavMenu / RouteTabs 一致。选中项落 aria-current="page"，视觉上是图标下方的指示点——形状线索，不只靠颜色。接了 onSelect 后 DockIcon 会渲染成真正的 <button>（可聚焦、可回车激活），底座也升级为 nav 地标。

当前：首页

tsx

const [active, setActive] = useState("home")

<Dock aria-label="主导航" activeKey={active} onSelect={setActive}>
  <DockIcon itemKey="home" label="首页"><Home className="size-5" /></DockIcon>
  <DockIcon itemKey="search" label="搜索"><Search className="size-5" /></DockIcon>
  <DockIcon itemKey="alerts" label="通知"><Bell className="size-5" /></DockIcon>
  <DockIcon itemKey="settings" label="设置"><Settings className="size-5" /></DockIcon>
</Dock>

基础用法

DockIcon 包裹图标，鼠标靠近时图标按水平距离放大（macOS 放大坞效果）。

tsx

<Dock>
  <DockIcon><Home className="size-5" /></DockIcon>
  <DockIcon><Search className="size-5" /></DockIcon>
  <DockIcon><Bell className="size-5" /></DockIcon>
  <DockIcon><Settings className="size-5" /></DockIcon>
  <DockIcon><User className="size-5" /></DockIcon>
</Dock>

更强放大

magnification 调高峰值尺寸、distance 调大影响范围，得到更夸张的放大效果。

tsx

<Dock magnification={84} distance={160}>
  <DockIcon><Home className="size-5" /></DockIcon>
  <DockIcon><Search className="size-5" /></DockIcon>
  <DockIcon><Bell className="size-5" /></DockIcon>
</Dock>

自定义静息尺寸

iconSize 设定未悬停时的基础尺寸，适配更紧凑或更宽松的坞。

tsx

<Dock iconSize={32}>
  <DockIcon><Home className="size-4" /></DockIcon>
  <DockIcon><Search className="size-4" /></DockIcon>
  <DockIcon><Settings className="size-4" /></DockIcon>
</Dock>

何时用

页面底部/侧边的悬浮快捷入口栏，鼠标靠近时图标按距离弹性放大，营造 macOS Dock 观感，多用于个人站、作品集、桌面风格 demo。常规站点导航用 Navbar；功能性下拉/菜单条用 Menu / Menubar。

导入

import { Dock, DockIcon } from "@hulianui/ui"

Props

Dock

名称	类型	默认	说明
magnification	`number`	-	鼠标靠近时图标放大到的峰值尺寸(px)
distance	`number`	-	放大影响范围半径(px)
iconSize	`number`	-	静息图标尺寸(px)
activeKey	`string`	-	当前项 key，与 DockIcon 的 `itemKey` 比对
onSelect	`(key: string) => void`	-	点击某项。提供它才把 DockIcon 渲染成真正的 `<button>`，底座同时升级为 `nav` 地标
aria-label	`string`	-	渲染为 `<nav>` 时的地标名称
className	`string`	-	-

DockIcon

名称	类型	默认	说明
itemKey	`string`	-	本项 key，配合 Dock 的 `activeKey` / `onSelect`
active	`boolean`	-	直接指定选中态，优先于 `activeKey` 比对结果
label	`string`	-	可点击时的无障碍名（图标本身通常没有文字）
className	`string`	-	-

Slots

Dock

插槽	类型	说明
children	`ReactNode`	一组 `DockIcon`

DockIcon

插槽	类型	说明
children	`ReactNode`	单个图标内容

禁忌 / 坑

选中态是 Dock 的核心信息，不是装饰。macOS Dock 本身就有「当前应用高亮」与「运行中指示点」；Web 上 Dock 的典型用法是常驻底部导航，同样要回答「我现在在哪」。用 activeKey + DockIcon 的 itemKey 表达，组件会给出 aria-current="page" 与图标下方的指示点（形状线索，不只靠颜色）。
接了 `onSelect` 才会渲染成真正的 `<button>`（可聚焦、可回车激活），底座同时升级为 nav 地标。不接时 DockIcon 保持无语义容器 —— 因为很多消费方是往 children 里放自己的 <a> 的，自动包一层 button 会造成嵌套交互元素。

候选坑 skill（macos-dock-icon-needs-baked-squircle-margin、tauri-macos-hide-to-tray）均针对原生 macOS / Tauri 的系统 Dock，与本 React 组件无关，不适用。
放大依赖随鼠标移动下发的 mouseX（context + motion 弹簧），是纯客户端交互；图标统一用固定尺寸（如 size-5）以便放大动画一致。

用法

常驻底部导航（选中态）

当前：首页

tsx

const [active, setActive] = useState("home")

<Dock aria-label="主导航" activeKey={active} onSelect={setActive}>
  <DockIcon itemKey="home" label="首页"><Home className="size-5" /></DockIcon>
  <DockIcon itemKey="search" label="搜索"><Search className="size-5" /></DockIcon>
  <DockIcon itemKey="alerts" label="通知"><Bell className="size-5" /></DockIcon>
  <DockIcon itemKey="settings" label="设置"><Settings className="size-5" /></DockIcon>
</Dock>

基础用法

DockIcon 包裹图标，鼠标靠近时图标按水平距离放大（macOS 放大坞效果）。

tsx

<Dock>
  <DockIcon><Home className="size-5" /></DockIcon>
  <DockIcon><Search className="size-5" /></DockIcon>
  <DockIcon><Bell className="size-5" /></DockIcon>
  <DockIcon><Settings className="size-5" /></DockIcon>
  <DockIcon><User className="size-5" /></DockIcon>
</Dock>

更强放大

magnification 调高峰值尺寸、distance 调大影响范围，得到更夸张的放大效果。

tsx

<Dock magnification={84} distance={160}>
  <DockIcon><Home className="size-5" /></DockIcon>
  <DockIcon><Search className="size-5" /></DockIcon>
  <DockIcon><Bell className="size-5" /></DockIcon>
</Dock>

自定义静息尺寸

iconSize 设定未悬停时的基础尺寸，适配更紧凑或更宽松的坞。

tsx

<Dock iconSize={32}>
  <DockIcon><Home className="size-4" /></DockIcon>
  <DockIcon><Search className="size-4" /></DockIcon>
  <DockIcon><Settings className="size-4" /></DockIcon>
</Dock>

Props

Dock

名称	类型	默认	说明
magnification	`number`	-	鼠标靠近时图标放大到的峰值尺寸(px)
distance	`number`	-	放大影响范围半径(px)
iconSize	`number`	-	静息图标尺寸(px)
activeKey	`string`	-	当前项 key，与 DockIcon 的 `itemKey` 比对
onSelect	`(key: string) => void`	-	点击某项。提供它才把 DockIcon 渲染成真正的 `<button>`，底座同时升级为 `nav` 地标
aria-label	`string`	-	渲染为 `<nav>` 时的地标名称
className	`string`	-	-

DockIcon

名称	类型	默认	说明
itemKey	`string`	-	本项 key，配合 Dock 的 `activeKey` / `onSelect`
active	`boolean`	-	直接指定选中态，优先于 `activeKey` 比对结果
label	`string`	-	可点击时的无障碍名（图标本身通常没有文字）
className	`string`	-	-

插槽

类型

说明

children

ReactNode

一组 DockIcon

插槽

类型

说明

children

ReactNode

单个图标内容

禁忌 / 坑

选中态是 Dock 的核心信息，不是装饰。macOS Dock 本身就有「当前应用高亮」与「运行中指示点」；Web 上 Dock 的典型用法是常驻底部导航，同样要回答「我现在在哪」。用 activeKey + DockIcon 的 itemKey 表达，组件会给出 aria-current="page" 与图标下方的指示点（形状线索，不只靠颜色）。

接了 `onSelect` 才会渲染成真正的 `<button>`（可聚焦、可回车激活），底座同时升级为 nav 地标。不接时 DockIcon 保持无语义容器 —— 因为很多消费方是往 children 里放自己的 <a> 的，自动包一层 button 会造成嵌套交互元素。

候选坑 skill（macos-dock-icon-needs-baked-squircle-margin、tauri-macos-hide-to-tray）均针对原生 macOS / Tauri 的系统 Dock，与本 React 组件无关，不适用。

放大依赖随鼠标移动下发的 mouseX（context + motion 弹簧），是纯客户端交互；图标统一用固定尺寸（如 size-5）以便放大动画一致。

Dock

用法

常驻底部导航（选中态）

基础用法

更强放大

自定义静息尺寸

何时用

导入

Props

Dock

DockIcon

Slots

Dock

DockIcon

禁忌 / 坑

相关

Dock

用法

常驻底部导航（选中态）

基础用法

更强放大

自定义静息尺寸

何时用

导入

Props

Dock

DockIcon

Slots

Dock

DockIcon

禁忌 / 坑

相关