0 Fork 0

Files

T

2026-10-09 17:32:14 +08:00

7.1 KiB

Raw Blame History

title, description

title	description
Button 按钮	触发一个操作，支持 8 种视觉变体、3 档尺寸与加载态

Button 按钮

按钮用于触发一个即时操作。它承载「点击后发生什么」，因此同一区域里应当只有一个视觉上最重的按钮，其余操作降级表达。

何时使用

用户点击后即时触发一个动作（提交、保存、删除、导出）时使用；
表单、对话框、工具条的最终动作使用 primary（或危险动作使用 danger）；
面板头部、表格行内的图标类动作使用 type="icon"；
只是页面跳转且不需要按钮外观时，直接用 <a>，或使用 type="link" 保持按钮语义。

基础用法

不传 type 时使用 primary；按钮内容写在默认插槽里。

按钮是原生 <button>，因此天然支持 disabled、键盘 Enter / Space 触发与表单语义。

视觉变体

type 决定按钮的视觉重量，请按「操作重要性」选择，而不是按颜色喜好选择。

变体	使用场景
`primary`	页面 / 表单 / 弹窗中的主操作，一屏通常只有一个
`secondary`	次要操作，有底色但无主色，常用于「取消」「重置」
`outline`	与 `primary` 并排出现时的次级操作，或工具条中的常规动作
`ghost`	表格行、卡片内的低强调操作，hover 才出现底色
`danger`	不可逆的危险操作，如删除、停用；建议配合二次确认
`danger-outline`	列表工具条中的危险动作：表达危险语义但不与 `primary` 抢视觉
`link`	视觉上是文字链接，但保留按钮的尺寸、禁用与键盘语义
`icon`	正方形描边图标按钮，用于工具条 / 面板头部动作位

尺寸

size 提供 3 档，默认 medium（--g3-control-height，32px）。

尺寸只影响按钮自身的高度与字号；图标按钮（type="icon"）会同步变成正方形。

图标

使用 #icon 插槽放图标，图标大小跟随按钮字号（1em）；纯图标按钮用 type="icon"，必须提供 aria-label，否则屏幕阅读器读不出来。

type="icon" 的按钮没有文字，因此无障碍标签需要手动补：

<G3Button type="icon" aria-label="搜索">
  <template #icon><Search /></template>
</G3Button>

加载态

loading 会同时做三件事：显示加载图标、进入原生 disabled、拦截 click 事件（不会触发 click），因此可以直接用它防止重复提交。

需要注意的是：loading 时按钮是原生禁用状态，浏览器不会派发 click；组件内部也额外做了拦截，避免在「按下瞬间进入 loading」时重复触发。

禁用态

disabled 使用原生 disabled 属性，同时降低整体透明度并显示禁用光标。

禁用按钮的 click 不会触发，也不会被聚焦（原生行为），所以不要把「必填校验失败」的提交按钮设为禁用——用户会不知道原因。

撑满宽度

block 让按钮占满父容器宽度，常用于移动端、抽屉底部与卡片内。

表单中的提交与重置

htmlType 对应原生 <button type>，配合 G3Form 使用时写 html-type="submit" / "reset" 即可触发表单的提交与重置。

htmlType 默认值是 button，这样按钮放在表单里不会意外提交（原生 <button> 在表单内的默认行为是 submit）。

全局默认值

通过 G3ConfigProvider 的 componentDefaults 可以一次性修改某类组件的默认 props，组件内部的回落顺序是 显式 prop > 全局默认值 > 组件内置默认。

click 事件

@click 回传原生 MouseEvent，可以直接读取修饰键或做 preventDefault。

API

Props

名称	类型	默认值	说明
`type`	`'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-outline' \| 'link' \| 'icon'`	`'primary'`	视觉变体。`icon` 为正方形描边图标按钮（无文字，需自行补 `aria-label`）
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	尺寸。对应高度 24px / 32px / 40px（`--g3-control-height-sm` / `--g3-control-height` / `--g3-control-height-lg`）
`htmlType`	`'button' \| 'submit' \| 'reset'`	`'button'`	原生 `type` 属性。表单里需要提交时写 `submit`
`disabled`	`boolean`	`false`	是否禁用。原生禁用，不派发 `click`，不参与焦点
`loading`	`boolean`	`false`	是否加载中。展示加载图标并阻止 `click`，用于防重复提交
`block`	`boolean`	`false`	是否撑满父容器宽度（`display: flex; width: 100%`）

type 与 size 的 prop 默认值语义上留空，以便 ConfigProvider.componentDefaults.button 生效；未配置全局值时回落到 primary / medium。

Events

名称	参数	说明
`click`	`(event: MouseEvent)`	点击按钮时触发。`disabled` 或 `loading` 时不会触发

Slots

名称	参数	说明
`default`	—	按钮文字。为空时不渲染内容容器
`icon`	—	按钮左侧图标。图标尺寸跟随字号（`1em`），加载中时会被加载图标顶到右侧

类型定义

export type ButtonType =
  | 'primary'
  | 'secondary'
  | 'outline'
  | 'ghost'
  | 'danger'
  | 'danger-outline'
  | 'link'
  | 'icon'

export type ButtonSize = 'small' | 'medium' | 'large'

export interface ButtonProps {
  type?: ButtonType
  size?: ButtonSize
  htmlType?: 'button' | 'submit' | 'reset'
  disabled?: boolean
  loading?: boolean
  block?: boolean
}

export interface ButtonGroupProps {
  /** 排列方向，默认 horizontal */
  orientation?: 'horizontal' | 'vertical'
}

样式变量

按钮只引用设计变量，换肤时覆盖同名变量即可，不需要改组件代码：

变量	默认值	说明
`--g3-control-height`	`32px`	默认高度（`small` / `large` 用 `--g3-control-height-sm / -lg`）
`--g3-radius`	`6px`	圆角
`--g3-color-primary`	`#18181b`	`primary` 底色与 `link` 文字色
`--g3-color-primary-on`	`#fafafa`	`primary` 上的文字色
`--g3-color-danger`	`#ec4246`	`danger` / `danger-outline` 的红
`--g3-fill` / `--g3-fill-hover`	`rgba(0,0,0,.04 / .08)`	`secondary` / `ghost` / `icon` 的底色

设计说明

hover 去抖：按钮的「离开 hover」过渡带 60ms 延迟，用来吸收鼠标在按钮边缘反复进出造成的背景闪烁；「进入 hover」延迟为 0，保证跟手。
按下反馈：:active 时 transform: scale(0.97)，加载态会压掉缩放，避免「进行中」的按钮抖动。
禁用态：整体 opacity: .5，保留原配色，不再改文字颜色——这样深浅主题下都能看出是同一个按钮。

7.1 KiB Raw Blame History Unescape Escape