Ant Design Card 组件完整使用指南从基础布局、语义化定制到源码级原理【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design卡片Card是 Ant Design 数据展示体系中最常用的信息容器之一用于将围绕单一主题的多种类型、多种尺寸的内容聚合在一起形成清晰的内容块。本文基于 ant-design 仓库中 Card 组件的官方英文文档components/card/index.en-US.md及其源码与示例展开完整覆盖 Card 的全部 API、组合式子组件 Card.Grid / Card.Meta、语义化结构定制classNames / styles、设计令牌Design Token定制并深入到 Card.tsx 等源码剖析其实现原理帮助你把它用得既正确又极致。什么时候使用卡片When To Use卡片适合用来承载与某个单一主题相关的内容集合。它的内容可以是多种元素混合而成——标题、说明文字、封面图、操作按钮、标签页甚至嵌套网格且这些元素可以有不同类型与尺寸。典型场景包括商品/文章/人物的信息展示卡仪表盘或后台页面的内容分区需要聚合入口与快捷操作的卡片式导航。官方文档给出的核心使用语句非常简单见 API 区段的起始示例Card titleCard titleCard content/Card渲染后卡片会呈现标准的头部标题 内容区结构。所有与 HTML 属性相关的扩展能力遵循 Ant Design 的 Common props通用属性约定。基础用法头部、内容与右上角操作区最基本的卡片包含标题title、内容children以及通过extra渲染在右上角的附加操作。仓库中的 basic 示例 同时演示了两种尺寸sizeimport { Card, Space } from antd; Space vertical size{16} Card titleDefault size card extra{a href#More/a} style{{ width: 300 }} pCard content/p pCard content/p pCard content/p /Card Card sizesmall titleSmall size card extra{a href#More/a} style{{ width: 300 }} pCard content/p pCard content/p pCard content/p /Card /Spacetitle/extra类型都是ReactNode可以传入任意元素如a、Button、下拉等size当前支持medium默认与small。源码中CardSize ExcludeSizeType, large | default即排除了大号并保留了已废弃的default取值见 Card.tsx 的类型注释default将在 v7 移除请改用medium若仍传入default开发模式下会通过devUseWarning(Card)输出弃用提示style{{ width: 300 }}说明卡片宽度默认由容器/内容决定通常需要自己给定宽度或交由父级如 Row/Col 栅格约束。如果想得到更简洁的“纯内容卡”无标题simple 示例 展示了省略title、extra后只渲染 body 的形态而 no-body-debug 示例内部 debug 示例则展示了只有封面与操作区、没有 body的极端形态。结构顺序head → cover → body → actions从 Card.tsx 的渲染逻辑可以看出卡片 DOM 的固定层级div ref{ref} {...divProps} className{classString} style{mergedStyle} {head} {coverDom} {body} {actionDom} /div顺序为头部title / extra / 内嵌 Tabs→ 封面cover→ 内容区body→ 底部操作区actions。body 并非总存在源码中只有当loading为真或children非空时才渲染 body 节点childNodes.length 0这正是 no-body-debug 场景的实现依据。视觉形态封面、操作区与 hoverable 交互cover 封面与 Meta 信息组合flexible-content 示例 展示了“封面 元信息”这一最流行的信息卡形态——hoverable悬停上浮、variantborderless无边框、cover放图片、内部再配合Card.Meta放标题与描述import { Card } from antd; const { Meta } Card; Card hoverable variantborderless style{{ width: 240 }} cover{img altexample srchttps://os.alipayobjects.com/rmsportal/QBnOOoLaAfKPirc.png /} Meta titleEurope Street beat descriptionwww.instagram.com / /Cardcover为ReactNode在样式层style/index.ts 会让封面内首个子元素display: block; width: 100%并裁掉顶部直角。hoverable对应的.ant-card-hoverable:hover样式则切换box-shadow与透明边框以制造“抬起”效果。actions 底部操作区actions接收ReactNode[]渲染在卡片最底部并按数组长度自动等分宽度。源码中的ActionNode组件Card.tsx为每个操作项生成了等宽lili style{{ width: ${100 / actions.length}% }} key{key} span{action}/span /li因此 actions 项数变化时宽度会重新均分hover 操作项时文字/图标会变为主题色colorPrimary。测试用例还特别校验了非数组的 actions如数字不会被渲染见 components/card/tests/index.test.tsx 中 “should not render when actions is number”。meta 示例 将cover、actions与Card.Meta三者组合成了完整的社交/商品卡图标类操作通常直接使用ant-design/icons图标元素并补key。边框变体与尺寸管理variantoutlined / borderless从 5.24.0 起Card 引入variant属性取值为outlined默认带边框或borderless无边框、改用浅阴影。此前控制边框的bordered属性已标记废弃文档明确提示“please usevariantinstead”。border-less 示例 即为最简用法Card titleCard title variantborderless style{{ width: 300 }} pCard content/p /Card从源码看Card.tsx 通过useVariant(card, customVariant, bordered)完成了新旧属性的合并当未显式传variant而传了旧bordered时逻辑会据此推导variant类名.ant-card-bordered在variant ! borderless时挂载。同时组件会在开发模式对headStyle、bodyStyle、bordered三个废弃属性逐一输出deprecated提示指向替代项styles.header、styles.body与variant。尺寸继承size会经过useSize处理Card.tsx从而可以继承 ConfigProvider SizeContext 下发的全局尺寸。渲染时mergedSize small会追加.ant-card-small类卡片内部若带 TabstabSize会取mergedSize ! small ? large : small来与卡片尺寸匹配。内容组合栅格网格、内部卡片与标签页Card.Grid 栅格卡片grid-card 示例 展示把多个Card.Grid放进同一张卡做成宫格布局。每个 Grid 默认 25% 宽度需要自己用style控制const gridStyle { width: 25%, textAlign: center }; Card titleCard Title Card.Grid style{gridStyle}Content/Card.Grid Card.Grid hoverable{false} style{gridStyle}Content/Card.Grid ... /Card这里有两个重要的源码细节容器识别Card 会通过child.type CardGrid判断 children 中是否含 GridCard.tsx是则追加.ant-card-contain-grid类样式层据此让 body 变为flex; flex-wrap: wrap的容器并把 body 默认 padding 归零保证 Grid 无缝拼接Grid 自身样式默认width: 33.33%使用多重box-shadow画网格分隔线style/index.ts 的genCardGridStylehoverable默认值为true悬停时通过相对定位 box-shadow上浮。可显式传hoverable{false}关闭该交互上面第二个 Grid 即如此。typeinner 内部卡片inner 示例 通过typeinner在卡片内再嵌套一层带浅灰头背景colorFillAlter的子卡片常用于分组明细Card titleCard title Card typeinner titleInner Card title extra{a href#More/a} Inner Card content /Card Card style{{ marginTop: 16 }} typeinner titleInner Card title extra{a href#More/a} Inner Card content /Card /Card样式上 inner 卡片的头部背景改为colorFillAlter、标题字号回落为常规fontSize配合更紧凑的 padding 形成层级感。tabList卡片内嵌标签页tabs 示例 把 Tabs 内嵌进卡片头部支持受控与非受控两种模式。相关属性tabListTabItemType[]、activeTabKey/defaultActiveTabKey受控/非受控当前 tab、onTabChange、tabBarExtraContenttab 栏右侧扩展以及tabProps透传给底层 Tabs 组件 的额外属性。const [activeTabKey, setActiveTabKey] useState(tab1); Card titleCard title extra{a href#More/a} tabList{[ { key: tab1, tab: tab1 }, { key: tab2, tab: tab2 }, ]} activeTabKey{activeTabKey} onTabChange{setActiveTabKey} {contentList[activeTabKey]} /Card从 Card.tsx 的实现看卡片头部的 Tabs 基于rc-component/tabs的Tab类型扩展出CardTabListTypetab为已废弃字段请改用label二者会在items生成时归一化。它会根据是否传入activeTabKey自动选择activeKey或defaultActiveKey当 tab 数不为空时卡片挂上.ant-card-contain-tabs类以调整头部与 tabs 的间距。若不带标题而直接使用tabListTabs 会作为唯一头部内容出现在卡片顶端示例第二张卡。对应的测试用例components/card/tests/index.test.tsx验证了onTabChange在点击 tab 后被以对应 key 调用也验证了tabProps{{ size }}与卡片尺寸对 Tabs 尺寸的联动。加载态loading 与 Skeleton数据未就绪时loading会把内容替换成骨架屏。源码中加载态内容Card.tsx本质就是包了一层 Skeletonconst loadingBlock ( Skeleton loading active paragraph{{ rows: 4 }} title{false} {children} /Skeleton );即 4 行段落、无标题、带流光动画的骨架并透传children作为 Skeleton 的真实子内容占位。同时卡片挂.ant-card-loading类body 变为user-select: none防止误选。loading 示例 用 Switch 开关实时切换加载态卡片本身保留了 actions 与 Card.Meta 结构配合真实的头像/描述占位观看骨架效果。组合子组件Card.Grid 与 Card.Meta 的 APICard是一个复合组件在 index.tsx 中通过类型合并把子组件挂到主组件上Card.Grid CardGrid; Card.Meta CardMeta;因此你可以从import { Card } from antd后直接解构或点语法使用。两个子组件的 ref 均暴露nativeElement指向其根 div。Card.Grid属性说明类型默认值hoverable悬停时是否抬起booleantrue其余为原生HTMLAttributesHTMLDivElementclassName/style 等CardGrid.tsx。Card.Meta属性说明类型默认值Global Configavatar头像或图标ReactNode-×description描述内容ReactNode-×title标题内容ReactNode-×CardMeta.tsx 渲染为avatar加.ant-card-meta-section包裹的 title/description任一可省略。样式上标题fontSizeLG加粗并超长省略描述为次要文字色colorTextDescriptionavatar仅在有值时渲染且不与右方文字重叠。语义化结构定制Semantic DOM自 5.14.0 起Card 支持通过classNames与styles按语义结构做精细定制二者既可以是普通对象也可以是接收{ props }的函数对象RecordSemanticDOM, string | CSSProperties函数根据 props 动态返回对应记录。Card 的语义节点对应语义演示见 components/card/demo/_semantic.tsx节点如下节点作用域root整个卡片容器定位、背景、边框、圆角、阴影、内边距6.0.0 起提供header头部区域flex 布局、最小高度、内边距、文字、下边框5.14.0 起title头部左侧标题extra右上角操作区cover封面容器body内容区actions底部操作组容器在 Card.tsx 中这些类名通过useMergeSemantic与 ConfigProvider 下发的 context classNames 合并后依次拼入各语义 DOM如${prefixCls}-headmergedClassNames.header、${prefixCls}-actionsmergedClassNames.actions。Card.Meta 的语义节点对应演示见 components/card/demo/_semantic_meta.tsxroot、section标题描述包裹块、avatar、title、description且均自 6.0.0 起可用。函数式 styles 示例style-class 示例6.0.0 起展示给出了极具参考价值的两种用法其一为对象式styles直接覆盖root/title其二为函数式——根据info.props.variant动态返回不同样式同时演示了配合 CSS-in-JScreateStyles将生成的类传入classNamesconst stylesCardFn: CardProps[styles] (info) { if (info.props.variant outlined) { return { root: { borderColor: #696FC7, boxShadow: 0 2px 8px #A7AAE1, borderRadius: 8 }, extra: { color: #696FC7 }, title: { fontSize: 16, fontWeight: 500, color: #A7AAE1 }, }; } };需要强调Card 与 Card.Meta 的全局配置Global Config一列均为×语义上未接入 config-provider 的 components 级配置通道但依旧可以组合 ConfigProvider 的 theme 令牌实现统一主题见下文。组件 API 参考总表除下表外Card 还透传原生HTMLAttributesHTMLDivElement如onClick、id、style、className其中title被组件接管。通用属性遵循 Common props。PropertyDescriptionTypeDefaultVersionGlobal Configactions操作列表展示于卡片底部ArrayReactNode-×activeTabKey当前 TabPane 的 key受控string-×bordered是否渲染边框请改用variantbooleantrue×bodyStylebody 样式请改用styles.bodyCSSProperties--×variant卡片变体outlined|borderlessoutlined5.24.05.24.0classNames为组件内各语义结构自定义类名支持对象或函数RecordSemanticDOM, string | (info: { props }) RecordSemanticDOM, string-5.14.0cover卡片封面ReactNode-×defaultActiveTabKey未设置activeTabKey时的初始 tab keystring第一个 tab 的 key×extra卡片右上角渲染的内容ReactNode-×hoverable鼠标悬停时卡片浮起booleanfalse×headStyle头部样式请改用styles.headerCSSProperties--×loading内容获取期间展示加载指示器booleanfalse×size卡片尺寸medium|smallmedium×tabBarExtraContenttab 栏额外内容ReactNode-×tabListTabPane 头列表TabItemType[]-×tabProps透传 Tabs 的属性TabsProps--×title卡片标题ReactNode-×type卡片风格类型可设inner或不设string-×styles为各语义结构自定义内联样式支持对象或函数RecordSemanticDOM, CSSProperties | (info: { props }) RecordSemanticDOM, CSSProperties-5.14.0onTabChangetab 切换回调(key) void-×上表沿用仓库文档的语义×表示该属性不支持通过 ConfigProvider 的 component config 全局下发。同一份中英文 API 说明可在 index.zh-CN.md 对照查看。布局场景示例一览官方 示例目录 覆盖了几乎所有常见布局可作为“按需取用”的地图示例文件解决的问题Basic cardbasic.tsx标题 右上角 extramedium/small 双尺寸No borderborder-less.tsxvariantborderless无边框Simple cardsimple.tsx只有内容体、无标题Customized contentflexible-content.tsxcover hoverable MetaCard in columnin-column.tsx与 Row/Col 栅格配合的等宽多卡Loading cardloading.tsxSkeleton 骨架加载态Grid cardgrid-card.tsxCard.Grid 宫格布局Inner cardinner.tsxtypeinner 嵌套分组卡With tabstabs.tsxtabList 受控切换 tabPropsMeta / actionmeta.tsxcover actions Meta 完整信息卡Custom stylingstyle-class.tsxclassNames / styles 语义化定制此外目录内还包含内部使用的调试与演示配套文件如no-body-debug.tsx、button-alignment-debug.tsx、component-token.tsx它们同样可以在文档站点中直接运行预览。设计令牌Design Token定制Card 的所有样式均通过 cssinjs 的genStyleHooks(Card, ...)生成style/index.ts这意味着你可以像 component-token 示例 那样在ConfigProvider中针对components.Card做全局主题化ConfigProvider theme{{ components: { Card: { headerBg: #e6f4ff, headerPadding: 18, bodyPadding: 26, headerFontSize: 20, headerHeight: 60, actionsBg: #e6f4ff, extraColor: rgba(0,0,0,0.25), tabsMarginBottom: 0, // 小号尺寸对应令牌 bodyPaddingSM: 22, headerPaddingSM: 20, headerFontSizeSM: 20, headerHeightSM: 60, }, }, }} {/* Card 树 */} /ConfigProvider从组件令牌接口ComponentToken定义于 style/index.ts与prepareComponentToken的默认值实现可得下表Token含义默认值取自源码 prepareComponentTokenheaderBg头部背景色transparentheaderFontSize头部文字大小fontSizeLG全局 token 派生headerFontSizeSM小号卡头部文字大小fontSizeheaderHeight头部高度fontSizeLG * lineHeightLG padding * 2headerHeightSM小号卡头部高度fontSize * lineHeight paddingXS * 2bodyPaddingbody 内边距bodyPadding ?? paddingLGbodyPaddingSM小号卡 body 内边距12固定值headerPadding头部内边距headerPadding ?? paddingLGheaderPaddingSM小号卡头部内边距12actionsBg操作区背景色colorBgContaineractionsLiMargin操作区每项外间距${paddingSM}px 0tabsMarginBottom内嵌 Tabs 下间距-padding - lineWidthextraColorextra 区文字颜色colorText另外还有若干由全局令牌派生的内部 token不直接对外暴露于组件令牌表cardShadow取boxShadowCard作用于 hoverable 悬停阴影、cardHeadPaddingpadding作用于含 tabs 时的头部内边距、cardPaddingBasepaddingLGGrid 单元的 padding 基准、cardActionsIconSizefontSize操作图标尺寸。边框、圆角等则来自 Card 样式对全局colorBorderSecondary、borderRadiusLG、lineWidth等的引用与整套主题体系保持一致。从源码看实现要点小结将文档与 Card.tsx 对照可以归纳出几个值得注意的实现事实复合组件挂载index.tsx 用接口合并把Grid、Meta作为静态属性挂到 Card 上同时导出各子组件的 Props/Ref 类型使用上与Card.Grid/Card.Meta点语法一致Grid 识别与专用布局Card 依据child.type CardGrid识别网格内容并切换.ant-card-contain-grid布局Grid 之间用 box-shadow 拼线加载即 Skeletonloading直接以 Skeleton 包裹 children 渲染配合.ant-card-loading的user-select: noneTabs 深度集成tab 头部复用rc-component/tabs自动处理受控/非受控 activeKey并随卡片尺寸联动 Tabs 尺寸弃用治理bordered、headStyle、bodyStyle均已在非生产环境输出 deprecated 警告明确指向variant与styles.*sizedefault亦提示改用medium语义化与全局上下文classNames/styles通过useMergeSemantic合并 ConfigProvider context 与本地值最终落到各语义 DOM 节点上。这些行为均有对应的单元测试守护例如 components/card/tests/index.test.tsx 中的 tab 切换、tab 尺寸继承、loading padding 与 actions 非法值过滤等用例。整体上Card 是一个“结构组合 语义定制 令牌主题”三层能力都相当完备的容器组件配合 docs/react/common-props.en-US.md 与 ConfigProvider 组件配置足以应对从纯展示到可交互聚合页面的绝大多数内容容器需求。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考