Card 卡片
容纳相关信息和操作的卡片。variant="glass" 使用共享玻璃材质,保持原圆角、内边距和内容布局;不支持原生玻璃的浅色 iOS/Android 使用白底、细边和轻阴影,显式表面和边框优先。各业务卡片自己选择材质,外层组合不再叠加背景。
代码演示
glass · 玻璃卡片default · 带阴影plain · 仅圆角,无阴影无描边(嵌套用)组合内容
独立维护的信息卡片
东方便利店 · 浦东店
本月订单合计 ¥12,480,主要采购统一冰红茶、阿萨姆奶茶。距离 1.2 km。
plain 卡片不带视觉外延 —— 嵌套到已有 surface 容器内时仅靠 padding + radius 区分内容。
plain + borderColor · 状态彩边(如 Confirmation)
2px 主橙描边,用于操作确认这种需要"挑出来看一眼"的卡片。
已完成 · 拜访
14:02
已完成本日全部 4 个客户拜访,待提交日报。
视觉规范
| 元素 | 规则 |
|---|---|
| 背景 | default/plain 使用主题 c.surface;glass 使用共享玻璃材质 |
| 圆角 | 12px (radius.xl) |
| Padding | 14px (space.6) |
| 阴影 | 0 1px 4px rgba(0,0,0,0.08) (shadow.card) |
Variant plain | 无阴影、无描边,适合嵌套场景 |
主题键(Tokens)
| Token | 来源 | 作用 |
|---|---|---|
c.surface | useColors() | 卡片背景色(白 / 暗色 surface) |
radius.xl | @unif/react-native-design | 默认圆角(12,可被 borderRadius 覆盖) |
space['6'] | @unif/react-native-design | 默认内边距(14,可被 padding 覆盖) |
s.card | useShadow() | default 变体卡片阴影(暗色置零) |
用法
import { Card } from '@unif/react-native-design';
{
/* default — 白卡 + 阴影 */
}
<Card>
<Text>普通卡片</Text>
</Card>;
{
/* plain — 仅圆角,无阴影无描边(嵌套场景) */
}
<Card variant="plain">
<Text>嵌套用</Text>
</Card>;
{
/* 状态色边框(如 Confirmation)— 2px 彩边,颜色走 useColors() */
}
function Confirm() {
const c = useColors();
return (
<Card variant="plain" borderColor={c.primary}>
<Text>操作确认</Text>
</Card>
);
}
{
/* bare — 内容自控 padding(如 Tool 卡片头/体不同 padding)*/
}
<Card variant="plain" bare>
<Header />
<Body />
</Card>;
{
/* fill — Card 撑满 flex 父 + 内部列表滚动(如 Me 屏会话列表)*/
}
<View style={{ flex: 1 }}>
<Card variant="plain" fill>
<Header />
<ScrollView style={{ flex: 1 }}>{/* 长列表 */}</ScrollView>
</Card>
</View>;
API
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
children | ReactNode | — | 卡片内容 |
variant | 'default' | 'flat' | 'plain' | 'glass' | 'default' | default 为主题实色与阴影,plain 为无阴影实色,glass 为玻璃材质;已弃用的 flat 等价于 plain |
padding | number | 14(space['6']) | 内边距 |
borderRadius | number | 12(radius.xl) | 圆角 |
borderColor | string | — | 强调描边色(任意 variant 均生效;启用时默认 2px) |
borderWidth | number | 2 | 与 borderColor 配合 |
bare | boolean | false | 抑制内边距,内容自控(与 variant 正交) |
fallbackColor | ColorValue | 主题 surface | glass 无原生玻璃时的表面底色;原生玻璃仍由系统呈现 |
fill | boolean | false | 撑满模式:外层 + 内层 clip 均 flex:1,Card 在 flex 父里撑满、内容区填满外层(内部 flex:1 滚动列表据此拿到高度) |
style | StyleProp<ViewStyle> | — | 额外样式覆盖 |
testID | string | — | E2E / 测试定位 |
无障碍(a11y)
来源:src/components/ui/Card/Card.tsx、types.ts。
本组件为展示 / 容器用,无交互(渲染为 <View>,仅负责背景 / 圆角 / 阴影 / 内边距)。源码未设置任何 a11y prop,继承底层 <View> 默认。a11y 语义由其 children 内容自行承载;若整张卡片需可点击,请在 children 内放可点区域(如 Cell 的 onPress 或 Button),不要把点击语义挂在 Card 本身。
使用注意
- ❌ 不要叠加多层阴影——卡片只有一种阴影
- ❌ 不要把 List 行做成 Card——List 行用 Cell
- 玻璃卡片直接选择
glass;Android、旧 iOS 或减少透明度时使用fallbackColor或主题surface实色。Web 保留 CSS 近似材质;无 CSS 模糊能力且未启用减少透明度时使用主题渐变。不要在玻璃卡片的祖先上设置 opacity,也不要叠加重复材质。