组件Controls
Button
@mox-hub/ui 组件 · Controls · canonical
button@mox-hub/uiControlscanonicalsrc/components/button.tsx变体轴
variantdefaultoutlinesecondaryghostdestructiveprimarydangerquietsubtleghost-danger
sizedefaultxssmlgiconicon-xsicon-smicon-lgicon-2xsicon-2sm
tonedefaultinfodanger
paddingdefaultp-0.5p-1p-1.5px-1.5 py-0.5px-2 py-0.5px-2 py-1px-2.5 py-1px-2 py-1.5px-2.5 py-1.5px-3 py-1.5px-2.5 py-2px-3 py-2px-3 py-2.5
fontSizedefault2xsxssm
变体演示button
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className* | string | ((state: ButtonState) => string) | — | — |
| variant* | "default" | "destructive" | "secondary" | "outline" | "ghost" | "primary" | "danger" | "quiet" | "subtle" | "ghost-danger" | "default" | — |
| size* | "default" | "sm" | "lg" | "xs" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | "icon-2xs" | "icon-2sm" | "default" | — |
| tone* | "default" | "info" | "danger" | "default" | — |
| padding* | "default" | "p-0.5" | "p-1" | "p-1.5" | "px-1.5 py-0.5" | "px-2 py-0.5" | "px-2 py-1" | "px-2.5 py-1" | "px-2 py-1.5" | "px-2.5 py-1.5" | "px-3 py-1.5" | "px-2.5 py-2" | "px-3 py-2" | "px-3 py-2.5" | "default" | — |
| fontSize* | "default" | "sm" | "xs" | "2xs" | "default" | — |
| children* | ReactNode | — | — |
源码
import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "../lib/utils"
const buttonVariants = cva(
"group/button inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-[color,background-color,border-color,box-shadow,transform,opacity] duration-fast outline-none select-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 active:not-aria-[haspopup]:translate-y-px disabled:pointer-events-none disabled:opacity-50 data-disabled:pointer-events-none data-disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/80",
outline:
"border-border bg-background shadow-xs hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
secondary:
"bg-secondary text-secondary-foreground hover:bg-[color-mix(in_oklch,var(--secondary),var(--foreground)_5%)] aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
ghost:
"hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
destructive:
"bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
// 项目扩展变体(历史保留)
// `primary` 与 `default` 是同一表面的两个入口,hover 必须同值(/80);
// 此前 primary 写 /90 造成同屏主操作悬停深浅不一,且与 Badge 的 /80 漂移。
primary: "bg-primary text-primary-foreground hover:bg-primary/80",
danger: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
// —— E 类批 0 增补(2026-09-27):纯增补,不改任何既有档位的类值 ——
// 来源:生产裸 <button>(`components/ui/` 之外)className 的**形态聚类 + 档位语义**。
// 靶子规模与口径见 `docs/design/修改方案-E类-2026-09-27.md`(正则行级 315 处 /
// 元素级真值 314 处,差 1 处为 JSX 注释误命中)。**本注释刻意不写逐档先例数**:
// 2026-09-28 裁决「删数留结论」——逐档计数在不同口径下不可复现(含/不含
// `components/ui/`、元素级 vs 行级),写进源码即变成无法核对的噪声。分界口径:
// · quiet:文字色变化,**无 hover 底色**(批 6 实测的最大缺口)
// · subtle:文字色变化 + **弱底色**;
// 与 ghost 的唯一差别是「基色为内容弱色」——ghost 不设基色,靠继承,
// 因此需要弱色基色的调用方此前只能写 className 覆盖。
// hover 底用 bg-muted(bg-accent 与 bg-muted 是同一 token 值,见报告)。
// · ghost-danger:静默态 + 悬停/聚焦才转危险色;
// 与既有 destructive 的区别是 **无基色底**,故不与 destructive 重复。
quiet: "text-muted-foreground hover:text-foreground",
subtle: "text-muted-foreground hover:bg-muted hover:text-foreground",
"ghost-danger":
"text-muted-foreground hover:bg-destructive/10 hover:text-destructive focus-visible:border-destructive/40 focus-visible:ring-destructive/20",
},
size: {
default:
"h-control-md gap-1.5 px-2.5 in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pe-2 has-data-[icon=inline-start]:ps-2",
xs: "h-control-xs gap-1 rounded-sm px-2 text-xs in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pe-1.5 has-data-[icon=inline-start]:ps-1.5 [&_svg:not([class*='size-'])]:size-3",
sm: "h-control-sm gap-1 rounded-md px-2.5 in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pe-1.5 has-data-[icon=inline-start]:ps-1.5",
lg: "h-control-lg gap-1.5 px-2.5 has-data-[icon=inline-end]:pe-2 has-data-[icon=inline-start]:ps-2",
icon: "size-control-md",
"icon-xs":
"size-control-xs rounded-sm in-data-[slot=button-group]:rounded-md [&_svg:not([class*='size-'])]:size-3",
"icon-sm":
"size-control-sm rounded-md in-data-[slot=button-group]:rounded-md",
"icon-lg": "size-control-lg",
// —— E 类批 0 增补(2026-09-27):纯增补,不改任何既有档位的类值 ——
// 档名规则:`2<档>` = 该档的下一档,沿用字阶 3xs / 2xs 的既有命名约定
// (`2xs` 即「xs 的下一档」)。
// · icon-2xs = 20px:既有最小档 icon-xs 是 24px,此前 20px 只能写裸 <button>
// · icon-2sm = 28px:落在 xs(24px) 与 sm(32px) 之间的空档
// 圆角刻意不写:基线已是 rounded-md(§4.5「按钮一律 rounded-md,不因尺寸降档」),
// 与 icon / icon-lg 同口径;xs/icon-xs/icon-sm 统一走 rounded-sm / rounded-md,
// 随 --radius 缩放(2026-11-12 P0 半径单根化,默认视觉不变)。
"icon-2xs": "size-5 rounded-sm pointer-coarse:min-h-11 pointer-coarse:min-w-11",
"icon-2sm": "size-7",
},
// —— E 类批 0b 增补(2026-09-28):语义色 tone 轴 ——
// 立项与靶子口径见 `docs/design/修改方案-E类-2026-09-27.md`(§七之二 #1「批 0b 能力
// 二次补档」)。**本注释刻意不写逐档先例数**(2026-09-28 裁决「删数留结论」)。
//
// 值域只收「生产裸 <button> 实测有量级证据、且已被 E 类方案 §19.4/§19.5 点名」的语义档:
// · info = 信息/中性动作(accent-blue)
// · danger = 危险/破坏性动作(accent-red)
// 刻意**不设** success / warning(实测零先例 ⇒ 依「无证据不造档」不立档),
// 也刻意**不设** accent-purple(实测确有量级,但紫不在 tone 词表内,属词表扩容,
// 已上呈人裁)。要补成功/警告档时,须先有先例,再按下方同名规则追加。
//
// 为何写成 `data-[tone=…]:` 作用域而不是裸色类:Tailwind 同一 utility 的胜出由
// **样式表内规则先后**决定,不由 className 书写顺序决定;本仓构建产物实测
// `text-muted-foreground` 排在所有 accent 色之后 ⇒ 若 tone 与任何设色的 variant
// (quiet / ghost / destructive …)并存,裸色类会被静默吞掉。加一档 `data-tone`
// 属性把选择器特异性从 (0,1,0) 提到 (0,2,0)(hover 态 (0,3,0))即可稳压,
// 与 size 档既有的 `in-data-[slot=button-group]:` 是同一手法。
//
// ⚠️ 连带契约:这组类**离开 `data-tone` 属性即为死类**(写了不生效,同幽灵类)。
// 属性由下方 `Button` 组件统一挂载,已有测试守卫「非默认档必带属性 / 默认档必不带」。
// 后续若把这些类改由 `components/ui/tone.ts` 供给,**必须连同 data 作用域一起搬**,
// 否则 tone 会无声失效(§19.5 的 tone 下沉改造请注意此点)。
tone: {
default: "",
info: "data-[tone=info]:text-accent-blue data-[tone=info]:hover:text-accent-blue data-[tone=info]:hover:bg-accent-blue-light",
danger:
"data-[tone=danger]:text-accent-red data-[tone=danger]:hover:text-accent-red data-[tone=danger]:hover:bg-accent-red-light",
},
// —— E 类批 0b 二次补档(2026-09-28):内距轴 ——
// 立项与靶子口径见 `docs/design/修改方案-E类-2026-09-27.md`(§七之二 #1「批 0b 能力
// 二次补档」与「批 6 开工前可行性复核」③ 的缺档分布)。口径:生产裸 `<button>`
// (`src/components/ui/**` 之外,排除 `*.test.*` / `*.stories.*`)className 的
// **形态聚类 + 档位语义**。**本注释刻意不写逐档先例数**(2026-09-28 裁决「删数留结论」):
// 同型计数在不同口径下不可复现,写进源码即成为无法核对的噪声。
//
// 为什么档值是「内距原样写出」而不是 xs/sm/lg 一类的阶梯名:实测的 `px-*/py-*`
// 组合是**二维**的(横内距与纵内距各自独立取档),不存在单一阶梯能覆盖——硬造
// 阶梯名就会给「px-2 py-1.5」与「px-2 py-0.5」这类同横不同纵的形态编出无语义的
// 名字。故档值直接等于它产出的内距类串:**档位表即实测簇的封闭词表**,表外的
// 组合(如 `px-5 py-4`)在类型上不可表达。每个档一一对应实测形态聚类:
// · `p-0.5` / `p-1` / `p-1.5` —— 方形内距(四周等值):图标钮 / 紧凑方钮,
// 与 `size="icon-*"` 同族但走「内距撑高」模型(见下),多以 `opacity-0`
// 悬停显形、出现在行尾或面板角;
// · `px-1.5 py-0.5` / `px-2 py-0.5` / `px-2 py-1` / `px-2.5 py-1` 一族 ——
// 密集工具条钮 / chip(常配 `rounded-sm`、`font-mono`、`text-2xs`,
// 纵内距明显小于横内距);
// · `px-2 py-1.5` / `px-2.5 py-1.5` / `px-3 py-1.5` 一族 —— 列表行钮 / 面板内
// 动作钮(常配 `w-full` + `text-start` + `hover:bg-accent`);
// · `px-2.5 py-2` / `px-3 py-2` / `px-3 py-2.5` 一族 —— 对话框内选项钮 /
// 卡片式钮(`items-start` + 两行文案)。
//
// ⚠️ **本轴会接管高度**(每档都带 `h-auto`)——这是它「可用」的前提,不是顺手加
// 的:实测缺档的裸钮**多数不写 `h-*`,靠内距撑高**,其真实高度落在 20/22/26/28px
// 等位置,而 `size` 轴只提供 h-control-xs(24) / sm(32) / md(36) / lg(40)——若本轴只给
// `px/py` 不动高度,`size` 的定高会留下,档位就落不到目标几何(迁移即产生可见
// 变化,违反批 6 的「无损」前提 ⇒ 造出「禁了但没得用」的档)。故约定:
// **`size` = 定高模型(档位定 h-* 与横内距);`padding` = 内距驱动模型(h-auto +
// 内距),二者同时给时以 `padding` 为准**(cva 输出顺序在本轴在后,twMerge 会丢弃
// `size` 的 `h-*` / `px-*`)。
//
// 命名:本轴**不叫 `inset`**(2026-09-28 裁决)。`ui/card.tsx` 的内距轴叫 `inset`
// 且用**语义档**(xs/sm/md/lg/xl,一维全向 `p-N`);本轴是**二维内距对**
// (`px-* py-*`),语义档名会给「同横不同纵」的形态编出撒谎的名字,故档名即类值。
// 两者值域形态不同 ⇒ 必须异名(通则:同名轴若值域形态不同必须异名)。
//
// 与 `size="icon-*"` 的关系:图标档给的是**完整几何**(`size-N` 定宽定高),与
// 本轴的「内距驱动几何」是两套模型;同给会产生「定宽 + 自高」的矛盾几何
// (已复现:`size="icon-xs" padding="p-1"` → `size-6 h-auto p-1`)。组件在下方
// **内建优先级**:`size` 为 `icon*` 时忽略本轴,故此处无需调用方自行避让。
//
// 默认档为空串 ⇒ 既有全部 variant × size × tone 档的输出**逐字节不变**(纯增补)。
padding: {
default: "",
// 方形内距(图标钮 / 紧凑方钮)
"p-0.5": "h-auto p-0.5",
"p-1": "h-auto p-1",
"p-1.5": "h-auto p-1.5",
// 密集工具条钮 / chip
"px-1.5 py-0.5": "h-auto px-1.5 py-0.5",
"px-2 py-0.5": "h-auto px-2 py-0.5",
"px-2 py-1": "h-auto px-2 py-1",
"px-2.5 py-1": "h-auto px-2.5 py-1",
// 列表行钮 / 面板内动作钮
"px-2 py-1.5": "h-auto px-2 py-1.5",
"px-2.5 py-1.5": "h-auto px-2.5 py-1.5",
"px-3 py-1.5": "h-auto px-3 py-1.5",
// 对话框内选项钮 / 卡片式钮
"px-2.5 py-2": "h-auto px-2.5 py-2",
"px-3 py-2": "h-auto px-3 py-2",
"px-3 py-2.5": "h-auto px-3 py-2.5",
},
// —— E 类批 0b 二次补档(2026-09-28):字阶轴 ——
// 口径同上(生产裸 `<button>` 的形态聚类)。值域只收实测有量级的 `text-2xs` /
// `text-xs` / `text-sm`:`text-sm` 与 Button 基线同值,保留为独立档是为了让
// `size="xs"`(自带 `text-xs`)等场合能**把字阶还原回基线**,而不是「无档可表达」。
// 刻意**不设** `text-3xs` / `text-lg`:
// · `text-3xs` —— 两条独立理由。①宪法 §2.4「任何中文 ≥ `text-xs`,`text-3xs/2xs`
// 仅用于徽标内数字 / 图表轴 / 纯 Latin 元数据」;②实测先例(含本仓展示页)的**主体**
// 是徽标内数字、`font-mono` 元数据、`ms-auto` 计数一类**非动作形态**,把动作文案
// 压到 3xs 属存量违规,不应由 Button 档位予以固化。要补须先有「3xs 的动作文案」
// 先例,并同时修改 §2.4。
// · `text-lg` —— 先例量级不足(仅 1 处,且是展示页里的装饰性大按钮)。
// 对照:`text-2xs` 同受 §2.4 约束,但它确有**动作文案**先例(工具条钮 / chip 上的
// 动作标签),立档是为了让这些存量形态**可被表达、进而可被迁移**;这不改变 §2.4
// 对该轴中文用例的约束——中文动作文案仍应 ≥ `text-xs`,§2.4 由评审把关(无脚本)。
//
// 命名的可读性陷阱(本仓既有裁决点名的):档名 **不叫 `text`**——`text` 作为
// prop 名会被读成「按钮文案」,且与 Tailwind 的 `text-*` 类名(字号 / 颜色 / 对齐
// 三义)同词;`fontSize` 与 CSS 属性同名、无歧义。档值与 token 后缀一一对应
// (`2xs` → `text-2xs`)。
// 默认档为空串 ⇒ 既有输出逐字节不变(纯增补)。
fontSize: {
default: "",
"2xs": "text-2xs",
xs: "text-xs",
sm: "text-sm",
},
},
defaultVariants: {
variant: "default",
size: "default",
// 默认档为空串 ⇒ 既有全部 variant × size 档的输出**逐字节不变**(纯增补)。
tone: "default",
padding: "default",
fontSize: "default",
},
}
)
type ButtonSizeAxis = NonNullable<VariantProps<typeof buttonVariants>["size"]>;
type ButtonPaddingAxis = NonNullable<VariantProps<typeof buttonVariants>["padding"]>;
/**
* 内距轴与 size 轴的**解析优先级**(2026-09-28 裁决)。
*
* `size="icon-*"` 给的是**完整几何**(`size-N` 定宽定高),`padding` 给的是
* **内距驱动几何**(`h-auto` + 内距)——两套模型同给会产生「定宽 + 自高」的矛盾几何
* (已复现:`size="icon-xs"` + `padding="p-1"` → `size-6 h-auto p-1`)。icon 档更封闭,
* 且实测缺档形态里不含「定宽图标钮再改内距」,故 icon 档下**忽略** `padding`。
*
* 独立成导出函数(而非内联在 JSX 里)是为了让这条优先级可被**逻辑单测**锁住——
* 按 §18.2,组件测试不得断言 className,而该优先级只影响类串,故只能在逻辑层断言。
*/
export function resolvePaddingAxis(
size: ButtonSizeAxis,
padding: ButtonPaddingAxis,
): ButtonPaddingAxis {
return size.startsWith("icon") ? "default" : padding;
}
// 组合方式:唯一走 base-ui 原生 `render` prop(宪法 §10.7)。
// Radix 遗产 `asChild` 已于批 6b 移除(radix 已退场,base-ui 不认该 prop)。
// 用 `render` 换成 <a>/<Link> 等非 button 元素时,**必须**由调用方显式传
// `nativeButton={false}`——不是可选优化。实测不传时渲染出的是 `<a type="button" href>`
// 且 role 为空:语义错乱,读屏与测试都无法识别为链接。
// 既有正确用法见 components/ui/pagination.tsx 的 PaginationLink。
function Button({
className,
variant = "default",
size = "default",
tone = "default",
// padding / fontSize 是**只给 cva 用**的轴,必须在此解构——否则会被 `...props`
// 透传到 DOM(`fontSize` 这类 camelCase 属性还会触发 React 警告)。
// 见 button.test.tsx 的「轴不泄漏到 DOM」用例。
padding = "default",
fontSize = "default",
children,
...props
}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>) {
// 内建优先级(2026-09-28 裁决):`size="icon-*"` 是完整几何档(`size-N` 定宽定高),
// 与 `padding` 的「h-auto + 内距」是两套模型;同给会得到「定宽 + 自高」的矛盾几何
// (已复现 `size="icon-xs" padding="p-1"` → `size-6 h-auto p-1`)。icon 档更封闭,
// 故 icon 档下**忽略** `padding`。解析逻辑见 `resolvePaddingAxis`。
const effectivePadding = resolvePaddingAxis(size, padding);
return (
<ButtonPrimitive
data-slot="button"
// tone 档的色类靠本属性拿到特异性(见上方 tone 轴注释)。
// 默认档传 undefined ⇒ 属性不落 DOM,既有用法的渲染结果零变化。
data-tone={tone === "default" ? undefined : tone}
className={cn(
buttonVariants({
variant,
size,
tone,
padding: effectivePadding,
fontSize,
className,
}),
)}
{...props}
>
{children}
</ButtonPrimitive>
)
}
export { Button, buttonVariants }
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
动作按钮,variant、size、tone 控制外观;链接语义用 render 或 asChild,并注意 nativeButton 与真实 button 元素一致。