BubbleMenu
bubble-menu从气泡按钮展开一屏错落排布的胶囊导航
用法
基础用法
logo 气泡 + 汉堡切换钮，点切换钮展开整屏错落胶囊导航。缺省用内置 5 项示例；需 relative + 定高容器锚定 absolute 定位。
tsx
<div className="relative h-96 overflow-hidden rounded-xl border">
<BubbleMenu logo={<span>瑚琏</span>} />
</div>自定义菜单项
items 自定义胶囊：label / href，rotation 营造手作错落感，hoverStyles 设悬停反色（建议吃 chart token）。
tsx
const items = [
{ label: "首页", href: "#", rotation: -6,
hoverStyles: { bgColor: "var(--color-chart-1)", textColor: "var(--color-primary-foreground)" } },
{ label: "文档", href: "#", rotation: 6,
hoverStyles: { bgColor: "var(--color-chart-2)", textColor: "var(--color-primary-foreground)" } },
{ label: "联系", href: "#", rotation: -4,
hoverStyles: { bgColor: "var(--color-chart-3)", textColor: "var(--color-primary-foreground)" } },
];
<BubbleMenu logo={<span>瑚琏</span>} items={items} />入场节奏
animationDuration 调单胶囊弹入时长，staggerDelay 调相邻胶囊错峰延迟，越小越紧凑。
tsx
<BubbleMenu
logo={<span>瑚琏</span>}
items={items}
animationDuration={0.3}
staggerDelay={0.05}
/>何时用
营销站/作品集这类需要花哨全屏遮罩式主导航时用：点汉堡铺开一组错落旋转的胶囊链接。它是炫技型一级导航；要规范的多级下拉/横向导航条用 NavigationMenu/NavMenu，要标准应用顶栏用 Navbar，要展开成卡片的那种用 CardNav。
导入
ts
import { BubbleMenu } from "@hulianui/ui"Props
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| items | BubbleMenuItem[] | 内置示例项 | 菜单项列表，缺省用内置示例 |
| menuAriaLabel | string | - | 切换按钮无障碍标签 |
| useFixedPosition | boolean | false | true=fixed（贴视口），false=absolute（贴最近定位父级） |
| animationDuration | number | 0.5 | 单个胶囊弹入动画时长（秒） |
| staggerDelay | number | 0.12 | 相邻胶囊入场错峰延迟（秒） |
| className | string | - | 透传根 nav 额外类名 |
| style | CSSProperties | - | 透传根 nav 内联样式 |
BubbleMenuItem
| 名称 | 类型 | 默认 | 说明 |
|---|---|---|---|
| label * | string | - | 链接文案 |
| href * | string | - | 跳转地址 |
| ariaLabel | string | 回退到 label | 无障碍标签 |
| rotation | number | - | 桌面端胶囊的旋转角度（度），营造手作错落感；移动端自动归零 |
| hoverStyles | { bgColor?: string; textColor?: string } | - | 悬停反色配置 |
Events
| 事件 | 类型 | 说明 |
|---|---|---|
| onMenuClick | (isOpen: boolean) => void | 开合状态回调，参数为下一状态是否打开 |
Slots
| 插槽 | 类型 | 说明 |
|---|---|---|
| logo | ReactNode | 左上角 logo 气泡内容：字符串当图片 src，ReactNode 直接渲染 |
禁忌 / 坑
useFixedPosition={false}（默认）时根 nav 为 absolute，须有position: relative的定位父级（否则贴到更外层）；做真实站点顶栏一般要useFixedPosition或自行控制定位上下文。- 父容器需
overflow-hidden收住展开时铺满的气泡层。 - 颜色走 token 用
--color-前缀。reduced-motion 下入场动效降级。
相关
Navbar · BeianFooter · NavMenu · NavigationMenu · Menu · Menubar
Playground
<div className="relative h-96 overflow-hidden rounded-xl">
<BubbleMenu
logo={<span>瑚琏</span>}
animationDuration={0.5}
staggerDelay={0.12}
useFixedPosition={false}
/>
</div>