悬浮按钮 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { FloatButton, FloatButtonGroup } from '@fibrous/semi-ui-vue';
</script>

基本用法

基本使用：页面右下第三列 1

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';

    const onClick = () => {
        console.log('float button clicked');
    };
</script>

<template>
    <span>基本使用：页面右下第三列 1 </span>
    <FloatButton aria-label="AI 编辑" style="bottom: 270px" @click="onClick">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

尺寸

支持三种尺寸：默认，小，大。

大尺寸：页面右下第三列 2

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';

    const onClick = () => {
        console.log('float button clicked');
    };
</script>

<template>
    <span>大尺寸：页面右下第三列 2</span>
    <FloatButton aria-label="AI 编辑" size="large" style="bottom: 200px" @click="onClick">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

形状

默认定义了两种形状：round（默认）、square。

方形：页面右下第三列 3

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';

    const onClick = () => {
        console.log('float button clicked');
    };
</script>

<template>
    <span>方形：页面右下第三列 3</span>
    <FloatButton aria-label="AI 编辑" shape="square" style="bottom: 150px" @click="onClick">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

点击跳转

设置 href 后渲染为原生链接 <a>，target 指定目标网页在哪个窗口或框架中打开，rel 指定与目标网页的关系。中键在新标签页打开、右键复制链接地址等均为浏览器原生行为。未设置 href 时渲染为原生 <button type="button">。

点击跳转：页面右下第三列 4

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';
</script>

<template>
    <span>点击跳转：页面右下第三列 4</span>
    <FloatButton aria-label="访问 Semi 官网" href="https://semi.design" rel="noopener noreferrer" style="bottom: 100px" target="_blank">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

AI 风格 - 多彩悬浮按钮

可设置 colorful 为 true，展示多彩的悬浮按钮。

多彩按钮：页面右下第一列

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';
</script>

<template>
    <span>多彩按钮：页面右下第一列</span>
    <FloatButton aria-label="访问 Semi 官网" colorful href="https://semi.design" rel="noopener noreferrer" style="bottom: 110px; inset-inline-end: 150px" target="_blank">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

带徽章的

带徽章：页面右下第二列

代码

<script setup lang="ts">
    import { IconAIEditLevel1 } from '@fibrous/semi-icons-vue';
    import { FloatButton } from '@fibrous/semi-ui-vue';
</script>

<template>
    <span>带徽章：页面右下第二列</span>
    <FloatButton aria-label="AI 编辑" :badge="{ dot: true, type: 'danger' }" disabled style="bottom: 270px; inset-inline-end: 100px">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
    <FloatButton aria-label="AI 编辑，999+" :badge="{ count: 1000, overflowCount: 999 }" size="large" style="bottom: 210px; inset-inline-end: 100px">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
    <FloatButton aria-label="AI 编辑" :badge="{ dot: true }" colorful style="bottom: 170px; inset-inline-end: 100px">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
    <FloatButton aria-label="AI 编辑，VIP" :badge="{ count: 'VIP', type: 'danger' }" colorful size="large" style="bottom: 110px; inset-inline-end: 100px">
        <template #icon>
            <IconAIEditLevel1 />
        </template>
    </FloatButton>
</template>

悬浮按钮组

可通过 items 传入子项，图标用 #icon="{ item, index }" 插槽提供。每个子项与单个 FloatButton 一样渲染为原生按钮或链接，各自的 href、target、rel、disabled、onClick 均生效；点击子项时先调用子项的 onClick(event)，再触发 FloatButtonGroup 的 click(value, event)。FloatButtonGroup 的 disabled 会禁用全部子项。

页面右下方最后一行

帮助

代码

<script setup lang="ts">
    import { IconAIStrokedLevel3, IconHelpCircleStroked, IconSearchStroked } from '@fibrous/semi-icons-vue';
    import { FloatButtonGroup } from '@fibrous/semi-ui-vue';

    const icons = [IconAIStrokedLevel3, IconSearchStroked, IconHelpCircleStroked];

    const items = [
        { content: '编辑', value: 'editor' },
        { content: '搜索', value: 'search', disabled: true },
        { content: '帮助', value: 'help', href: 'https://semi.design', target: '_blank' },
    ];

    const onClick = (value?: string) => {
        console.log('点击了 ', value);
    };
</script>

<template>
    <span>页面右下方最后一行</span>
    <FloatButtonGroup :items="items" style="inset-inline-end: 24px; bottom: 50px" @click="onClick">
        <template #icon="{ index }">
            <component :is="icons[index]" />
        </template>
    </FloatButtonGroup>
</template>

API参考

FloatButton

Props

