FloatButton 悬浮按钮
浮在页面上的圆形或方形按钮,常放在右下角做“帮助”“反馈”“新建”这类全局入口。可以带文字提示、角标、展开一组子按钮(菜单),也可以用 NsFloatButtonGroup 把几个按钮竖着排成一组。
引入
import { NsFloatButton, NsFloatButtonGroup } from '@ns/ui'
基础用法
icon 是图标名,tooltip 是悬停或聚焦时的文字提示(默认显示在左边)。默认 position="fixed",用 right、bottom 等定位,数字按 px,字符串原样使用(如 '10%')。
为了在示例框里看效果,本页的示例用 position="absolute"(相对设了 position: relative 的示例框定位)或 position="relative"(留在原位置,和别的元素排在一起),三种定位方式的区别见下一节。
<script setup lang="ts">
import { NsFloatButton, NsMessage } from '@ns/ui'
const openHelp = () => {
NsMessage.info('打开帮助中心')
}
</script>
<template>
<div class="stage">
<NsFloatButton
icon="help"
tooltip="帮助中心"
position="absolute"
:right="24"
:bottom="24"
@click="openHelp"
/>
</div>
</template>
<style scoped>
.stage {
position: relative;
height: 120px;
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
background-color: var(--ns-bg-color-page);
}
</style>
只有图标时,按钮的可读名称(aria-label)用 tooltip 的文字,所以只有图标的按钮要写 tooltip(或者自己写 aria-label),否则开发环境下会在控制台警告。
定位方式
position 可选:
fixed(默认):固定在浏览器窗口上,不随页面滚动。z-index 跟随NsConfigProvider的zIndex(默认 2000)。absolute:相对最近的定位祖先(position不是static的元素),配合left、right、top、bottom放在某个区域的角落。relative:留在原来的位置,和前后的内容排在一起,left等是相对原位置的偏移。
打开开关后,fixed 的按钮出现在浏览器窗口的右下角:
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatButton, NsSpace, NsSwitch } from '@ns/ui'
const showFixed = ref(false)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSwitch v-model="showFixed" active-text="显示 fixed 按钮(窗口右下角)" />
<div class="stage">
<NsSpace>
<span>relative,留在原位置:</span>
<NsFloatButton icon="star" tooltip="relative" position="relative" />
</NsSpace>
<NsFloatButton
icon="bell"
tooltip="absolute,在示例框右下角"
type="primary"
position="absolute"
:right="24"
:bottom="24"
/>
</div>
</NsSpace>
<NsFloatButton
v-if="showFixed"
icon="heart"
tooltip="fixed,固定在窗口右下角"
type="primary"
:right="40"
:bottom="40"
/>
</template>
<style scoped>
.stage {
position: relative;
height: 120px;
padding: 16px;
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
background-color: var(--ns-bg-color-page);
}
</style>
类型和形状
type:default(白底,默认)或primary(主色底、白色图标)。shape:circle(圆形,默认)或square(圆角方形,圆角 8px)。
<template>
<NsSpace size="large">
<NsFloatButton icon="help" tooltip="default + circle" position="relative" />
<NsFloatButton icon="plus" type="primary" tooltip="primary + circle" position="relative" />
<NsFloatButton icon="bell" shape="square" tooltip="default + square" position="relative" />
<NsFloatButton
icon="edit"
type="primary"
shape="square"
tooltip="primary + square"
position="relative"
/>
</NsSpace>
</template>
文字提示的位置
tooltip-placement 是文字提示的位置,默认 left,可选 12 个方向,放不下时自动翻到另一侧。把鼠标移到下面的按钮上看效果,按钮下面的小字是方向:
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsFloatButton
shape="square"
icon="arrow-up"
description="top"
tooltip="top"
tooltip-placement="top"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-up"
description="top-start"
tooltip="top-start"
tooltip-placement="top-start"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-up"
description="top-end"
tooltip="top-end"
tooltip-placement="top-end"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-down"
description="bottom"
tooltip="bottom"
tooltip-placement="bottom"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-down"
description="bottom-start"
tooltip="bottom-start"
tooltip-placement="bottom-start"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-down"
description="bottom-end"
tooltip="bottom-end"
tooltip-placement="bottom-end"
position="relative"
:width="96"
/>
</NsSpace>
<NsSpace wrap>
<NsFloatButton
shape="square"
icon="arrow-left"
description="left"
tooltip="left"
tooltip-placement="left"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-left"
description="left-start"
tooltip="left-start"
tooltip-placement="left-start"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-left"
description="left-end"
tooltip="left-end"
tooltip-placement="left-end"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-right"
description="right"
tooltip="right"
tooltip-placement="right"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-right"
description="right-start"
tooltip="right-start"
tooltip-placement="right-start"
position="relative"
:width="96"
/>
<NsFloatButton
shape="square"
icon="arrow-right"
description="right-end"
tooltip="right-end"
tooltip-placement="right-end"
position="relative"
:width="96"
/>
</NsSpace>
</NsSpace>
</template>
描述文字和尺寸
description 是图标下面的小字(12px),一般和 shape="square" 一起用;有描述文字时图标从 20px 缩小到 16px。40px 宽的按钮放得下两个汉字,更长的显示省略号,要用 width 加宽。width、height 改大小,默认都是 40,数字按 px,字符串原样使用;内容放不下时按钮会自动变高。description 插槽可以放自定义的描述内容,优先于 description 属性。
默认插槽可以放自定义图标或文字,写了默认插槽时不显示 icon。
<template>
<NsSpace size="large" align="end">
<NsFloatButton shape="square" icon="mail" description="反馈" position="relative" />
<NsFloatButton
shape="square"
icon="phone"
description="电话客服(被截断)"
position="relative"
/>
<NsFloatButton
shape="square"
icon="phone"
description="电话客服"
:width="64"
:height="56"
position="relative"
/>
<NsFloatButton shape="square" icon="user" width="4rem" height="4rem" position="relative">
<template #description>
<span style="color: var(--ns-color-primary)">我的</span>
</template>
</NsFloatButton>
<NsFloatButton tooltip="AI 助手" position="relative">
<span style="font-weight: 600">AI</span>
</NsFloatButton>
<NsFloatButton
tooltip="大按钮"
icon="plus"
type="primary"
:width="56"
:height="56"
position="relative"
/>
</NsSpace>
</template>
角标
badge 在右上角显示角标(用的是 NsBadge):
- 数字或字符串:显示内容,数字超过 99 显示
99+; true,或者只写badge:显示小圆点;false、0:不显示。要显示 0 时传字符串'0'。
圆形按钮的角标贴着圆的边(对准右上方 45° 的位置),方形按钮的对准外框的角。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsFloatButton, NsSpace } from '@ns/ui'
const unread = ref(5)
</script>
<template>
<NsSpace direction="vertical" align="start" size="large">
<NsSpace size="large">
<NsFloatButton icon="bell" tooltip="通知" :badge="unread" position="relative" />
<NsFloatButton icon="user" tooltip="新动态" badge position="relative" />
<NsFloatButton icon="mail" tooltip="99+" :badge="120" position="relative" />
<NsFloatButton icon="star" tooltip="文字角标" badge="new" position="relative" />
<NsFloatButton icon="file" tooltip="字符串 '0'" badge="0" position="relative" />
<NsFloatButton icon="folder" tooltip="数字 0 不显示" :badge="0" position="relative" />
<NsFloatButton
icon="bell"
shape="square"
tooltip="方形按钮"
:badge="unread"
position="relative"
/>
</NsSpace>
<NsSpace>
<NsButton size="small" @click="unread++">未读 +1</NsButton>
<NsButton size="small" @click="unread = 0">清空(0 时不显示)</NsButton>
</NsSpace>
</NsSpace>
</template>
角标对读屏软件隐藏,不进按钮的可读名称。需要读出数量时把它写进 aria-label,例如 :aria-label="'通知,' + unread + ' 条未读'"。
链接
写了 href 就渲染成 <a>,target="_blank" 时自动加 rel="noopener noreferrer"(自己写了 rel 时用自己的)。
<template>
<NsSpace size="large">
<NsFloatButton
icon="link"
tooltip="使用手册(新窗口打开)"
href="https://example.com/manual"
target="_blank"
position="relative"
/>
<NsFloatButton
icon="download"
shape="square"
description="下载"
href="https://example.com/download"
target="_blank"
position="relative"
/>
</NsSpace>
</template>
展开菜单
menu 插槽里放几个 NsFloatButton,它们竖着排在主按钮上方,点主按钮展开、再点收起;展开时主按钮的图标换成关闭图标(close)。
menu-trigger="click"(默认):点击展开、再点收起;在页面其他地方按下鼠标、或者焦点移到别处时收起。menu-trigger="hover":鼠标移入展开,移出 100ms 后收起;鼠标移到子按钮上不收起。点击主按钮也能展开(触屏设备没有悬停),但不会收起。- 用
v-model:show-menu读写展开状态。 - 点了子按钮菜单不收起,要收起时把
show-menu改成false。
子按钮不用写 position、right 等,由菜单排列;shape 不写时跟随主按钮。下面左边是点击展开,右边是悬停展开(方形,子按钮跟着变方形):
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatButton, NsMessage } from '@ns/ui'
const open = ref(false)
const hoverOpen = ref(false)
const create = (kind: string) => {
open.value = false
NsMessage.success(`新建${kind}`)
}
</script>
<template>
<div class="stage">
<p class="state">
点击菜单:{{ open ? '展开' : '收起' }};悬停菜单:{{ hoverOpen ? '展开' : '收起' }}
</p>
<NsFloatButton
v-model:show-menu="open"
type="primary"
icon="plus"
tooltip="新建"
menu-trigger="click"
position="absolute"
:left="40"
:bottom="24"
>
<template #menu>
<NsFloatButton icon="file" tooltip="新建文档" @click="create('文档')" />
<NsFloatButton icon="folder" tooltip="新建文件夹" @click="create('文件夹')" />
<NsFloatButton icon="table" tooltip="新建表格" @click="create('表格')" />
</template>
</NsFloatButton>
<NsFloatButton
v-model:show-menu="hoverOpen"
shape="square"
icon="share"
tooltip="分享"
menu-trigger="hover"
position="absolute"
:left="120"
:bottom="24"
>
<template #menu>
<NsFloatButton icon="mail" tooltip="邮件分享" />
<NsFloatButton icon="link" tooltip="复制链接" />
</template>
</NsFloatButton>
</div>
</template>
<style scoped>
.stage {
position: relative;
height: 260px;
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
background-color: var(--ns-bg-color-page);
}
.state {
margin: 0;
padding: 12px 16px;
color: var(--ns-text-color-secondary);
}
</style>
按钮组
NsFloatButtonGroup 把几个悬浮按钮竖着排成一组,组负责定位(position、left、right、top、bottom,规则同 NsFloatButton),组里的按钮自己的 position、right 等不生效。
shape="circle"(默认):圆形按钮,之间隔 16px,各自带阴影。shape="square":方形按钮连成一整块,按钮之间是一条分隔线,阴影和外圆角在组上。
组里按钮的形状统一跟随组的 shape,按钮自己写的 shape 不生效。下面左边是 circle,右边是 square:
<script setup lang="ts">
import { NsFloatButton, NsFloatButtonGroup, NsMessage } from '@ns/ui'
const notify = (text: string) => {
NsMessage.info(text)
}
</script>
<template>
<div class="stage">
<NsFloatButtonGroup position="absolute" :left="40" :bottom="24" aria-label="快捷操作">
<NsFloatButton icon="help" tooltip="帮助" @click="notify('帮助')" />
<NsFloatButton icon="mail" tooltip="反馈" :badge="2" @click="notify('反馈')" />
<NsFloatButton icon="arrow-up" tooltip="顶部" @click="notify('回到顶部')" />
</NsFloatButtonGroup>
<NsFloatButtonGroup
position="absolute"
:left="120"
:bottom="24"
shape="square"
aria-label="快捷操作"
>
<NsFloatButton icon="help" description="帮助" @click="notify('帮助')" />
<NsFloatButton icon="mail" description="反馈" :badge="2" @click="notify('反馈')" />
<NsFloatButton icon="arrow-up" description="顶部" @click="notify('回到顶部')" />
</NsFloatButtonGroup>
</div>
</template>
<style scoped>
.stage {
position: relative;
height: 220px;
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
background-color: var(--ns-bg-color-page);
}
</style>
组的根元素是 role="group",可以写 aria-label="快捷操作" 给读屏软件一个名称。
和回到顶部一起用
单独的回到顶部按钮用 NsBacktop:它自己监听滚动,滚过 visibility-height 才出现,外观(40×40 的圆、边框、阴影、图标大小)和 NsFloatButton 一致。两个按钮分开放时错开位置即可,例如 NsBacktop 在 bottom: 40,悬浮按钮在 bottom: 96。
NsBacktop 自己是 fixed 定位,不能直接放进 NsFloatButtonGroup(放进去也会按自己的 right、bottom 固定在视口上,不在组里排列)。组里要“回到顶部”时,用 NsFloatButton 加 icon="arrow-up",滚动位置自己判断。下面在框里往下滚,滚过 200px 后组里多出“回到顶部”:
<script setup lang="ts">
import { ref } from 'vue'
import { NsFloatButton, NsFloatButtonGroup } from '@ns/ui'
const boxRef = ref<HTMLElement>()
const showTop = ref(false)
// 监听页面滚动时换成 window.scrollY 和 window.addEventListener('scroll', ...)
const update = () => {
showTop.value = (boxRef.value?.scrollTop ?? 0) >= 200
}
const toTop = () => boxRef.value?.scrollTo({ top: 0, behavior: 'smooth' })
</script>
<template>
<div class="stage">
<div ref="boxRef" class="box" @scroll="update">
<p v-for="i in 30" :key="i" class="line">第 {{ i }} 行内容</p>
</div>
<NsFloatButtonGroup position="absolute" :right="24" :bottom="16">
<NsFloatButton icon="help" tooltip="帮助" />
<NsFloatButton v-if="showTop" icon="arrow-up" tooltip="回到顶部" @click="toTop" />
</NsFloatButtonGroup>
</div>
</template>
<style scoped>
.stage {
position: relative;
}
.box {
height: 240px;
overflow: auto;
padding: 0 16px;
border: 1px solid var(--ns-border-color);
border-radius: var(--ns-border-radius);
}
.line {
margin: 12px 0;
color: var(--ns-text-color-secondary);
}
</style>
聚焦和失焦
通过 ref 调用 focus()、blur() 让主按钮获得、失去焦点,聚焦时会显示文字提示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsFloatButton, NsSpace } from '@ns/ui'
const fabRef = ref<InstanceType<typeof NsFloatButton>>()
</script>
<template>
<NsSpace size="large">
<NsButton @click="fabRef?.focus()">聚焦</NsButton>
<NsButton @click="fabRef?.blur()">失焦</NsButton>
<NsFloatButton
ref="fabRef"
icon="setting"
tooltip="聚焦时显示提示"
tooltip-placement="right"
position="relative"
/>
</NsSpace>
</template>
键盘操作
- 主按钮是原生
<button>(有href时是<a>),Tab 能聚焦,聚焦时显示文字提示;<button>回车、空格触发,<a>回车触发。 - 有菜单时:回车、空格展开菜单,焦点移到第一个子按钮,再按一次收起;在主按钮上按向上键展开并聚焦离主按钮最近的(最下面的)子按钮,向下键聚焦第一个。
- 菜单里:上下键在子按钮之间移动(首尾循环),Home、End 到第一个、最后一个;子按钮不单独占 Tab 位置,Tab 离开时菜单收起。
- Esc 收起菜单,焦点回到主按钮。放在对话框、抽屉里时,这次 Esc 只收起菜单,对话框不跟着关。
Props
FloatButton
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| icon | string | - | 图标名(见《图标》),和默认插槽二选一 |
| tooltip | string | - | 悬停或聚焦时的文字提示;只有图标时也是按钮的 aria-label |
| tooltip-placement | TooltipPlacement | 'left' | 文字提示的位置 |
| description | string | - | 图标下面的小字,一般配合 shape="square" |
| type | 'default' | 'primary' | 'default' | 类型 |
| shape | 'circle' | 'square' | - | 形状,不写时是 circle。在组里跟随组(自己写的不生效);在菜单里不写时跟随主按钮 |
| position | 'fixed' | 'absolute' | 'relative' | 'fixed' | 定位方式。fixed 时 z-index 跟随 NsConfigProvider 的 zIndex(默认 2000)。在组里、菜单里不生效 |
| left | number | string | - | 距离左边,数字按 px。在组里、菜单里不生效 |
| right | number | string | - | 距离右边 |
| top | number | string | - | 距离上边 |
| bottom | number | string | - | 距离下边 |
| width | number | string | 40 | 宽度 |
| height | number | string | 40 | 高度(最小高度,内容放不下时变高) |
| badge | boolean | number | string | - | 右上角的角标:true 是小圆点,数字超过 99 显示 99+;false、0 不显示 |
| href | string | - | 链接地址,写了就渲染成 <a>;有菜单时不生效 |
| target | string | - | 链接的 target,_blank 时自动加 rel="noopener noreferrer" |
| menu-trigger | 'click' | 'hover' | 'click' | 展开菜单(menu 插槽)的触发方式 |
| show-menu | boolean | - | 菜单是否展开,配合 v-model:show-menu;不写时组件自己管理 |
class、style 写在根元素上(定位用);其他属性(id、aria-label、data-* 等)和没声明的事件监听放到真正的按钮上。
FloatButtonGroup
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| shape | 'circle' | 'square' | 'circle' | 组里按钮的形状;square 时按钮连成一整块 |
| position | 'fixed' | 'absolute' | 'relative' | 'fixed' | 定位方式。fixed 时 z-index 跟随 NsConfigProvider 的 zIndex(默认 2000) |
| left | number | string | - | 距离左边,数字按 px |
| right | number | string | - | 距离右边 |
| top | number | string | - | 距离上边 |
| bottom | number | string | - | 距离下边 |
Events
FloatButton
| 事件 | 回调参数 | 说明 |
|---|---|---|
| click | (event: MouseEvent) | 点击主按钮;菜单里的子按钮触发它们自己的 click |
| update:show-menu | (value: boolean) | 菜单展开或收起,配合 v-model:show-menu |
FloatButtonGroup 没有事件。
Slots
FloatButton
| 插槽 | 说明 |
|---|---|
| default | 图标位置的内容,写了就不显示 icon |
| description | 描述文字,优先于 description 属性 |
| menu | 展开的子按钮,放 NsFloatButton;有这个插槽主按钮才能展开 |
FloatButtonGroup
| 插槽 | 说明 |
|---|---|
| default | 组里的 NsFloatButton |
方法
FloatButton 通过 ref 暴露:
| 方法 | 参数 | 说明 |
|---|---|---|
| focus | - | 让主按钮获得焦点 |
| blur | - | 让主按钮失去焦点 |
FloatButtonGroup 没有对外暴露的方法。
类型
import type {
FloatButtonProps,
FloatButtonEmits,
FloatButtonGroupProps,
FloatButtonShape,
FloatButtonType,
FloatButtonPosition,
FloatButtonMenuTrigger,
FloatButtonLength
} from '@ns/ui'
type FloatButtonShape = 'circle' | 'square'
type FloatButtonType = 'default' | 'primary'
type FloatButtonPosition = 'fixed' | 'absolute' | 'relative'
type FloatButtonMenuTrigger = 'click' | 'hover'
/** 数字和纯数字的字符串按 px,其他字符串原样使用 */
type FloatButtonLength = number | string
interface FloatButtonProps {
left?: FloatButtonLength
right?: FloatButtonLength
top?: FloatButtonLength
bottom?: FloatButtonLength
width?: FloatButtonLength
height?: FloatButtonLength
position?: FloatButtonPosition
shape?: FloatButtonShape
type?: FloatButtonType
icon?: NsIconName
description?: string
tooltip?: string
tooltipPlacement?: TooltipPlacement
href?: string
target?: string
badge?: boolean | number | string
menuTrigger?: FloatButtonMenuTrigger
showMenu?: boolean
}
interface FloatButtonEmits {
click: [event: MouseEvent]
'update:showMenu': [value: boolean]
}
interface FloatButtonGroupProps {
left?: FloatButtonLength
right?: FloatButtonLength
top?: FloatButtonLength
bottom?: FloatButtonLength
position?: FloatButtonPosition
shape?: FloatButtonShape
}
注意事项
- 外观和
NsBacktop一致:40×40、1px 边框、--ns-shadow阴影,图标 20px。悬停时阴影加深,default类型叠一层浅底色、图标变主色,primary类型底色变浅。颜色、阴影都用主题变量,暗色主题自动切换。 - 层级:
position="fixed"时 z-index 写在内联样式上,跟随NsConfigProvider的zIndex(默认 2000),和下拉面板、对话框是同一套;对话框、抽屉和下拉面板挂在body末尾,会盖住悬浮按钮。要单独调整时在按钮或组上写style="z-index: …",使用者写的优先。absolute、relative时不写 z-index。 - 没有
right、bottom等时不会自动放到右下角,按钮停在它在页面里本来的位置,记得写定位。 - 菜单在主按钮上方展开。组里带菜单的按钮放在最上面,否则展开的菜单会盖住它上面的按钮。
- 方形组里的按钮宽度要一样,否则连不成整块。
- 菜单里的子按钮不要再放菜单。
- 有菜单时
href不生效(主按钮要负责展开菜单),开发环境下会在控制台警告。 NsBacktop不能直接放进NsFloatButtonGroup,组里的回到顶部用NsFloatButton组合,见上面的“和回到顶部一起用”。