Button

按钮（Button）用于触发即时操作，是用户界面中最常用的交互元素之一。

import { Button, ButtonIcon, ButtonGroup } from '@skyroc/web-ui';

何时使用

当需要一个即时操作的触发器时，使用按钮。
主按钮在同一操作区域建议最多出现一次，突出最重要的行动。
多个按钮组合时，推荐 1 个主操作 + N 个次级操作，超过 3 个可使用 Dropdown 收纳。

颜色

按钮提供 8 种主题颜色，每种颜色都有其语义含义：

颜色	语义	适用场景
`primary`	主操作	页面中最重要的行为
`destructive`	危险操作	删除、移除等不可逆操作
`success`	成功确认	操作成功、确认完成
`warning`	警告提示	需要注意的操作
`info`	信息提示	信息性操作
`carbon`	中性深色	不带语义倾向的中性操作
`secondary`	次级操作	辅助性、低优先级操作
`accent`	强调色	需要特殊视觉关注的操作

无法读取 Demo 源码：@playground/button/modules/ButtonColor

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonColor.tsx'

变体

通过 variant 控制按钮的视觉强度，从高到低依次为：

变体	视觉强度	适用场景
`solid`	最强	主要操作，填充背景色（默认）
`pure`	较强	中性卡片风格，hover 时高亮
`plain`	中等	朴素边框风格，hover 时着色
`outline`	中等	次要操作，实线边框
`dashed`	中低	可选操作，虚线边框
`soft`	低	轻量操作，淡色背景
`ghost`	极低	无背景，仅文字和 hover 效果
`link`	最低	行内链接风格，带下划线

无法读取 Demo 源码：@playground/button/modules/ButtonVariant

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonVariant.tsx'

尺寸

通过 size 调整按钮大小，从 xs 到 2xl 共 6 个尺寸。

尺寸	高度	字号	适用场景
`xs`	24px	10px	紧凑布局、表格内操作
`sm`	28px	12px	辅助操作、工具栏
`md`	32px	14px	常规场景（默认）
`lg`	36px	16px	强调操作、表单提交
`xl`	40px	18px	重要入口、CTA
`2xl`	48px	20px	首屏 Hero、大幅 CTA

无法读取 Demo 源码：@playground/button/modules/ButtonSize

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonSize.tsx'

形状

通过 shape 控制按钮的圆角形态。

形状	圆角	说明
`auto`	`rounded-md`	标准圆角（默认）
`rounded`	`rounded-full`	药丸形，适用于标签和动作
`square`	`rounded-md`	正方形，固定宽高，适用于图标
`circle`	`rounded-full`	圆形，固定宽高，适用于圆形图标

无法读取 Demo 源码：@playground/button/modules/ButtonShape

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonShape.tsx'

阴影

通过 shadow 控制按钮投影。默认值为 sm，ghost 和 link 变体会自动忽略阴影。

无法读取 Demo 源码：@playground/button/modules/ButtonShadow

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonShadow.tsx'

禁用

设置 disabled 后，按钮变为不可交互状态，同时降低透明度。

无法读取 Demo 源码：@playground/button/modules/ButtonDisabled

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonDisabled.tsx'

加载

设置 loading={true} 时，按钮自动禁用并在 leading 位置显示旋转图标。如果你已经为 leading 传入了自定义内容，加载状态会保留你的内容而不替换为默认 Spinner。

无法读取 Demo 源码：@playground/button/modules/ButtonLoading

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonLoading.tsx'

插槽

通过 leading 和 trailing 插槽在按钮文字前后放置图标或其他内容。

无法读取 Demo 源码：@playground/button/modules/ButtonSlot

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonSlot.tsx'

图标按钮

ButtonIcon 是专门为纯图标场景封装的组件。相比 Button，它默认使用 ghost 变体、square 形状和 accent 颜色，并通过 fitContent 让尺寸自适应内容。

无法读取 Demo 源码：@playground/button/modules/ButtonIconBasic

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonIconBasic.tsx'

设置 fitContent={false} 可以恢复为固定尺寸。

无法读取 Demo 源码：@playground/button/modules/ButtonIconFitContent

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonIconFitContent.tsx'

按钮组

ButtonGroup 将多个按钮组合成一个视觉整体，自动处理圆角合并和相邻边框去重。

通过 orientation 控制排列方向：

无法读取 Demo 源码：@playground/button/modules/ButtonGroupHorizontal

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonGroupHorizontal.tsx'

无法读取 Demo 源码：@playground/button/modules/ButtonGroupVertical

no such file or directory, readAll '/apps/web-ui-playground/src/app/[locale]/(demo)/button/modules/ButtonGroupVertical.tsx'

API

Button

通用属性参考：支持原生 button 元素的所有属性。

Props属性、类型与默认值

11 properties

属性	说明	类型	默认值
color	主题颜色	'primary' \| 'destructive' \| 'success' \| 'warning' \| 'info' \| 'carbon' \| 'secondary' \| 'accent'	'primary'
variant	视觉样式	'solid' \| 'outline' \| 'dashed' \| 'soft' \| 'ghost' \| 'link' \| 'plain' \| 'pure'	'solid'
size	尺寸	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'	'md'
shape	形状	'auto' \| 'rounded' \| 'square' \| 'circle'	'auto'
shadow	投影大小	'none' \| 'sm' \| 'md' \| 'lg'	'sm'
loading	加载状态，自动禁用按钮并显示 Spinner	boolean	false
disabled	禁用状态	boolean	false
leading	前置插槽，放置图标或其他内容	ReactNode	-
trailing	后置插槽，放置图标或其他内容	ReactNode	-
fitContent	宽高自适应内容，不再使用固定高度	boolean	false
asChild	将渲染委托给子元素，合并 props 和行为	boolean	false

ButtonIcon

继承 Button 的全部 Props，并新增以下属性：

Props属性、类型与默认值

2 properties

属性	说明	类型	默认值
icon	图标名称（传入 Icon 组件）	string	-
iconProps	传递给内部 Icon 组件的额外 props	Omit<IconProps, 'icon'>	-

ButtonIcon 的默认值与 Button 不同：variant="ghost"、shape="square"、color="accent"、fitContent={true}。

ButtonGroup

Props属性、类型与默认值

1 properties

属性	说明	类型	默认值
orientation	排列方向	'horizontal' \| 'vertical'	'horizontal'

类型

IconProps

Icon 组件的属性。

字段	类型	说明
icon	string	Iconify 图标名称。
width	number \| string	图标宽度。
height	number \| string	图标高度。
color	string	图标颜色。
inline	boolean	是否以内联方式显示图标。

Button

IconProps

On this page