Button

触发操作或导航，支持文字、图标、加载与禁用状态，适合从主要操作到轻量工具按钮的不同场景。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于触发操作。无外壳图标操作用 bare；有内边距的纯图标按钮显式声明 iconOnly 并提供 aria-label。bare 需要透明度 hover 时用 emphasis="muted"。内容切换用 Tab，互斥参数选择用 Segmented。

无上下文时默认 gray、sm；显式 variant / size 优先于组配置。
纯图标必须提供可访问名称；bare 去掉外壳，iconOnly 保留按钮外壳，组件不会根据内容自动判断。

导入

import { Button } from '@snowui-design-system/components';

用法

灰色变体

填充变体

描边变体

无边框变体

仅图标

无底色

强调程度

切换

API 参考

属性	类型	默认值	示例	描述
`variant`	`"gray" \| "filled" \| "outline" \| "borderless"`	`—`	`variant="gray"`	按钮变体；显式值优先，其次嵌入 ButtonGroup 或 Breadcrumb 的上下文，无上下文时回退 gray。
`size`	`"sm" \| "md" \| "lg"`	`—`	`size="sm"`	控制按钮字号、内边距、圆角及子图标尺寸；显式值优先，其次 ButtonGroup/集合及父级尺寸上下文，无上下文时为 sm。
`iconOnly`	`boolean`	`false`	`iconOnly`	有 padding 的纯图标按钮模式，专门控制只有图标时的对称 padding 和图标大小；sm/md/lg 图标为 16/20/24px。无外壳图标按钮直接使用 bare。缺少 aria-label、aria-labelledby 或 title 时开发环境警告。
`bare`	`boolean`	`false`	`bare`	无外壳按钮，以图标操作为主，也可包含文字或其他内容。忽略 variant，移除 padding、radius、背景、边框和 hover overlay，保留内容 gap。无需叠加 iconOnly；同 size 的图标与 iconOnly 一致，为 16/20/24px，子图标显式 size 优先。默认 100% 不透明，emphasis="muted" 启用 40% → hover 100%。
`emphasis`	`"normal" \| "muted"`	`"normal"`	`emphasis="normal"`	bare 模式的视觉强调级别。`normal` 常态与 hover 均为 100%；`muted` 常态为 40%，hover 提升到 100%。非 bare 模式下不改变现有 variant 视觉。
`backgroundBlur`	`boolean`	`false`	`backgroundBlur`	是否模糊按钮背后的内容。开启时使用与 BarChart 模糊浮层一致的 `backdrop-filter: blur(1.25rem)`。
`gap`	`number`	`—`	`gap={42}`	兼容间距编号，映射原gap Token；图文／独立文字内容间距至少4 CSS px，0按下限处理，保留更大首选值。无需另包Frame。
`scaleOnHover`	`boolean`	`—`	`scaleOnHover`	是否同时启用 Button 内置背景层 hover 放大及配套点击缩回 / 恢复动效。独立动作默认开启；内容默认跟随缩放，命中区和布局不变。复合控件容器可提供 `false` 默认值，子 Button 显式传 `true` 可重新开启。bare 没有背景层，因此无视觉效果；本 Prop 不覆盖显式 `whileHover`。
`contentScaleOnHover`	`boolean`	`—`	`contentScaleOnHover`	是否让文字、Icon、Spinner 等内容作为整体跟随内置背景 hover 与点击缩放。`false` 仅关闭内容缩放；`true` 仍要求背景缩放生效，不能绕过 scaleOnHover=false、bare、disabled 或显式 whileHover 接管。
`toggle`	`boolean`	`false`	`toggle`	Toggle 模式语法糖。内部自动注入 `Click={{ Idle: "Active", Active: "Idle" }}` 与 `whileClick=false`；Active 状态下由 Frame 自动暴露的 `data-state="Active"` 触发 Brand 配色（gray / outline / borderless 生效，filled 排除）；`aria-pressed` 由 Frame 自动输出。消费方可继续传 `Click` / `whileClick` 显式覆盖。
`holdRepeat`	`boolean`	`false`	`holdRepeat`	开启指针按住连发；仅对未禁用的 button 宿主主按钮按压生效。按下立即触发一次 click，等待后周期触发，松开或取消停止；不为链接或键盘增加连发。
`holdRepeatDelay`	`number`	`260`	`holdRepeatDelay={42}`	开始周期连发前的等待时间，单位 ms，负值按 0 处理；仅 holdRepeat=true 生效，第一次周期点击还需等待 holdRepeatInterval。
`holdRepeatInterval`	`number`	`80`	`holdRepeatInterval={42}`	按住期间相邻周期 click 的间隔，单位 ms，最小按 1 处理；仅 holdRepeat=true 生效。
`children`	`Snippet`	`—`	`<Button>Content</Button>`	按钮内的文字、图标或其他内容；有外壳纯图标用法设置 iconOnly，无外壳用 bare；两者的纯图标用法均须提供可访问名称，组件不通过内容自动推断。