ant-design Card 基础卡片完全指南：标题、内容与操作区域的正确打开方式-平芜编程栈

ant-design Card 基础卡片完全指南：标题、内容与操作区域的正确打开方式

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design

本篇技术指南聚焦 ant-design（Ant Design）组件库中 Data Display 分组下的 Card（卡片）组件的基础用法：如何搭建一张同时包含标题（title）、内容（body）与右上角操作区（extra）的标准卡片，以及default与small两种尺寸的差异与切换方式。读完本文，你将掌握 Card 组件的核心属性组合、源码级的结构原理，并能结合 loading、actions、Meta、Tabs 等进阶特性，在实际项目中直接落地可复用的卡片布局。

一、demo 原文与设计意图

在仓库中，基础卡片示例位于 components/card/demo/basic.tsx，其配套文档 components/card/demo/basic.md 对该示例的定位做了两段说明：

中文：包含标题、内容、操作区域。
英文：A basic card containing a title, content and an extra corner content. Supports two sizes:defaultandsmall.

也就是说，这个示例要传达的核心信息是三点：标题区（title）、内容区（children）、右上角操作区（extra），外加两种尺寸规格（default/small）。这是所有 Card 复杂用法（网格、标签页、加载态、Meta 元信息等）的最小公共骨架。

二、基础卡片源码解析

basic.tsx的完整代码如下：

import React from 'react'; import { Card, Space } from 'antd'; const App: React.FC = () => ( <Space direction="vertical" size={16}> <Card title="Default size card" extra={<a href="#">More</a>} style={{ width: 300 }}> <p>Card content</p> <p>Card content</p> <p>Card content</p> </Card> <Card size="small" title="Small size card" extra={<a href="#">More</a>} style={{ width: 300 }}> <p>Card content</p> <p>Card content</p> <p>Card content</p> </Card> </Space> ); export default App;

逐项拆解：

属性	值	作用
`title`	`"Default size card"`	卡片头部标题，渲染在`ant-card-head-title`区域
`extra`	`<a href="#">More</a>`	右上角操作区，渲染在`ant-card-extra`区域，默认靠右对齐
`size`	`"small"`（第二张）	切换为紧凑尺寸；不传或传`"default"`则为标准尺寸
`style`	`{ width: 300 }`	示例中通过行内样式固定卡片宽度，实际项目中可用布局容器控制
`Space`	`direction="vertical" size={16}`	垂直排列两张卡片，间距 16px，避免示例挤在一起

1. 头部（head）的渲染条件

从 components/card/Card.tsx 的实现看，头部只有在title、extra、tabList三者至少存在一个时才会渲染：

if (title || extra || tabs) { head = ( <div className={`${prefixCls}-head`} style={mergedHeadStyle}> <div className={`${prefixCls}-head-wrapper`}> {title && <div className={`${prefixCls}-head-title`}>{title}</div>} {extra && <div className={`${prefixCls}-extra`}>{extra}</div>} </div> {tabs} </div> ); }

因此，只传children不传title/extra时，Card 会渲染成一张没有头部的极简卡片（见 components/card/demo/simple.tsx）。extra之所以显示在右上角，是因为样式里设置了marginInlineStart: 'auto'（见 components/card/style/index.ts 中ant-card-extra规则），在 flex 布局下被推向最右侧。

2. 内容区（body）

children统一包裹在ant-card-body容器中，默认内边距来自 token 的cardPaddingBase（即paddingLG）。当loading为真时，body 内会替换为Skeleton加载骨架（paragraph={{ rows: 4 }}），见 Card.tsx 中的loadingBlock实现。

3. 两种尺寸的本质差异

size="small"不是简单缩小字号，而是整套头部/内容区的尺寸 token 切换。在 components/card/style/index.ts 的genCardSizeStyle中可以看到：

头部最小高度：headerHeightSM（fontSize * lineHeight + paddingXS * 2）
头部字号：headerFontSizeSM（即fontSize，小于默认的fontSizeLG）
body 内边距：cardPaddingSM（固定 12px，源码注释为 "Fixed padding."）

而默认尺寸对应headerHeight、headerFontSize与cardPaddingBase。在组件内部，size会经由useSize合并 ConfigProvider 的全局尺寸配置后生成mergedSize，并最终体现在根元素 classant-card-small/ant-card-default上（见 Card.tsx 的classString拼装逻辑）。

4. 尺寸与 Tabs 的联动

值得注意的源码细节：当 Card 同时使用tabList时，尺寸还会透传给内部 Tabs——mergedSize为default时 Tabs 用large，为small时 Tabs 用small（见 Card.tsx 中tabSize的推导）。测试用例 components/card/tests/index.test.tsx 中也验证了size="small"时 Tabs 会应用ant-tabs-smallclass。

三、从基础卡片到完整能力矩阵

