Naive UI 浮动按钮 FloatButton 完全指南:定位、分组与菜单交互实战
Naive UI 浮动按钮 FloatButton 完全指南:定位、分组与菜单交互实战
浮动按钮(Float Button)是 Naive UI 在 2.38.0 版本起提供的悬浮操作组件,用于在页面角落承载高频操作入口。它与 Back Top 定位类似,但多了一份颜值与互动——支持徽章、气泡提示、描述文本、分组和子菜单折叠。读完本文,你将掌握 n-float-button 与 n-float-button-group 的全部 Props/Slots 用法、定位与形状配置、菜单触发方式,以及底层源码实现原理与主题定制方法。
组件概览:与 Back Top 相似定位,多一份互动
浮动按钮从视觉与定位上与 Back Top 高度相似:都是固定悬浮在页面四角的圆形容器。区别在于浮动按钮把“图标按钮”本身做成可自定义的通用组件,并扩展出 type(default/primary)、shape(circle/square)、描述文本、子菜单折叠等能力。
从 FloatButton.tsx 的 props 定义可以看到,组件核心由三大类配置构成:
- 定位类:
left、right、top、bottom、position,直接映射为按钮的 CSS 定位属性; - 外观类:
width、height、shape、type,控制尺寸、形状与主题色; - 菜单交互类:
menu-trigger、show-menu、on-update:show-menu,实现子菜单折叠展开。
组件整体是一个带 role="button" 的 <div>,内部结构分为 __fill(背景层)、__body(图标与描述)、__close(关闭图标)与 __menu(子菜单容器)四部分。
基础用法:四个角落的悬浮按钮
最基础的场景是在页面四个角落放置悬浮按钮。下面的例子来自 basic.demo.vue:
<template>
<div style="height: 200px; transform: translate(0)">
<n-float-button :right="0" :bottom="0" shape="square">
<n-icon>
<CashIcon />
</n-icon>
</n-float-button>
<n-float-button :left="0" :bottom="0" shape="square" type="primary">
<n-icon>
<CashIcon />
</n-icon>
</n-float-button>
<n-float-button :right="0" :top="0">
<n-icon>
<CashIcon />
</n-icon>
</n-float-button>
<n-float-button :left="0" :top="0" type="primary">
<n-icon>
<CashIcon />
</n-icon>
</n-float-button>
</div>
</template>
要点说明:
left/right/top/bottom传数值时即对应 CSS 的像素值,传字符串则原样写入 CSS(例如"10%");type="primary"使用主题主色作为背景,default使用浮层色(popover 色)背景,二者在源码中通过cssVarsRef动态切换--n-color、--n-text-color等 CSS 变量(见 FloatButton.tsx);- 默认
position="fixed",在演示容器内如需相对布局,可改传position="relative"; shape决定圆角:circle使用border-radius: 4096px的胶囊圆角,square使用主题变量--n-border-radius-square(见 index.cssr.ts)。
徽章:叠加数量与红点
浮动按钮内部可以自由组合其他 Naive UI 组件。官方 badge.demo.vue 展示了与 n-badge 的组合:
<n-flex>
<n-float-button position="relative">
<n-badge :value="9" :offset="[6, -8]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
<n-float-button position="relative">
<n-badge :value="100" :max="99" :offset="[6, -8]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
<n-float-button position="relative">
<n-badge dot :offset="[4, -4]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
<n-float-button position="relative">
<n-badge value="新" :offset="[6, -6]">
<n-icon><AlarmOutlineIcon /></n-icon>
</n-badge>
</n-float-button>
</n-flex>
实用技巧:
n-badge的:offset用于微调徽章在按钮角上的位置,负偏移让它骑在圆角边缘;:max="99"控制数字上限,超出显示为99+;dot模式渲染纯红点,value="新"则直接展示文本徽章;- 此场景必须使用
position="relative",让按钮在文档流中占位,徽章才能正确吸附在图标上。
气泡提示:悬浮按钮 + Tooltip
悬浮按钮常需要解释性文案,官方 tooltip.demo.vue 演示了与 n-tooltip 的配合——将浮动按钮放入 tooltip 的 #trigger 插槽,按钮本身使用 position="relative":
<n-tooltip trigger="hover" placement="right">
<template #trigger>
<n-float-button position="relative">
<n-icon><CashIcon /></n-icon>
</n-float-button>
</template>
这个故事还没有完结
</n-tooltip>
当鼠标悬停按钮时,气泡从右侧滑出显示说明文字。这也是 tooltip 与 float-button 组合的标准写法,无需额外状态管理。
描述文本:description 插槽
如果不想借助 Tooltip,可以直接通过 description 插槽在按钮内部(图标下方)展示描述信息。官方 custom.demo.vue 示例:
<n-float-button shape="square">
<n-icon><DocumentIcon /></n-icon>
<template #description>
文档
</template>
</n-float-button>
源码层面,description 插槽渲染在 __description 元素中,样式为 font-size: 12px; line-height: 14px; text-align: center(见 index.cssr.ts),并且 __body 使用 flex-direction: column 排列图标与描述。这意味着:
- 有
description时按钮自动变为“图标在上、文字在下”的竖向布局; - 文字过长时会换行并居中,按钮高度跟随内容自适应(高度由
minHeight保证); - 若同时设置
shape="square"会更适合容纳两行内容。
浮动按钮组:n-float-button-group
当操作项较多时,可以把多个按钮包进 n-float-button-group,形成统一外观的按钮组。官方 group.demo.vue 展示了 square 与 circle 两种形态:
<n-flex align="flex-start">
<n-float-button-group shape="square" position="relative">
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
</n-float-button-group>
<n-float-button-group position="relative">
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
</n-float-button-group>
</n-flex>
分组背后的实现机制值得理解(对应 FloatButtonGroup.tsx):
n-float-button-group通过provide(floatButtonGroupInjectionKey, { shapeRef: toRef(props, 'shape') })向子按钮注入组配置;- 子按钮(FloatButton.tsx)通过
inject感知自己是否位于组内:若在组内,position与left/right/top/bottom定位属性一律失效,改为position: relative参与组内流式排布,形状也以组的shape为准(mergedShapeRef); - square 组渲染为一个带背景和阴影的整体容器,按钮之间以 1px
--n-button-border-color分隔线相连,首尾按钮圆角 4px(见 FloatButtonGroup 样式); - circle 组则保持独立圆形按钮,通过
margin-bottom: 16px纵向堆叠排列(见 FloatButtonGroup 样式)。
菜单显示:menu-trigger 折叠子菜单
FloatButton 最具特色的能力是“一键展开子菜单”。官方 menu.demo.vue 展示了 hover 与 click 两种触发方式:
<n-float-button position="relative" type="primary" menu-trigger="hover">
<n-icon><CashIcon /></n-icon>
<template #menu>
<n-float-button shape="square" type="primary">
<n-icon><CashIcon /></n-icon>
</n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
</template>
</n-float-button>
<n-float-button position="relative" type="primary" menu-trigger="click">
<n-icon><CashIcon /></n-icon>
<template #menu>
<!-- 与上面相同的子按钮 -->
</template>
</n-float-button>
交互与实现细节(见 FloatButton.tsx 与 index.cssr.ts):
menu-trigger="hover":鼠标进入(mouseenter)打开菜单,鼠标移出按钮范围(通过 evtd 的mousemoveoutside事件监听)自动关闭;menu-trigger="click":点击按钮切换开合状态;- 菜单打开时主按钮的
__body(图标)会缩小为scale(0.75)并淡出,__close位置的关闭图标淡入,__menu容器从按钮正上方弹出(bottom: 100%),子按钮之间margin-bottom: 16px纵向排列; - 菜单容器监听了
click并stopPropagation,避免点击子按钮误触主按钮的切换逻辑(见 FloatButton.tsx)。
受控与非受控:show-menu 与 on-update:show-menu
菜单的开合状态同时支持受控与非受控两种模式,源码使用 vooks 的 useMergedState 合并两者(FloatButton.tsx):
- 非受控:不传
show-menu,组件内部用uncontrolledShowMenuRef维护状态,交互自动开合; - 受控:传入
show-menu后由父组件完全接管开合状态,父组件需监听on-update:show-menu并回写值; - 事件触发时会同时调用
onUpdateShowMenu与on-update:show-menu两种写法(都支持函数或函数数组),兼容性更好。
<template>
<n-float-button
menu-trigger="click"
:show-menu="show"
@update:show-menu="show = $event"
>
<n-icon><CashIcon /></n-icon>
<template #menu>
<n-float-button><n-icon><CashIcon /></n-icon></n-float-button>
</template>
</n-float-button>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const show = ref(false)
</script>
API 参考
以下参数表完整来自 index.demo-entry.md,默认值与类型与源码 FloatButton.tsx 一一对应。
FloatButton Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
| bottom | number | string |
40 |
按钮的 CSS bottom 属性 |
2.38.0 |
| height | number | string |
40 |
按钮的 CSS height 属性 |
2.38.0 |
| left | number | string |
undefined |
按钮的 CSS left 属性 |
2.38.0 |
| menu-trigger | 'click' | 'hover' |
undefined |
触发菜单显示的方式 | 2.38.0 |
| position | 'relative' | 'absolute' | 'fixed' |
'fixed' |
按钮的定位方式 | 2.38.0 |
| right | number | string |
undefined |
按钮的 CSS right 属性 |
2.38.0 |
| shape | 'circle' | 'square' |
'circle' |
按钮的形状 | 2.38.0 |
| show-menu | boolean |
undefined |
是否打开菜单(受控) | 2.38.0 |
| top | number | string |
undefined |
按钮的 CSS top 属性 |
2.38.0 |
| type | 'default' | 'primary' |
'default' |
按钮的类型 | 2.38.0 |
| width | number | string |
40 |
按钮的 CSS width 属性 |
2.38.0 |
| on-update:show-menu | (value: boolean) => void |
undefined |
菜单打开或者关闭的回调 | 2.38.0 |
补充说明:
width、height在源码中的默认值均为40(文档表格未列出的默认值以源码为准),渲染时通过formatLength统一处理数字/字符串;position默认fixed,但在组内会自动退化为relative(由注入机制覆盖,见 FloatButton.tsx);type仅影响颜色变量(--n-color、--n-color-hover、--n-color-pressed等),不影响尺寸与形状。
FloatButtonGroup Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
| bottom | number | string |
undefined |
按钮组的 CSS bottom 属性 |
2.38.0 |
| left | number | string |
undefined |
按钮组的 CSS left 属性 |
2.38.0 |
| position | 'relative' | 'absolute' | 'fixed' |
'fixed' |
按钮组的定位方式 | 2.38.0 |
| right | number | string |
undefined |
按钮组的 CSS right 属性 |
2.38.0 |
| shape | 'circle' | 'square' |
'circle' |
按钮组的形状 | 2.38.0 |
| top | number | string |
undefined |
按钮组的 CSS top 属性 |
2.38.0 |
FloatButton Slots
| 名称 | 参数 | 说明 | 版本 |
|---|---|---|---|
| default | () |
按钮主体内容(通常放 n-icon) |
2.38.0 |
| description | () |
按钮中的描述信息,渲染在图标下方 | 2.38.0 |
| menu | () |
按钮会触发的子菜单,可放置多个 n-float-button |
2.38.0 |
主题定制:CSS 变量与 ThemeOverrides
浮动按钮的视觉完全由 CSS 变量驱动(变量清单见 index.cssr.ts):--n-color、--n-color-hover、--n-color-pressed、--n-text-color、--n-box-shadow、--n-box-shadow-hover、--n-box-shadow-pressed、--n-bezier、--n-border-radius-square。
主题变量定义在 light.ts 的 self 函数中:
color(默认背景)取自popoverColor浮层色;colorHover/colorPressed取自按钮类通用变量buttonColor2Hover/buttonColor2Pressed;type="primary"时使用primaryColor系列主色,文字色textColorPrimary为#fff;- 阴影三级递进:
0 2px 8px rgba(0,0,0,.16)(常态)→0 2px 12px rgba(0,0,0,.24)(hover/active),配合--n-bezier完成 0.3s 过渡动画。
因此可通过两种方式定制外观:
- CSS 变量覆盖:直接对
.n-float-button覆写--n-color、--n-box-shadow等变量; - 主题覆写:通过
NConfigProvider的theme-overrides传入FloatButton主题覆写(FloatButtonThemeOverrides),例如修改主色、圆角与阴影。
完整用法可参考 light.ts、dark.ts 以及 组件导出,英文版演示与 API 见 enUS 演示入口。
延伸阅读
- 若只需“回到顶部”,可对比使用 Back Top 组件;
- 按钮组的分组注入机制与测试见 NFloatButtonGroup.spec.tsx 与 server.spec.tsx(含 SSR 渲染验证);
- 主题变量总览与扩展方式可阅读 theme 目录 与 themes。