Semi Design FloatButton 悬浮按钮完整指南：API 配置、尺寸形状与悬浮按钮组实战

前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载Semi Design 的 FloatButton悬浮按钮自 2.85.0 版本起提供是一种可悬浮在页面上方的可操作按钮适合承载快捷操作、回到顶部、AI 助手入口等高频动作。本文将以 content/basic/floatbutton/index-en-US.md 为核心骨架结合 packages/semi-ui/floatButton 与 packages/semi-foundation/floatButton 的源码实现系统讲解 FloatButton 的引入方式、尺寸/形状/跳转/多彩风格/徽章/按钮组等全部用法并深入剖析其底层原理帮助你在实际项目中快速落地。如何引入FloatButton 是douyinfe/semi-ui的一部分自2.85.0版本开始支持。直接使用 ES Module 按需引入即可import { FloatButton } from douyinfe/semi-ui;如果还需要使用按钮组可一并引入FloatButtonGroupimport { FloatButton, FloatButtonGroup } from douyinfe/semi-ui;图标通常搭配douyinfe/semi-icons使用例如本文示例中反复出现的IconAIEditLevel1import { IconAIEditLevel1 } from douyinfe/semi-icons;基本用法FloatButton 是一个可以固定悬浮在页面上的可操作按钮。默认定位为页面右下角你可以通过style中的bottom、insetInlineEnd或right等属性微调其位置。最简单的用法如下——渲染一个带图标的悬浮按钮并监听点击事件import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( spanBasic usage: Row one, third column at the bottom right of the page /span FloatButton icon{IconAIEditLevel1 /} style{{ bottom: 270px }} onClick{onClick}/ / ); };从源码实现来看FloatButton 实际渲染的是一个包裹着-body子元素的div见 packages/semi-ui/floatButton/index.tsxicon被放进-body内部居中展示外层div承担定位与点击事件。基础样式层面见 packages/semi-foundation/floatButton/floatButton.scss使用了position: fixed、bottom与right来锚定在页面右下角z-index: 1000保证悬浮层级。尺寸SizeFloatButton 支持三种尺寸默认default、小small、大large。通过size属性切换import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( spanLarge size: Row two, third column at the bottom right of the page /span FloatButton sizelarge icon{IconAIEditLevel1 /} style{{ bottom: 200px }} onClick{onClick}/ /); };三种尺寸的可用枚举值在 packages/semi-foundation/floatButton/constants.ts 中统一定义const strings { SHAPE: [square, round], SIZE: [small, default, large], } as const;对应的实际像素尺寸定义在 packages/semi-foundation/floatButton/variables.scss尺寸宽度/高度说明small24px紧凑场景如密集工具栏default默认值32px通用场景large40px需要更突出视觉权重时SCSS 中通过-small、-default、-large三个类名分别控制宽高同时组件内部也会把size拼入 className见 index.tsx实现样式与逻辑的解耦。形状ShapeFloatButton 默认提供两种形状round圆形默认与square方形。通过shape属性切换import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( spanSquare: Row three, third column at the bottom right of the page /span FloatButton shapesquare icon{IconAIEditLevel1 /} style{{ bottom: 150px }} onClick{onClick}/ /); };两种形状的圆角样式在 floatButton.scss 中定义-square { border-radius: $radius-floatButton_square; // 8px } -round { border-radius: $radius-floatButton_round; // var(--semi-border-radius-full)即全圆角 }其中方形的圆角为固定8px圆形的圆角使用主题令牌--semi-border-radius-full因此圆形外观会随主题设计令牌自动适配这也是 Semi Design 强调 Design Tokens 可定制性的体现。需要注意的是文档表格中shape的默认值标注为round与源码中 defaultProps 的shape: round完全一致。点击跳转href / target你可以通过href设置点击跳转地址并通过target指定目标网页在哪个窗口或框架中打开语义同原生a标签的target属性import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( spanClick to jump: Row four, third column at the bottom right of the page/span FloatButton icon{IconAIEditLevel1 /} style{{ bottom: 100px }} href{https://semi.design} target{_blank} / /); };底层跳转逻辑在 index.tsx 的handleClick中实现值得注意的细节如下handleClick (e: React.MouseEvent) { const { href, target, onClick, disabled } this.props; if (disabled) { return; } // 如果有 href执行跳转 if (href) { if (target _blank) { window.open(href, _blank); } else { window.location.href href; } } // 如果有 onClick 回调执行它 if (onClick) { onClick(e); } };从源码可以看出三点行为约定禁用优先disabled为true时直接returnhref与onClick均不会触发双通道共存设置href后点击会先执行跳转随后onClick回调仍会照常执行跳转方式分支target _blank时用window.open新开窗口否则用window.location.href在当前页跳转。AI 风格多彩悬浮按钮colorfulSemi Design 内置了面向 AI 场景的视觉风格。设置colorful为true即可展示多彩渐变 AI 风格的悬浮按钮import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( spanColorful buttons: The first column at the bottom right of the page/span FloatButton colorful icon{IconAIEditLevel1 /} style{{ bottom: 110px, insetInlineEnd: 150px }} href{https://semi.design} target{_blank} / /); };从样式源码floatButton.scss可以看到colorful模式的配色完全由 AI 主题令牌驱动-colorful { background: $color-floatButton-colorful-bg; // var(--semi-color-ai-general) color: $color-floatButton-colorful-text; // var(--semi-color-white) :hover { background: $color-floatButton-colorful-bg-hover; // var(--semi-color-ai-general-hover) } :active { background: $color-floatButton-colorful-bg-active; // var(--semi-color-ai-general-active) } }对应令牌定义在 variables.scss默认背景为--semi-color-ai-general文字为白色hover/active 状态分别使用--semi-color-ai-general-hover与--semi-color-ai-general-active。这意味着多彩悬浮按钮的颜色可以随主题切换统一变化非常适合作为页面中的AI 助手入口类按钮。带徽章BadgeFloatButton 支持直接透传 Badge 参数badge属性接受 Badge 组件的全部 props。你可以组合出红点提示、数字角标、多彩 徽章等多种形态import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { return ( spanWith badge: second column from the bottom right of the page/span FloatButton disabled icon{IconAIEditLevel1 /} badge{{ dot: true, type: danger }} style{{ bottom: 270, insetInlineEnd: 100px }} / FloatButton badge{{ count: 1000, overflowCount: 999 }} size{large} icon{IconAIEditLevel1 /} style{{ bottom: 210, insetInlineEnd: 100 }} / FloatButton icon{IconAIEditLevel1 /} badge{{ dot: true }} colorful style{{ bottom: 170, insetInlineEnd: 100 }} / FloatButton icon{IconAIEditLevel1 /} colorful sizelarge badge{{ count: VIP, type: danger }} style{{ bottom: 110, insetInlineEnd: 100 }} / /); };badge支持的关键子属性来自 packages/semi-ui/badge/index.tsx 的BadgeProps定义如下属性说明类型count徽章显示的数字/内容ReactNodedot是否只显示小圆点booleantype徽章类型primary | secondary | tertiary | danger | warning | successtheme徽章主题solid | light | invertedposition徽章位置leftTop | leftBottom | rightTop | rightBottomoverflowCount数字溢出上限超过后显示number示例中count: 1000, overflowCount: 999会在数量超过 999 时显示为999count也可以传字符串如VIP作为文字徽章。组件内部对 badge 的处理非常简洁见 index.tsx{badge ? Badge {...badge}{body}/Badge : body}即有badge时用Badge包裹按钮主体没有时直接渲染主体。而徽章的定位偏移在 floatButton.scss 中针对不同尺寸、形状做了精确计算——通过几何关系(√2 - 1)/√2 × R ≈ 0.29 × RR 为按钮半径保证徽章中心始终落在按钮中心与右上角的连线上视觉上处于右上角的标准位置。悬浮按钮组FloatButtonGroup当需要在一处放置多个相关操作时可以使用FloatButtonGroup通过items传入子项。每个子项支持icon、content文本内容与value子项标识等字段import React from react; import { FloatButtonGroup } from douyinfe/semi-ui; import { IconAIEditLevel1, IconAIStrokedLevel3, IconSearchStroked, IconHelpCircleStroked } from douyinfe/semi-icons; () { return ( span页面右下方最后一行/span FloatButtonGroup style{{ insetInlineEnd: 24, bottom: 50, }} onClick{(value, e) { console.log(Clicked , value); }} items{[ { icon: IconAIStrokedLevel3 /, content: Edit, value: editor, }, { icon: IconSearchStroked /, content: Search, value: search, }, { icon: IconHelpCircleStroked /, content: Help, value: help } ]} / /); };按钮组的点击回调签名是(value: string, e: React.MouseEvent)——第一个参数是被点击子项的value。这一机制在 floatButtonGroup.tsx 中通过data-value属性实现handleClick (e) { const value e.target.dataset.value; this.props.onClick?.(value, e); }每个子项渲染时都会携带data-value{item.value}见 floatButtonGroup.tsx点击时从事件目标上读取该值并回传给onClick从而让开发者无需自行记录索引即可区分点击了哪个子项。另外若某个子项配置了badge组件也会自动用Badge包裹该子项。按钮组的视觉形态是一个横向排布的卡片式容器样式源码floatButton.scss显示其使用display: inline-flex横向排列容器有8px圆角、--semi-shadow-elevated阴影与6px内边距子项之间以4px间隔子项内部图标与文本间隔8pxhover/active 分别使用--semi-color-fill-1与--semi-color-fill-2背景。整体同样固定在页面右下角bottom: 24px; right: 24px与单个悬浮按钮的默认定位保持一致。API 参考FloatButton属性说明类型默认值badge徽章参数BadgeProps-colorful多彩悬浮按钮AI 风格booleanfalseclassName样式类名string-disabled禁用状态booleanfalsehref点击跳转的链接同 hrefstring-icon显示图标ReactNode-onClick点击回调函数(e: React.MouseEvent) void-shape样式支持 round、squarestringroundsize尺寸支持 default、small、largestringdefaultstyle样式CSSProperties-target指定在何处显示链接的 URL同 targetstring-说明上述默认值可在 index.tsx 的defaultProps与 interface.ts 的FloatButtonProps类型定义中得到印证。href/target的跳转行为与原生a语义一致具体实现见handleClick。FloatButtonGroupItem在FloatButtonProps基础上增加以下参数属性说明类型默认值content文本内容string | ReactNode-valueitem 的标识string-该接口定义于 floatButtonGroup.tsxvalue会作为onClick回调的第一个参数返回。FloatButtonGroup属性说明类型默认值className样式类名string-disabled禁用状态booleanfalseitems单个子项的信息FloatButtonGroupItem[]-onClick点击回调函数(value: string, e: React.MouseEvent) void-style样式CSSProperties-源码结构速览如果你希望深入阅读实现以下是 FloatButton 相关的核心文件路径组件实现packages/semi-ui/floatButton/index.tsx、packages/semi-ui/floatButton/floatButtonGroup.tsx类型定义packages/semi-ui/floatButton/interface.ts常量形状/尺寸枚举、CSS 类名前缀packages/semi-foundation/floatButton/constants.ts样式与设计令牌packages/semi-foundation/floatButton/floatButton.scss、packages/semi-foundation/floatButton/variables.scssRTL 适配样式packages/semi-foundation/floatButton/rtl.scss其中 RTL 样式用于在从右向左阿拉伯语等排版环境下自动镜像徽章偏移方向尺寸/形状的 className 由组件根据 props 动态拼接SCSS 与逻辑层通过类名约定如semi-floatButton-large、semi-floatButton-square实现松耦合便于主题定制时仅靠覆盖 SCSS 变量即可调整外观。小结FloatButton 是 Semi Design 中一个小而精的浮层操作组件覆盖了图标按钮、尺寸/形状切换、链接跳转、AI 多彩风格、徽章角标与组合式按钮组等完整场景。其实现采用UI 层 Foundation 层的经典分层逻辑点击分发、跳转、disabled 拦截集中在 packages/semi-ui/floatButton 的 React 组件中样式与几何定位徽章偏移、圆角、间距、z-index则全部沉淀在 packages/semi-foundation/floatButton 的 SCSS 与设计令牌中既保证开箱即用的体验又保留了通过主题令牌尤其是 AI 相关的--semi-color-ai-*系列进行深度定制的空间。对于需要快速挂载AI 入口快捷操作通知角标等能力的业务页面FloatButton 与 FloatButtonGroup 是即插即用的理想选择。赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐ant-design-vue FloatButton 悬浮按钮组件完全指南API、源码解析与实战场景ant design vue FloatButton 悬浮按钮组件完全指南API、源码解析与实战场景 FloatButton 是 ant design vue前端UI组件设计系统Ant Design FloatButton 完全指南悬浮按钮、分组菜单与 BackTop 的 API 详解与源码实现Ant Design FloatButton 完全指南悬浮按钮、分组菜单与 BackTop 的 API 详解与源码实现 FloatButton悬浮按钮 是前端UI组件设计系统如何快速实现React Native Navigation悬浮按钮FAB按钮的完整指南如何快速实现React Native Navigation悬浮按钮FAB按钮的完整指南 React Native Navigation是一个功能强大的原生导航移动开发上一篇B站视频下载完整指南8K、杜比视界与收藏夹批量解析下一篇ExplorerPatcher3分钟把Windows 11改回Windows 10桌面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考