跳到主要内容

Button 按钮Button · ButtonGroup · ToggleButton

触发一个立即发生的操作：提交、保存、打开浮层。跳转到别的页面时传 href，它会渲染成链接。一个区域里最多放一个主按钮。

变体

默认是灰底的 soft。primary 给页面里最重要的那一个操作，accent 给需要品牌色强调的操作，danger 给不可恢复的操作。

尺寸

高度 32 / 40 / 48，触屏设备上自动各加 4。左右内边距约为高度的 0.48 倍。

图标

leading / trailing 放在文字前后。只有图标时加 iconOnly，并且必须给 aria-label（类型上强制）。

状态

禁用

原生 disabled 会让按钮离开 Tab 顺序。需要保留焦点（比如要配一条解释原因的提示）时改用 aria-disabled，点击同样会被拦下。

加载与成功

loading 时文字上滑让位、尾巴加载器弹入，期间点击无效；结束后把 success 短暂置为 true 会描出对勾。只要传过 loading 或 success（哪怕是 false），按钮就会预留状态位。

撑满与链接

block 撑满一行。传 href 渲染成 <a>；target="_blank" 时自动补 rel。

查看输入框文档

按钮组

ButtonGroup 把一组相关操作排在一起，并统一下发 size / variant / disabled。attached 让按钮连成一体。记得给组一个 aria-label。

撑满

block 让按钮组占满一行并平分宽度，常用在窄容器和对话框底部。

纵向

开关按钮

ToggleButton 有按下 / 弹起两个状态，用 aria-pressed 表达。适合工具栏里的“加粗”“收藏”这类即时生效的开关；设置项请用 Switch。

非受控

受控

当前：已按下

规格

尺寸
32 / 40 / 48 · 圆角全圆 · 左右内边距 = 高 × .48
按下
scale .955 · 90ms ease-out
松开
spring-bouncy 回弹
悬停
只换一档底色 · 150ms，无高光、无棱台、无阴影
描边
仅描边按钮 1.5px · 禁用时保留
加载
文字上滑让位 → 尾巴加载器 → 对勾描线

API

Button

属性类型默认值说明
variant'primary' | 'accent' | 'soft' | 'ghost' | 'outline' | 'danger''soft'变体。在 ButtonGroup 里默认取组的 variant。
size'sm' | 'md' | 'lg''md'高度 32 / 40 / 48。
loadingboolean—加载中：显示加载器，aria-busy，期间不响应点击。
successboolean—成功：描出对勾，期间不响应点击。
leadingReactNode—文字前的图标。
trailingReactNode—文字后的图标。
iconOnlyboolean—图标按钮（正方形）。为 true 时必须同时给 aria-label 或 aria-labelledby。
blockboolean—撑满一行。
disabledboolean—禁用。渲染成链接时改为去掉 href 并加 aria-disabled。
hrefstring—传了就渲染成 <a>；可配 target、rel、download。
type'button' | 'submit' | 'reset''button'原生按钮类型。表单提交按钮要显式写 submit。
…restButtonHTMLAttributes—其余原生属性和 ref 透传到根节点。onClick 收到的是原生事件。

ButtonGroup

属性类型默认值说明
size'sm' | 'md' | 'lg'—组内按钮的默认尺寸。
variantButtonVariant—组内按钮的默认变体。
disabledboolean—整组禁用。
attachedboolean—连体：按钮贴在一起，中间的圆角收小。
orientation'horizontal' | 'vertical''horizontal'排列方向。
blockboolean—撑满一行并平分宽度。

ToggleButton

属性类型默认值说明
pressedboolean—是否按下（受控）。
defaultPressedbooleanfalse初始是否按下（非受控）。
onChange(pressed: boolean) => void—状态变化时触发，参数是新状态。在 onClick 里 preventDefault 可以阻止切换。
…ButtonProps—其余同 Button（不支持 href）。

无障碍

  • 根节点是原生 <button type="button">；传 href 时是 <a>。Enter 和 Space 触发按钮，链接只响应 Enter。
  • 图标按钮必须有 aria-label，读屏读出的是这个名称而不是图标。
  • 加载中带 aria-busy="true"；加载器和对勾是装饰，对读屏隐藏。需要播报结果时请另用 Toast 或 aria-live 区域。
  • ToggleButton 用 aria-pressed 表达状态，读屏会读“已按下 / 未按下”。
  • ButtonGroup 是 role="group"，组内按钮各自是 Tab 停靠点，没有方向键导航。
  • 键盘聚焦时显示统一的焦点环；禁用按钮指针为 not-allowed，不响应悬停和按压。