属性	说明	类型	默认值
badge	徽章参数，同 Badge 的 props；class、style 以及 onClick、onMouseenter、onMouseleave 落在 Badge 根元素上。	`FloatButtonBadge`	`semiGlobalDefault("FloatButton", "badge")`
colorful	多彩悬浮按钮。	`boolean`	`semiDefault("FloatButton", "colorful", false)`
disabled	禁用状态。	`boolean`	`semiDefault("FloatButton", "disabled", false)`
href	链接地址，设置后渲染为 a；禁用时去掉 href。	`string`	`semiGlobalDefault("FloatButton", "href")`
rel	与链接目标的关系，仅在设置 href 时生效。	`string`	`semiGlobalDefault("FloatButton", "rel")`
shape	形状，可选 round、square。	`"square" \| "round"`	`semiDefault("FloatButton", "shape", "round")`
size	尺寸，可选 default、small、large。	`"small" \| "default" \| "large"`	`semiDefault("FloatButton", "size", "default")`
target	指定在何处显示链接的 URL，仅在设置 href 时生效。	`string`	`semiGlobalDefault("FloatButton", "target")`

Events

事件	说明	回调参数
click	点击时触发，载荷为原生 click 事件；禁用时不触发。	`[event: MouseEvent]`

Slots

插槽	说明	作用域参数
badgeCount	自定义徽章内容，代替 badge.count。	`any`
icon	按钮图标。	`any`

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 传入，落在根元素上：设置 href 时为 <a>，否则为 <button>。click 声明为事件，会遮住根元素的原生 click 监听，禁用时不触发。按钮分支的 type="button" 与 aria-disabled 不可被 attrs 覆盖，链接分支丢弃传入的 type。:style 中的数字不会自动补 px，需写成字符串。

FloatButtonGroupItem

在 FloatButton 的 props 基础上增加以下参数。子项的 href、target、rel、disabled、class、style 与 FloatButton 含义相同，onClick 等监听器写在数据里；shape、size、colorful 与单个 FloatButton 的同名属性效果相同，设置 size 时子项为该尺寸的固定宽高。不支持子项的 ref。

属性	说明	类型	默认值
aria-label	子项的可访问名称，只有图标没有文本时必须传	string	-
class	类名	string \| object \| array	-
content	文本内容，更丰富的内容用 `#content` 插槽	string \| number	-
data-*	自定义数据属性	string	-
id	元素 id	string	-
onClick	点击回调，先于 FloatButtonGroup 的 `click` 调用	(event: MouseEvent) => void	-
onContextmenu	右键菜单回调	(event: MouseEvent) => void	-
onMouseenter	指针进入回调	(event: MouseEvent) => void	-
onMouseleave	指针离开回调	(event: MouseEvent) => void	-
style	样式	string \| object \| array	-
title	原生 title 属性	string	-
value	item 的标识，作为 `click` 事件的第一个载荷	string	-

FloatButtonGroup

Props

属性	说明	类型	默认值
disabled	禁用全部子项。	`boolean`	`semiDefault("FloatButtonGroup", "disabled", false)`
items	子项列表。	`FloatButtonGroupItem[]`	`undefined`

Events

事件	说明	回调参数
click	点击未禁用子项时触发，载荷为子项的 value（未设置时为 undefined）与原生 click 事件；子项自己的 onClick 先于它调用。	`[value: string \| undefined, event: MouseEvent]`

Slots

插槽	说明	作用域参数
badgeCount	自定义子项徽章内容，接收 item 与 index。	`FloatButtonGroupItemSlotProps`
content	自定义子项文本内容，接收 item 与 index；缺省渲染 item.content。	`FloatButtonGroupItemSlotProps`
icon	子项图标，接收 item 与 index。	`FloatButtonGroupItemSlotProps`

Exposes

名称	说明	类型
无

class、style 与原生属性（如 aria-*）经 attrs 落在根元素（role="group"）上。items 中的 icon、节点型 content 与节点型 badge.count 分别用 #icon、#content、#badgeCount 作用域插槽提供，参数为 { item, index }。

Accessibility

ARIA

FloatButton 与 FloatButtonGroup 的每个子项都是原生元素：设置 href 时为链接 <a>，否则为按钮 <button type="button">，读屏软件会读出对应的角色
可访问名称取自 aria-label，没有时取可见文本（子项的 content）。FloatButton 通常只有图标，请务必传入 aria-label 描述按钮的作用，例如 aria-label="回到顶部"；只有图标的子项同样需要在子项上传入 aria-label
徽标（badge.count）显示的文字也是按钮可见文本的一部分，aria-label 会覆盖它，因此请把徽标文字写进 aria-label，例如 aria-label="AI 编辑，VIP"，让语音输入用户能用看到的文字操作按钮
禁用的按钮使用原生 disabled 并带 aria-disabled="true"。链接没有原生禁用状态，禁用的链接会去掉 href（无法点击、中键或右键打开，也不在 Tab 顺序中），同时设置 role="link" 与 aria-disabled="true"，读屏软件仍将其读作不可用的链接
FloatButtonGroup 的根元素是 role="group"，可通过 aria-label 或 aria-labelledby 给整组命名（aria-* 透传到根元素）
FloatButtonGroup 没有选中态，子项不使用 aria-pressed

键盘和焦点

焦点管理与原生按钮、链接一致：可以使用 Tab 及 Shift + Tab 切换焦点，禁用的项不可聚焦
按钮聚焦时可以通过 Enter 或 Space 键激活，链接聚焦时可以通过 Enter 键打开
键盘聚焦时显示聚焦轮廓