Naive UI 浮动按钮 FloatButton 完全指南:定位、分组与菜单交互实战

原创2026-09-20 10:39:071,631 阅读
文章标签:前端UI组件设计系统

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 过渡动画。

因此可通过两种方式定制外观:

  1. CSS 变量覆盖:直接对 .n-float-button 覆写 --n-color、--n-box-shadow 等变量;
  2. 主题覆写:通过 NConfigProvider 的 theme-overrides 传入 FloatButton 主题覆写(FloatButtonThemeOverrides),例如修改主色、圆角与阴影。

完整用法可参考 light.ts、dark.ts 以及 组件导出,英文版演示与 API 见 enUS 演示入口。

延伸阅读

登录后查看全文
naive-ui