Semi Design FloatButton 悬浮按钮组件完全指南：从基础用法到源码级解析

Semi Design FloatButton 悬浮按钮组件完全指南从基础用法到源码级解析【免费下载链接】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 DesignReact UI 组件库位于本仓库packages/semi-ui的 FloatButton 悬浮按钮组件为核心系统讲解其引入方式、尺寸形状、点击跳转、多彩AI 风格、徽章与悬浮按钮组等全部能力并结合 组件实现源码 与 Foundation 样式层 深入剖析其底层原理与设计 Token 体系。读完本文你将能够独立、正确地在业务页面中落地单按钮与按钮组两种悬浮交互形态并理解其尺寸、圆角、定位、徽章偏移量等细节的来龙去脉。说明本文内容以 content/basic/floatbutton/index.md 为骨架辅以仓库源码与样式变量文件进行纵深补充。如何引入FloatButton 自2.85.0版本开始支持。与 Semi Design 其他组件一致直接从douyinfe/semi-ui包中按需引入即可import { FloatButton } from douyinfe/semi-ui;如果需要使用悬浮按钮组则额外引入FloatButtonGroupimport { FloatButton, FloatButtonGroup } from douyinfe/semi-ui;两个组件均由semi-ui包统一导出底层实现位于 packages/semi-ui/floatButton/index.tsxFloatButton与 packages/semi-ui/floatButton/floatButtonGroup.tsxFloatButtonGroup对应的样式与常量定义在douyinfe/semi-foundation/floatButton目录下。基本用法FloatButton 是悬浮在页面上的可操作按钮默认通过position: fixed固定在页面右下角。最简用法是传入一个图标与点击回调import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { const onClick () { console.log(float button clicked); }; return ( span基本使用页面右下第三列 1 /span FloatButton icon{IconAIEditLevel1 /} style{{ bottom: 270px }} onClick{onClick}/ / ); };要点说明icon接收任意ReactNode既可以是 semi-icons 中的图标如IconAIEditLevel1也可以是自定义的图片或 SVG 元素组件的固定定位、默认间距等由样式层提供见下文「样式与设计 Token」而style中的bottom、right/insetInlineEnd等属性可直接覆盖定位值用于在页面右下角纵向排布多个按钮。尺寸FloatButton 支持三种尺寸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 ( span大尺寸页面右下第三列 2/span FloatButton sizelarge icon{IconAIEditLevel1 /} style{{ bottom: 200px }} onClick{onClick}/ /); };从源码视角看三种尺寸被收敛在 constants.ts 的strings.SIZE中其取值为[small, default, large]组件defaultProps中size默认为default。对应的实际宽高定义在 variables.scsssize宽高width / heightsmall24pxdefault32pxlarge40px形状FloatButton 默认定义了两种形状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 ( span方形页面右下第三列 3/span FloatButton shapesquare icon{IconAIEditLevel1 /} style{{ bottom: 150px }} onClick{onClick}/ /); };关于默认值的补充说明组件源码 index.tsx 中defaultProps明确将shape默认值设为roundAPI 表格中的默认值一栏同样标注为round而文档演示文字中方形默认的表述属于演示文案笔误实际使用时请以源码默认值round为准。形状的视觉效果由 floatButton.scss 控制roundborder-radius使用var(--semi-border-radius-full)即全圆角视觉上为圆形squareborder-radius固定为8px变量$radius-floatButton_square。值得注意的一个细节是徽章在两种形状下的偏移量算法由于方形按钮的徽章会落在右上角圆角边缘样式层专门为其计算了偏移——注释中给出了推导逻辑「按钮中心与包围矩形右上角的连线与按钮边框的交点通过半径计算得 (√2 − 1) / √2 × R ≈ 0.29 × R」因此方形按钮的徽章top与inset-inline-end均取calc(0.29 * $radius-floatButton_square)而圆形按钮则进一步乘以0.5 * width换算成像素偏移保证徽章始终贴合按钮边缘。点击跳转可通过href设置跳转地址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 ( span点击跳转页面右下第三列 4/span FloatButton icon{IconAIEditLevel1 /} style{{ bottom: 100px }} href{https://semi.design} target{_blank} / /); };当设置了href时组件会优先执行跳转逻辑跳转方式取决于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状态下点击直接短路返回既不跳转也不触发onClick若同时传入href与onClick两者都会执行先执行跳转再执行回调注意_blank分支使用window.open其余情况改写window.location.hrefhref与target的语义与原生a标签一致target_blank即在新窗口 / 新标签页打开链接。AI 风格多彩悬浮按钮可设置colorful为true展示多彩的悬浮按钮。这是 Semi Design 面向 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 ( span多彩按钮页面右下第一列/span FloatButton colorful icon{IconAIEditLevel1 /} style{{ bottom: 110px, insetInlineEnd: 150px }} href{https://semi.design} target{_blank} / /); };从样式变量 variables.scss 可以看到colorful模式实际复用了 Semi Design 的 AI 语义色 Token背景色var(--semi-color-ai-general)文字颜色var(--semi-color-white)悬浮态背景var(--semi-color-ai-general-hover)按下态背景var(--semi-color-ai-general-active)。也就是说colorful与默认模式的本质区别在于配色方案切换图标、点击、跳转等行为完全一致。colorful的默认值为false。带徽章的悬浮按钮badge属性接收完整的 Badge 配置对象类型为BadgeProps完整参数可参见 Badge 组件文档可以组合出点状徽章、数字徽章、文案徽章等多种形态import React from react; import { FloatButton } from douyinfe/semi-ui; import { IconAIEditLevel1 } from douyinfe/semi-icons; () { return ( span带徽章页面右下第二列/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 配置效果说明禁用态 红点{ dot: true, type: danger }仅显示危险色小圆点且按钮整体禁用数字超限{ count: 1000, overflowCount: 999 }超过overflowCount显示为999多彩 红点{ dot: true }圆点徽章叠加多彩底色文字徽章{ count: VIP, type: danger }count支持字符串展示自定义文案实现上组件在渲染时判断badge是否存在存在则用Badge {...badge}{body}/Badge包裹按钮主体见 index.tsx因此徽章的位置由 Badge 组件与上述样式层偏移量共同决定。悬浮按钮组当页面需要一组并列的悬浮操作项时可使用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 ( spanThe last row at the bottom right of the page/span FloatButtonGroup style{{ insetInlineEnd: 24, bottom: 50, }} onClick{(value, e) { console.log(点击了 , value); }} items{[ { icon: IconAIStrokedLevel3 /, content: 编辑, value: editor, }, { icon: IconSearchStroked /, content: 搜索, value: search, }, { icon: IconHelpCircleStroked /, content: 帮助, value: help } ]} / /); };按钮组的关键行为与底层实现见 floatButtonGroup.tsx点击回调携带 value组件的onClick签名为(value: string, e: React.MouseEvent) void。实现上通过事件委托在组容器上统一监听点击再从e.target.dataset.value读取被点击子项的value并回传floatButtonGroup.tsx因此业务层无需为每个 item 单独注册回调每个 item 都支持 badge若子项配置了badge该子项会被Badge包裹渲染组的样式FloatButtonGroup整体以inline-flex横向排列容器带8px圆角、--semi-shadow-elevated阴影、6px内边距与4px的子项间距见 floatButton.scss子项 hover / active 时背景色分别切换为--semi-color-fill-1/--semi-color-fill-2disabled组级disabled会在容器上添加禁用类子项不支持单独禁用禁用粒度以组为单位。API 参考以下为官方 API 文档完整参数表与 content/basic/floatbutton/index.md 一致并附源码级补充说明。FloatButton属性说明类型默认值badge徽章参数BadgeProps-colorful多彩悬浮按钮booleanfalseclassName样式类名string-disabled禁用状态booleanfalsehref点击跳转的链接string-icon显示图标ReactNode-onClick点击回调函数(e: React.MouseEvent)-shape样式支持 round、squarestringroundsize尺寸支持 default、small、largestringdefaultstyle样式CSSProperties-target指定在何处显示链接的 URLstring-补充说明shape与size的合法取值由 constants.ts 中strings.SHAPE [square, round]与strings.SIZE [small, default, large]约束并通过 interface.ts 的ArrayElementtypeof strings.SHAPE类型收窄为字面量联合类型传入非法值会在编译期报错href与target的跳转语义已在「点击跳转」一节详述target _blank走window.open否则改写window.location.hrefonClick与href可同时使用点击时先跳转后回调disabled为true时两者均不触发。FloatButtonGroupItem在 FloatButtonProps 基础上增加以下参数属性说明类型默认值content文本内容String / ReactNode-valueitem 的标识String-注意content在类型定义floatButtonGroup.tsx中为string | React.ReactNode即除了纯文本外同样可以传入自定义节点value则是点击回调回传的标识字段。FloatButtonGroup属性说明类型默认值className样式类名string-disabled禁用状态booleanfalseitems单个子项的信息FloatButtonGroupItem-onClick点击回调函数(value: string, e: React.MouseEvent)-style样式CSSProperties-样式与设计 Token从源码看定位与主题化FloatButton 与 FloatButtonGroup 的固定定位、间距与层级均定义在 Foundation 样式层全部收敛为可在主题中覆盖的设计 Tokenvariables.scssTokenSCSS 变量默认值作用$spacing-floatButton-bottom/-right24px / 24px单按钮距底部 / 右侧距离$width-floatButton_small/-default/-large24px / 32px / 40px三种尺寸的宽高$z-floatButton/$z-floatButton_group1000 / 1000悬浮层级z-index$radius-floatButton_square/-round8px /var(--semi-border-radius-full)方形与圆形圆角$radius-floatButton_group-border-radius/-item-border-radius8px / 4px按钮组容器与子项圆角$shadow-floatButton/-groupvar(--semi-shadow-elevated)按钮与按钮组阴影$spacing-floatButton_group-padding/-columnGap6px / 4px按钮组内边距与子项水平间距$spacing-floatButton_group_item-paddingX/-paddingY12px / 6px子项内边距配色方面全部使用 Semi Design 语义色变量默认态为--semi-color-fill-0背景与--semi-color-primary图标色hover / active 切换至--semi-color-fill-1/--semi-color-fill-2多彩态复用--semi-color-ai-general系列 AI 语义色。这意味着 FloatButton 与整个设计系统共享同一套主题体系通过 自定义主题 或 Design Token 即可全局调整悬浮按钮的外观无需改动业务代码。此外样式文件中使用了inset-inline-end等逻辑属性并引入 rtl.scss因此在 RTL从右到左语言环境下按钮与徽章的定位会自动镜像符合 国际化 的布局规范。小结FloatButton 组件虽然 API 精简却覆盖了「单按钮 按钮组」两种悬浮交互形态size、shape控制形态href/target与onClick控制跳转和回调colorful一键切换 AI 风格配色badge直接复用 Badge 组件能力FloatButtonGroup则通过items 事件委托实现了批量操作项的统一管理。其定位、间距、圆角、阴影、色彩全部沉淀为 Foundation 层的设计 Token天然融入 Semi Design 的主题定制体系——无论是快速接入业务页面还是深入定制视觉风格都可以在本文基础上直接展开实践。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考