basic.tsx只用了 3 个属性，但同一Card组件在 components/card/index.en-US.md 中暴露了完整的 API 面，基础用法是理解其余能力的起点：

属性	说明	默认值
`actions`	底部操作列表，`Array<ReactNode>`，等宽均分排列	-
`bordered`	是否渲染边框	`true`
`cover`	卡片封面图区域（渲染于头部之下、body 之上）	-
`hoverable`	悬停时抬升阴影（`cursor: pointer`+`boxShadow`过渡）	`false`
`loading`	内容加载时展示 Skeleton 骨架屏	`false`
`size`	`default`\|`small`	`default`
`type`	`inner`（内嵌卡片，用于嵌套场景）	-
`tabList`/`activeTabKey`/`defaultActiveTabKey`/`onTabChange`/`tabBarExtraContent`/`tabProps`	卡片内置 Tabs 标签页	-
`classNames`/`styles`	5.14.0 起按语义模块（`header`、`body`、`extra`、`title`、`actions`、`cover`）定制 class 与样式	-

在 Card.tsx 中还通过React.Children.forEach检测 children 中是否包含Card.Grid，并自动添加ant-card-contain-grid使 body 变为 flex 换行布局；检测到tabList时添加ant-card-contain-tabs。

组合用法示例

加载态卡片（见 components/card/demo/loading.tsx）：

<Card loading={loading} actions={actions} style={{ minWidth: 300 }}> <Card.Meta avatar={<Avatar src="..." />} title="Card title" description="..." /> </Card>

带封面与元信息的卡片（见 components/card/demo/meta.tsx）：

<Card style={{ width: 300 }} cover={<img alt="example" src="..." />} actions={[<SettingOutlined key="setting" />, <EditOutlined key="edit" />, <EllipsisOutlined key="ellipsis" />]} > <Card.Meta avatar={<Avatar src="..." />} title="Card title" description="This is the description" /> </Card>

内置标签页卡片（见 components/card/demo/tabs.tsx）：通过tabList+activeTabKey+onTabChange受控切换内容，tabBarExtraContent可在标签栏右侧追加操作；不传title时标签页直接占据头部。

网格卡片（见 components/card/demo/grid-card.tsx）：多个Card.Grid子元素自动等宽换行，每个 Grid 默认hoverable=true，可用style={{ width: '25%' }}自定义宽度。

四、组件结构：Card、Card.Meta 与 Card.Grid

Card是一个复合组件，从 components/card/index.tsx 可以看到它通过挂载静态属性组合而成：

Card.Grid = Grid; Card.Meta = Meta;

Card.Meta（见 components/card/Meta.tsx）：由avatar、title、description三部分组成，内部渲染为ant-card-meta-avatar与ant-card-meta-detail（包含-title、-description）两块结构，适合展示对象型内容。
Card.Grid（见 components/card/Grid.tsx）：渲染为ant-card-grid，通过 box-shadow 绘制网格分隔线，hover 时抬升为cardShadow。

整体 DOM 结构自上而下为：head（含 head-title 与 extra）→cover→body→actions，最终渲染在单个div根节点上并支持ref获取。

五、Design Token 与样式定制

Card 的视觉尺寸与颜色全部走组件级 Token，定义于 components/card/style/index.ts 的prepareComponentToken：

Token	默认值来源	含义
`headerBg`	`transparent`	头部背景色
`headerFontSize`/`headerFontSizeSM`	`fontSizeLG`/`fontSize`	头部字号（默认/小号）
`headerHeight`/`headerHeightSM`	由字号、行高与 padding 计算	头部最小高度
`actionsBg`	`colorBgContainer`	操作区背景
`actionsLiMargin`	`paddingSM 0`	操作项纵向 margin
`extraColor`	`colorText`	extra 区文字颜色

此外还有内部合并 token：cardPaddingBase = paddingLG、cardPaddingSM = 12、cardShadow = boxShadowCard、cardActionsIconSize = fontSize。开发者可通过ConfigProvider的theme.components.Card覆盖这些 Token，配合 components/card/demo/component-token.tsx（debug 示例）查看全部可调项。

六、实战小结

最小可用卡片：<Card title="..." extra={...}>content</Card>即包含标题、内容、操作区三大区域，对应 basic demo 的设计意图。
尺寸选择：信息密度高的紧凑场景（如侧栏、弹窗内嵌）用size="small"；常规内容区用默认default，二者通过ant-card-smallclass 与对应 Token 生效。
进阶组合：loading（骨架屏）、actions（底部操作）、cover（封面）、Card.Meta（元信息）、Card.Grid（网格）、tabList（标签页）都建立在基础结构之上，可在 components/card/index.en-US.md 查阅完整 API 表，在 components/card/demo 目录下查阅全部可运行示例。