React 组件
UGButton 按钮
用于触发操作的基础控件。外观、语义色、尺寸和状态彼此独立，可覆盖工具栏、表单、危险确认与移动端全宽操作。
导入方式
按需从包入口导入组件，并在应用入口引入一次样式文件。
tsx
import { UGButton, UGButtonGroup } from '@ug666/ui-react'按钮类型
外观只表达操作层级；链接外观仍是操作按钮，页面导航请使用 UGLink。
语义按钮
用于成功、警告、危险和信息操作。
图标与位置
图标属于按钮内容，可放在文字前后；纯图标按钮必须提供 aria-label。
形状
标准圆角用于常规界面，胶囊和正圆仅在空间与场景需要时使用。
尺寸
三档文字按钮和两档正方形图标按钮共享统一高度体系。
加载状态
加载会阻止重复点击；可以保留原文、替换文字、改变位置或提供自定义指示器。
禁用状态
不同外观在禁用后仍保留原有层级，但不响应点击或键盘激活。
全宽按钮
适合移动端主操作、登录提交和窄容器底部操作。
配置继承与覆盖
在应用根节点配置一次，后代按钮默认继承；组件属性优先，嵌套 Provider 只覆盖局部。颜色、圆角和字体由根 Token 统一控制。
按钮组与连续按钮
相关操作可以统一排列；按钮组只负责布局与公共配置，不承担选中值管理。
统一配置、纵向排列
组级外观、尺寸和禁用状态会下发给子按钮；纵向模式适合窄侧栏操作区。
原生行为与无障碍
默认 type 为 button；组件透传原生属性，并保留 Tab、Enter、Space 键盘行为。
按钮属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| variant | 'solid' | 'soft' | 'default' | 'secondary' | 'outline' | 'dashed' | 'ghost' | 'text' | 'link' | 兼容语义预设 | 'default' | 控制按钮外观。primary、success 等旧语义预设继续兼容。 |
| tone | 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 按 variant 推导 | 设置语义颜色，可与 solid、soft、outline、dashed、ghost、text、link 组合。 |
| size | 'default' | 'sm' | 'lg' | 'icon-sm' | 'icon' | ConfigProvider / default | 控制文字按钮高度或正方形图标按钮尺寸；未设置时继承全局尺寸。 |
| shape | 'default' | 'circle' | 'round' | 'default' | 设置标准圆角、正圆或胶囊形态。 |
| block | boolean | false | 让按钮宽度占满父容器。 |
| loading | boolean | false | 显示加载指示器、设置 aria-busy 并阻止重复点击。 |
| loadingText | ReactNode | — | 加载时替换按钮正文；不传则保留原文，减少宽度跳动。 |
| loadingIcon | ReactNode | Loader2 | 替换默认加载指示器。 |
| loadingPlacement | 'start' | 'end' | 'start' | 控制加载指示器位于文字起始或末尾。 |
| disabled | boolean | ConfigProvider / false | 禁用原生按钮；全局或按钮组禁用时同样生效。 |
| type | 'button' | 'submit' | 'reset' | 'button' | 原生按钮类型；默认不会意外提交表单。 |
| children | ReactNode | — | 按钮正文，可组合前置或后置图标。 |
按钮组属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| variant | ButtonVariant | — | 统一设置组内按钮外观，子按钮可以覆盖。 |
| tone | ButtonTone | — | 统一设置组内按钮语义色，子按钮可以覆盖。 |
| size | ButtonSize | ConfigProvider | 统一设置组内按钮尺寸；未设置时继承全局尺寸。 |
| shape | ButtonShape | — | 统一设置组内按钮形状。 |
| disabled | boolean | ConfigProvider / false | 禁用组内全部按钮；全局禁用时同样生效。 |
| orientation | 'horizontal' | 'vertical' | 'horizontal' | 设置横向或纵向排列。 |
| attached | boolean | false | 合并相邻按钮边界，形成连续操作组。 |
| children | ReactNode | — | 按钮组内容，通常放置 UGButton。 |
| className / style | string / CSSProperties | — | 扩展组容器布局和局部样式。 |
| 原生属性 / ref | HTMLAttributes<HTMLDivElement> / Ref<HTMLDivElement> | — | 透传 aria-*、data-* 和原生事件，并暴露实际 group 容器。 |
原生属性与 Ref
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| onClick | MouseEventHandler<HTMLButtonElement> | — | 原生点击事件；disabled 或 loading 时不会触发。 |
| ref | Ref<HTMLButtonElement> | — | 获取实际的 HTMLButtonElement。 |
| 原生属性 | ButtonHTMLAttributes<HTMLButtonElement> | — | 透传 aria-*、data-*、name、value、form 等原生按钮属性。 |