组件Layout & Shells
Card
@mox-hub/ui 组件 · Layout & Shells · canonical
card@mox-hub/uiLayout & Shellscanonicalsrc/components/card.tsx变体演示card
卡片标题
卡片描述文本,一行以内。
内容区。
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className* | string | — | — |
| size* | "default" | "sm" | "default" | — |
| variant* | "default" | "outline" | "default" | — |
| border* | "ring" | "solid" | "dashed" | "ring" | — |
| surface* | "default" | "flat" | "translucent" | "default" | — |
| inset* | "default" | "sm" | "lg" | "xs" | "md" | "xl" | "default" | — |
源码
import * as React from "react"
import { cn } from "../lib/utils"
function Card({
className,
size = "default",
variant = "default",
border = "ring",
surface = "default",
inset = "default",
...props
}: React.ComponentProps<"div"> & {
size?: "default" | "sm"
variant?: "default" | "outline"
border?: "ring" | "solid" | "dashed"
surface?: "default" | "flat" | "translucent"
inset?: "default" | "xs" | "sm" | "md" | "lg" | "xl"
}) {
return (
<div
data-slot="card"
data-size={size}
data-variant={variant}
data-border={border}
data-surface={surface}
data-inset={inset}
className={cn(
"group/card flex flex-col gap-3 overflow-hidden rounded-xl bg-card py-3.5 text-sm text-card-foreground shadow-xs ring-1 ring-border/50 [--card-spacing:--spacing(4)] [--card-radius:var(--radius-xl)] has-[>img:first-child]:pt-0 data-[size=sm]:py-2.5 data-[size=sm]:gap-2 data-[size=sm]:[--card-spacing:--spacing(3)] *:[img:first-child]:rounded-t-(--card-radius) *:[img:last-child]:rounded-b-(--card-radius)",
// —— E 类批 0 增补(2026-09-27):纯增补,variant=default 时下面整行不生效 ——
// 归纳自手写卡片壳的形态聚类(口径:同一 class 串内「圆角档 + bg-card」且未
// import ui/card)。主形态 = 「描边 + 无投影 + rounded-lg」——正是 §4.5
// 「卡片/面板 = rounded-lg」那一档;手写壳以 border 描边为主(几乎不用 ring),
// 多数无 shadow。**本注释刻意不写逐类「N 行 / M 文件」先例数**(2026-09-28
// 裁决「删数留结论」):同型计数在不同口径下不可复现——本仓实测同一靶子出现过
// 「39 行」与「40 行」两种结果,写进源码即变成无法核对的噪声。
// 故 outline 一次给出「描边 + 去投影 + 卡片圆角」三件事;default 保留
// rounded-xl + ring-1 + shadow-xs 不动,既有 55 个消费方渲染不变(已复算:55)。
// 置于 className 之前,保留调用方的最终覆盖权。
variant === "outline" &&
"rounded-lg border border-border ring-0 shadow-none [--card-radius:var(--radius-lg)]",
// —— E 类批 0b 增补:Card 第二·三轴,纯增补,默认值不生成任何类 ——
//
// 第二轴 `border`(描边样式):Card 基线用「环」描边,与 `variant="outline"`
// 的「实线」描边被焊在同一根 `variant` 轴上,导致「要基线的圆角档 + 要实线描边」
// 无档可用——手写卡片壳里这一类正是靠 className 传 `border` 绕过的(违反
// §19.4 的 className 白名单)。抽出描边样式轴后,`variant="default"` 不再被
// 强制成环,`variant` 只管圆角与表面语义。形态分布与逐行依据见
// `docs/design/修改方案-E类-2026-09-27.md`(批 0「未入档清单」与批 7 开工条件)。
border === "solid" && "border border-border ring-0",
border === "dashed" && "border border-dashed border-border ring-0",
// 第三轴 `surface`(表面/强调层级):实测「无投影 / 有投影」是壳的强调度主轴,
// 而它同样被焊进了 `variant`(default 带投影、outline 去投影)。半透明弱化壳
// (更低一档的强调)此前同样无档可用。
// `flat` = 去投影(§3.6 的复位档 `shadow-none`),层级交给描边;
// `translucent` = 弱化壳:半透明底 + 半色描边 + 去投影。色名一律取自
// `index.css` 已注册的语义 token,未新增 token。
surface === "flat" && "shadow-none",
surface === "translucent" &&
"border border-border/60 bg-card/60 ring-0 shadow-none",
// —— E 类批 0b 增补:Card 内距轴 `inset`,纯增补,`default` 不生成任何类 ——
//
// 形态依据(口径:`components/ui/` 之外、排除 `*.test.*` / `*.stories.*` 的生产面里,
// 同一 class 串内「圆角档 + 卡片底色」且未 import `ui/card` 的手写壳):这类壳是**裸壳**
// ——内容直接挂在壳根上,没有 header/content 槽位拆分,内距类因此落在**壳根元素**上。
// 故本轴只接管**根元素内距**,不覆盖 `--card-spacing`:槽位级内距在仓内实测无该类先例,
// 按「无证据不造档」不立;`size` 已给槽位内距两档,两轴**按形态分工、不叠加**:
// · 裸壳形态:内距由本轴给(`p-*`),内容直接作为 children;
// · 槽位形态:内距由 `size` 经 `--card-spacing` 给,走 CardHeader / Content / Footer;
// 两形态同用会「根内距 + 槽位内距」叠加,属禁止组合。
// 档位值域 = 裸壳实测的**对称内距**取值(写成 `px-N py-N` 的等值形式按同一内距归并到该档);
// 档名沿用 `COMPONENTS.md` 的尺寸词表,其中 `md` 与 Card 基线 `--card-spacing(4)` 同值、
// `sm` 与 `size=sm` 的槽位间距同值——本轴不是另起的一套刻度,而是既有内距阶梯的显式化。
// 两个 `.5` 档与相邻主档仅差一档(2px)、且属零散取值,**不立档**(否则本轴出现相邻不可辨档)。
// 与 `size` 同时给出时的裁决(已按构建产物取证):垂直以 `size` 档为准——`data-[size=*]:py-*`
// 作用域类特异性高于裸 `p-*`;水平以本轴为准。
//
// 轴名(2026-09-28 裁决,跨组件口径):本轴叫 `inset`——**语义档 + 一维全向**
// (`p-N`,档名 xs/sm/md/lg/xl)。`ui/button.tsx` 另有一根内距轴,但那是**二维内距对**
// (`px-* py-*`),语义档名会给「同横不同纵」的形态编出撒谎的名字,故那边档名即类值
// 且**必须异名**(叫 `padding`)。通则:**同名轴若值域形态不同必须异名**。
inset === "xs" && "p-2",
inset === "sm" && "p-3",
inset === "md" && "p-4",
inset === "lg" && "p-6",
inset === "xl" && "p-8",
className
)}
{...props}
/>
)
}
function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-header"
className={cn(
"group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-(--card-radius) px-(--card-spacing) has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-(--card-spacing)",
className
)}
{...props}
/>
)
}
function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-title"
className={cn(
"font-heading text-heading-4 leading-normal font-semibold group-data-[size=sm]/card:text-sm",
className
)}
{...props}
/>
)
}
function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-description"
className={cn("text-sm text-muted-foreground", className)}
{...props}
/>
)
}
function CardAction({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-action"
className={cn(
"col-start-2 row-span-2 row-start-1 self-start justify-self-end",
className
)}
{...props}
/>
)
}
function CardContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-content"
className={cn("flex flex-col gap-3 px-(--card-spacing)", className)}
{...props}
/>
)
}
function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="card-footer"
className={cn(
"flex flex-wrap items-center justify-end gap-2 rounded-b-(--card-radius) px-(--card-spacing) [.border-t]:pt-(--card-spacing)",
className
)}
{...props}
/>
)
}
export {
Card,
CardHeader,
CardFooter,
CardTitle,
CardAction,
CardDescription,
CardContent,
}
可访问性与 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。
用法说明
卡片容器,由 Card、Header、Title、Description、Content、Footer 组合;整卡可点击时用 Link 包裹标题。