Ant Design Card 卡片组件完全指南API 详解、组合模式与主题定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designCard卡片是 Ant Design 数据展示组件中最基础也最通用的容器之一用于承载文字、列表、图片、段落等内容常见于后台概览页、详情页与信息聚合场景。本文以 components/card/index.zh-CN.md 为骨架结合仓库内 Card.tsx、Grid.tsx、Meta.tsx 等源码与 demo 示例完整讲解 Card 的全部 API、Card.Grid/Card.Meta组合用法、页签与加载态等进阶场景以及基于 Design Token 的主题定制方案帮助你在实战中快速构建规范、可维护的卡片布局。何时使用Card 的适用场景Card 是“最基础的卡片容器”可承载文字、列表、图片、段落常用于后台概览页面。它适合把单一主题的相关内容组织在一起——例如一个用户信息卡片、一条商品条目、一张统计概览块。与 Table、List 等数据密集型组件不同Card 更强调对内容的自由编排你可以通过title、extra、cover、actions、Card.Meta等插槽组合出任意形态的信息块。一个最典型的骨架如下Card title卡片标题卡片内容/CardCard 支持所有通用属性className、style、id、事件等通用属性说明可参考 docs/react/common-props.zh-CN.md。快速上手五种最常用的基础形态典型卡片与尺寸控制components/card/demo/basic.tsx 展示了最常用的写法title设置标题、extra在右上角放置操作区如 More 链接、size切换default与small两种尺寸import { Card, Space } from antd; const App () ( Space directionvertical size{16} Card titleDefault size card extra{a href#More/a} style{{ width: 300 }} pCard content/p pCard content/p /Card Card sizesmall titleSmall size card extra{a href#More/a} style{{ width: 300 }} pCard content/p /Card /Space );从源码看Card.tsx组件会依据size生成ant-card-default/ant-card-small类名small模式会应用更紧凑的头部高度与内边距见 style/index.ts 的genCardSizeStyle其中小号卡片 body 内边距固定为 12px。无边框与简洁卡片无边框components/card/demo/border-less.tsx设置bordered{false}后卡片不再渲染边框而改用boxShadowTertiary阴影区分层级style/index.ts。简洁卡片components/card/demo/simple.tsx只包含内容、不设置title的纯内容卡片适合承载一段说明文字。悬停浮起效果设置hoverable后鼠标移过卡片时会产生浮起阴影加深、边框透明的效果style/index.tsCard hoverable style{{ width: 240 }} Card.Meta titleEurope Street beat descriptionwww.instagram.com / /CardCard 核心 API 详解下表完整列出Card组件的全部属性对应 components/card/index.zh-CN.md 的 API 表参数说明类型默认值actions卡片操作组位置在卡片底部ArrayReactNode-activeTabKey当前激活页签的 keystring-bordered是否有边框booleantruecover卡片封面ReactNode-defaultActiveTabKey初始化选中页签的 key如果没有设置 activeTabKeystring第一个页签的 keyextra卡片右上角的操作区域ReactNode-hoverable鼠标移过时可浮起booleanfalseloading当卡片内容还在加载中时可以用 loading 展示一个占位booleanfalsesizecard 的尺寸default|smalldefaulttabBarExtraContenttab bar 上额外的元素ReactNode-tabList页签标题列表TabItemType[]-tabPropsTabs 组件的属性透传--title卡片标题ReactNode-type卡片类型可设置为inner或不设置string-classNames配置卡片内置模块的 classNameRecordSemanticDOM, string-5.14.0 起styles配置卡片内置模块的 styleRecordSemanticDOM, string-5.14.0 起onTabChange页签切换的回调(key) void-文档中tabList与tabProps的类型引用 Tabs 组件详见 components/tabs/index.zh-CN.md。关键参数的源码级说明actions底部操作组在 Card.tsx 中ActionNode将每个操作渲染为li并设置width: ${100 / actions.length}%即所有操作等宽均分卡片底部操作项之间以边框分隔hover 时图标与文字变为主题色style/index.ts。cover封面封面区域会整体铺满卡片顶部并做圆角处理有边框时通过负 margin 让封面与边框贴合style/index.ts。typeinner内部卡片用于在卡片内再嵌套一层卡片常用于“分组内容”场景。内部卡片头部使用colorFillAlter背景色style/index.ts。headStyle / bodyStyle 已废弃源码在开发模式下会给出deprecation警告提示改用styles.header与styles.bodyCard.tsx建议新代码直接使用语义化 styles。组合子组件Card.Grid 与 Card.MetaCard通过 components/card/index.tsx 将Grid与Meta挂载为静态属性因此可以写作Card.Grid与Card.Meta。Card.Grid 网格型内嵌卡片Card.Grid用于在卡片内部切分网格非常适合仪表盘、概览统计等场景示例见 components/card/demo/grid-card.tsx参数说明类型默认值className网格容器类名string-hoverable鼠标移过时可浮起booleantruestyle定义网格容器类名的样式CSSProperties-默认情况下网格宽度为33.33%即一行三列可通过style覆盖宽度实现 4 列乃至任意布局style/index.tsconst gridStyle: React.CSSProperties { 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 会通过React.Children.forEach检测 children 中是否包含Grid元素并据此添加ant-card-contain-grid类名使 body 切换为display: flex; flex-wrap: wrap的流式布局Card.tsx、style/index.ts。Card.Meta 内容元信息Card.Meta用于快速组织“头像 标题 描述”的经典信息结构示例见 components/card/demo/meta.tsx参数说明类型默认值avatar头像/图标ReactNode-className容器类名string-description描述内容ReactNode-style定义容器类名的样式CSSProperties-title标题内容ReactNode-const { Meta } Card; Card style{{ width: 300 }} cover{img altexample srchttps://gw.alipayobjects.com/zos/rmsportal/JiqGstEfoWAOHiTxclqi.png /} actions{[SettingOutlined keysetting /, EditOutlined keyedit /, EllipsisOutlined keyellipsis /]} Meta avatar{Avatar src... /} titleCard title descriptionThis is the description / /Card从 Meta.tsx 的源码可见其 DOM 结构为.ant-card-meta下分别渲染-meta-avatar、-meta-title、-meta-description与包裹它们的-meta-detail标题使用fontWeightStrong加粗与fontSizeLG大号字号style/index.ts。进阶场景页签卡片与加载占位带页签的卡片tabList当信息量较多、需要在卡片头部切换视图时可直接通过tabList让 Card 内置 Tabs示例见 components/card/demo/tabs.tsxconst tabList [ { key: tab1, tab: tab1 }, { key: tab2, tab: tab2 }, ]; const [activeTabKey1, setActiveTabKey1] useState(tab1); Card titleCard title extra{a href#More/a} tabList{tabList} activeTabKey{activeTabKey1} onTabChange{setActiveTabKey1} {contentList[activeTabKey1]} /Card关键机制说明受控与非受控传入activeTabKey时为受控模式此时由onTabChange回调更新状态不传时使用defaultActiveTabKey默认取第一个页签的 key。源码会据此决定把哪个 key 写入activeKey还是defaultActiveKeyCard.tsx。tab已废弃CardTabListType中tab字段标记为 deprecated建议使用labelCard.tsx源码也会自动将旧写法tab映射为label。tabBarExtraContent与tabProps前者在 tab bar 尾部追加额外元素如 More 链接后者透传 Tabs 属性例如tabProps{{ size: middle }}可调整页签尺寸。内部 Tabs 的尺寸会跟随 Card 的sizedefault映射为largesmall映射为smallCard.tsx。预加载的卡片loading数据尚未返回时设置loading即可显示骨架屏占位。源码将 children 包裹在Skeleton loading active paragraph{{ rows: 4 }} title{false}中Card.tsx即渲染 4 行段落骨架并保留原有卡片结构示例见 components/card/demo/loading.tsxCard loading{loading} actions{actions} style{{ minWidth: 300 }} Card.Meta avatar{Avatar src... /} titleCard title description... / /Card加载态下 body 会设置user-select: none避免加载过程中误选中内容style/index.ts。语义化定制styles 与 classNames5.14.0自 5.14.0 起Card 支持按内置模块精准定制样式。classNames用于追加类名、styles用于注入内联样式二者支持的模块一致名称说明版本header设置卡片头部区域5.14.0body设置卡片内容区域5.14.0extra设置卡片右上角的操作区域5.14.0title设置卡片标题5.14.0actions设置卡片底部操作组5.14.0cover设置标题封面5.14.0Card classNames{{ header: my-header, body: my-body }} styles{{ header: { background: #fafafa }, body: { padding: 24 } }} /源码实现上moduleClass会合并ConfigProvider的card.classNames与组件自身classNamesmoduleStyle则先合并全局card.styles再覆盖组件级stylesCard.tsx因此在 ConfigProvider 层面统一配置、在单卡片上做局部微调是完全支持的。主题定制Card Design TokenCard 通过 style/index.ts 定义了 9 个可定制 Token可直接在ConfigProvider的theme.components.Card中覆盖示例见 components/card/demo/component-token.tsxToken说明默认值推导headerBg卡片头部背景色transparentheaderFontSize卡片头部文字大小token.fontSizeLGheaderFontSizeSM小号卡片头部文字大小token.fontSizeheaderHeight卡片头部高度fontSizeLG * lineHeightLG padding * 2headerHeightSM小号卡片头部高度fontSize * lineHeight paddingXS * 2actionsBg操作区背景色token.colorBgContaineractionsLiMargin操作区每一项的外间距paddingSM 0tabsMarginBottom内置标签页组件下间距-(padding lineWidth)extraColor额外区文字颜色token.colorText完整默认值推导见 style/index.ts 的prepareComponentToken。实际定制示例ConfigProvider theme{{ components: { Card: { headerBg: #e6f4ff, headerFontSize: 20, headerHeight: 60, headerHeightSM: 60, actionsBg: #e6f4ff, actionsLiMargin: 2px 0, tabsMarginBottom: 0, extraColor: rgba(0,0,0,0.25), }, }, }} Card titleCard title extraMoreCard content/Card /ConfigProvider除了组件级 TokenCard 还大量复用全局主题 Token边框使用colorBorderSecondary、头部标题使用colorTextHeading、正文使用colorBgContainer、悬停阴影使用boxShadowCard、圆角使用borderRadiusLGstyle/index.ts这意味着全局换肤时卡片会自动跟随主题保持一致。小结Card 组件以“头部title/extra/tabs 封面cover 内容children 操作组actions”的四段式结构覆盖了绝大多数信息容器需求配合Card.Grid实现网格布局、Card.Meta快速组装元信息、loading骨架屏与内置 Tabs 支撑后台业务的高频场景。若需要进一步自定义优先使用 5.14.0 引入的styles/classNames语义化属性再考虑通过 Design Token 在 ConfigProvider 层统一调整主题。建议结合以下源码文件深入阅读组件实现components/card/Card.tsx、components/card/Grid.tsx、components/card/Meta.tsx、components/card/index.tsx样式与 Tokencomponents/card/style/index.ts演示示例components/card/demo含 basic、border-less、simple、grid-card、inner、tabs、loading、meta、flexible-content、component-token 等官方 API 文档components/card/index.zh-CN.md英文版见 components/card/index.en-US.md【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考