Button

触发即时操作。中文惯用名：按钮。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.button`
名称	Button
二级分类	通用（`general`）
用途	触发即时操作
描述	中文惯用名：按钮。

预览

静态结构：Button 渲染为单个 <button> 根节点（vendored shadcn Button 适配），variant=primary 映射实心主按钮、default 映射描边按钮；loading 时前置旋转图标并禁用点击；icon 通道在文本前渲染 Icon；配置 tooltip 时以 Tooltip 包裹，但根节点仍为按钮本体。

DSL 结构

DslNode

{
  "type": "Button",
  "props": {
    "text": "提交订单",
    "variant": "primary",
    "size": "large"
  },
  "events": {
    "onClick": {
      "action": "setState",
      "params": {
        "submitted": true
      }
    }
  }
}

何时用

何时使用

触发即时操作：提交表单、保存、创建、删除等改变数据或触发流程的动作。
对话框 / 抽屉 / 卡片内的主、次操作（主操作每区最多一个）。
工具栏、列表操作列中的动作入口。

何时不用

页面、位置或外部资源跳转：使用 Link / 导航组件，不使用 Button。
状态切换（如启用 / 停用）：使用 Switch、Tag 或 Segmented。
需要展示加载进度的长时间任务：使用 Progress 类反馈组件，Button 的 loading 仅表示操作进行中。

变体

变体	视觉形态	适用场景
default 默认	描边按钮（outline）	常规操作；与主按钮成组出现的次操作
primary 主要	实心品牌色按钮	每区唯一的高权重主行动（提交、创建、确认）
dashed 虚线	虚线描边	配置 / 构建类操作、占位添加（如「添加字段」）
link 链接	文字按钮，hover 出现下划线	低权重、导航式操作（如「查看全部」）
text 文字	无边底文字按钮	最轻量操作，如工具栏、卡片角落动作
danger 危险（修饰）	上列变体叠加 danger，映射 destructive 或文字标红	删除等破坏性操作，需配合二次确认
尺寸 small / middle / large	三档高度（small≈sm / middle≈默认 / large≈lg）	按容器密度选择；默认 middle

API 属性

属性	类型	默认值	说明
`text`	`string`	—	按钮文本；也可用 children 渲染内容
`icon`	`string`	—	图标名（Icon 白名单，kebab-case / PascalCase 均可），渲染在文本前
`tooltip`	`string`	—	提示文案：hover / focus 按钮时展示 Tooltip
`variant`	`'default'	'primary'	'dashed'
`danger`	`boolean`	false	危险态；link / text 变体保持形态、文字标红
`size`	`'small'	'middle'	'large'`
`loading`	`boolean`	false	加载中：显示旋转图标并禁用（优先于 icon）
`disabled`	`boolean`	false	禁用；未显式给定时 loading 也会禁用
`submit`	`boolean`	false	true 时作为 Form 的提交按钮（type=submit）
`onClick`	`() => void`	—	点击事件（Renderer 绑定 events.onClick）

使用规范

同一区域最多一个 primary 实心主按钮，其余操作降级为 default / text。
危险操作（danger）必须配合二次确认（Popconfirm 或 Dialog），确认文案说明后果。
提交类操作使用 submit + loading：进行中禁用并防重复提交。
按钮文案用动词开头（「保存」「创建项目」），不超过 6 字，避免「确定 / 取消」以外的模糊文案。
link / text 变体不承载主流程动作；禁用态保持可见，不用隐藏代替。

正例

✓ 表单底部：primary「保存」+ default「取消」，保存中按钮转 loading 并禁用。
✓ 删除条目：text「删除」+ danger，点击后弹 Popconfirm 二次确认。
✓ 列表操作列：text「编辑」「复制」，权重从低到高依次排列。

反例

✕ 用 Button 实现页面跳转（应使用 Link / 导航组件）。
✕ 同屏并排多个 primary 实心按钮，用户无法判断主行动。
✕ 危险操作无确认直接执行，或 loading 期间仍可重复点击提交。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。