Ant Design Descriptions 组件实战指南用 items 声明式 API 构建企业级详情页只读信息展示【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-designDescriptions 是 Ant Design 中用于「成组展示多条只读字段」的经典信息展示组件最常见的落地场景是订单详情、用户信息、商品规格等详情页Details Page。本文以官方文档 components/descriptions/index.en-US.md 为核心骨架结合仓库内组件源码与真实 Demo系统讲解 Descriptions 的两种数据声明方式、全部 API 参数、响应式列数/跨度控制、样式定制优先级以及 Design Token 定制方法读完即可在项目中直接落地一套适配多端屏幕的详情信息面板。何时使用 Descriptions官方文档给出的定位非常明确Commonly displayed on the details page通常展示在详情页。当页面需要将一组只读字段如用户名、电话、地址以「标签 内容」的表格形式整齐排列时Descriptions 是比手工拼 table 更语义化、更省心的选择。它与 Form 的核心区别在于Descriptions 不承载交互输入纯粹用于信息陈列。两种数据声明方式items数组与 JSX 子组件自 5.8.0 起Descriptions 推荐使用items数组声明数据而基于Descriptions.Item子组件的旧写法在 5.8.0 之后被标记为 deprecated。官方文档给出了两种写法的对照// 推荐写法works when 5.8.0 ✅ const items: DescriptionsProps[items] [ { key: 1, label: UserName, children: pZhou Maomao/p }, { key: 2, label: Telephone, children: p1810000000/p }, { key: 3, label: Live, children: pHangzhou, Zhejiang/p }, { key: 4, label: Remark, children: pempty/p }, { key: 5, label: Address, children: pNo. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China/p, }, ]; Descriptions titleUser Info items{items} /; // 旧写法works when 5.8.05.8.0 起不推荐 ‍♀️ Descriptions titleUser Info Descriptions.Item labelUserNameZhou Maomao/Descriptions.Item Descriptions.Item labelTelephone1810000000/Descriptions.Item Descriptions.Item labelLiveHangzhou, Zhejiang/Descriptions.Item Descriptions.Item labelRemarkempty/Descriptions.Item Descriptions.Item labelAddress No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China /Descriptions.Item /Descriptions;从源码看两种写法最终会汇合到同一条数据管线useItems钩子components/descriptions/hooks/useItems.ts中优先消费items属性若未传入则调用transChildren2Items把Descriptions.Item子节点的props与key转换为等价的对象数组const mergedItems React.useMemoDescriptionsItemType[]( () // Take items first or convert children into items items || transChildren2Items(children), [items, children], );因此两者渲染结果完全一致items只是更利于与后端数据、状态管理直接对接。Descriptions API 参数详解官方文档的完整参数表如下均可在源码 components/descriptions/index.tsx#L31-L51 的DescriptionsProps中找到一一对应的类型定义属性说明类型默认值版本bordered是否显示边框booleanfalse-colon修改 Descriptions.Item 默认的colon属性值控制标签后冒号是否显示booleantrue-column一行内DescriptionItems的数量可为数字或对象如{ xs: 8, sm: 16, md: 24 }number | RecordBreakpoint, number3-contentStyle自定义内容样式CSSProperties-4.10.0extra描述列表的操作区域位于右上角ReactNode-4.5.0items描述列表项的内容DescriptionsItem[]-5.8.0labelStyle自定义标签样式CSSProperties-4.10.0layout定义描述布局horizontal|verticalhorizontal-size设置列表尺寸可为middle、small或不填default|middle|small--title描述列表的标题位于顶部ReactNode--除表格所列属性外DescriptionsProps还声明了prefixCls、className、rootClassName、style、id等通用属性并支持透传 ConfigProvider 提供的directionRTL 场景下会自动追加-rtl类名见 index.tsx#L113。值得注意的细节size类型为middle | small | default若当前组件处于 ConfigProvider 的 size 上下文中且未显式传入会通过useSize钩子继承全局尺寸见 index.tsx#L93。column支持数字或断点对象两种形式。源码中通过matchScreen(screens, { ...DEFAULT_COLUMN_MAP, ...column }) ?? 3合并计算最终列数index.tsx#L77-L88未命中任何断点时兜底为 3 列。官方文档表格中注明 column 的断点对象形式「仅在bordered{true}时生效」。labelStyle/contentStyle4.10.0 起通过DescriptionsContext下发给所有 Item 作为「根级」样式具体优先级见后文「样式定制与覆盖优先级」。DescriptionItem API 与 span 列宽控制items数组中的每一项对应以下字段类型定义见 components/descriptions/Item.ts 与 index.tsx#L23-L29属性说明类型默认值版本contentStyle自定义内容样式CSSProperties-4.9.0label内容的描述ReactNode--labelStyle自定义标签样式CSSProperties-4.9.0span包含的列数number | Screens1screens: 5.9.0关于 span官方文档有一段重要补充说明The number of span Description.Item. Span{2} takes up the width of two DescriptionItems. When bothstyleandlabelStyle(orcontentStyle) configured, both of them will work. And next one will overwrite first when conflict.即span{2}表示该条目占据两个普通条目的宽度当style与labelStyle或contentStyle同时配置时两者都会生效发生冲突时后者覆盖前者。这一点与源码 components/descriptions/Cell.tsx#L48-L49 的展开顺序完全一致labelStyle{{ ...rootLabelStyle, ...labelStyle }}、contentStyle{{ ...rootContentStyle, ...contentStyle }}—— Item 级样式始终覆盖根级Descriptions 级样式。span自 5.9.0 起还支持响应式对象screens: 5.9.0例如span{{ xl: 2, xxl: 2 }}会在useItems中通过matchScreen依据当前屏幕断点解析为具体数字useItems.ts#L24-L31。布局与视觉定制bordered / layout / size / colon / title / extra边框与尺寸bordered{true}开启表格边框。源码中渲染分支发生变化——bordered 模式下每行使用thlabeltdcontent两个独立单元格无边框模式下 label 与 content 合并在同一个td内通过 flex 布局排布见 components/descriptions/Row.tsx#L128-L137。sizemiddle | small控制单元格内边距。从 components/descriptions/style/index.ts 的样式生成逻辑看middle 使用paddingSM、small 使用paddingXS实现紧凑型详情面板。布局方向layouthorizontal默认标签与内容同行排列。layoutvertical标签与内容上下堆叠。源码中 vertical 模式下每个逻辑行会被拆成两行tr渲染第一行只渲染 labelth第二行只渲染 contenttd见 Row.tsx#L105-L126。// 来自 demo/vertical.tsx地址占两列宽度其余条目单列 const items: DescriptionsProps[items] [ { key: 1, label: UserName, children: Zhou Maomao }, { key: 2, label: Telephone, children: 1810000000 }, { key: 3, label: Live, children: Hangzhou, Zhejiang }, { key: 4, label: Address, span: 2, children: No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China }, { key: 5, label: Remark, children: empty }, ]; Descriptions titleUser Info layoutvertical items{items} /;冒号、标题与操作区colon{false}隐藏标签后的冒号。样式层通过在 label 元素上追加-item-no-colon类并把::after伪元素内容置空实现style/index.ts#L182-L184。title面板顶部标题样式上使用fontWeightStrong加粗、fontSizeLG放大style/index.ts#L131-L138。extra右上角操作区如「编辑」「更多」按钮通过marginInlineStart: auto推到标题右侧style/index.ts#L139-L143。Descriptions titleUser Info extra{Button sizesmall typelinkEdit/Button} items{items} /响应式列数与响应式 spanDescriptions 内置了一套断点默认列数映射定义在 components/descriptions/constant.tsconst DEFAULT_COLUMN_MAP: RecordBreakpoint, number { xxl: 3, xl: 3, lg: 3, md: 3, sm: 2, xs: 1, };即默认在手机屏xs上每行 1 列、平板sm2 列、桌面端md 及以上3 列。开发者可通过column传入断点对象覆盖任意断点的列数配合useBreakpointgrid/hooks/useBreakpoint实时响应窗口变化。官方 responsive Demo 给出了完整的多断点实践column{{ xs: 1, sm: 2, md: 3, lg: 3, xl: 4, xxl: 4 }}让宽屏下每行容纳 4 列同时条目级span也可以按断点自适应例如「Config Info」「Hardware Info」两项在窄屏占 1 列、中等屏占 2~3 列、超宽屏占 2 列{ label: Config Info, span: { xs: 1, sm: 2, md: 3, lg: 3, xl: 2, xxl: 2 }, children: ( Data disk type: MongoDB br / Database version: 3.4 br / Package: dds.mongo.mid / ), }样式定制与覆盖优先级Descriptions 级labelStyle/contentStyle4.10.0作为根级样式通过DescriptionsContext下发DescriptionsContext.ts。Item 级labelStyle/contentStyle4.9.0作用在单个条目上。单元格级style作用在整格td/th上。合并顺序在 Cell.tsx#L48-L49 中体现为{ ...root, ...item }因此条目级覆盖根级文档同时强调style与labelStyle/contentStyle并行生效、冲突时后者labelStyle/contentStyle覆盖前者。仓库中的 style Demo 与 padding Demo 展示了具体效果。源码级原理剖析从items到表格行的渲染链路理解 Descriptions 的底层渲染流程有助于排查 span 越界、列数不符等布局问题。整条链路可概括为四步列数解析index.tsx#L77-L88mergedColumn合并默认断点映射与用户column得到当前屏幕下的实际列数。条目归一useItems.ts把items或 children 统一成内部条目数组并将响应式span对象解析为数字。行计算useRow.tsgetCalcRows按列数把条目切分为多个行数组逐项累计剩余列数rowRestCol当某条span超出本行剩余列数时会将该条目的 span 自动收缩为剩余列数并标记exceed在开发模式下通过devUseWarning输出告警Sum of column span in a line not match column of Descriptions.。这一机制保证任何 span 配置都不会破坏表格结构。单元格渲染Row.tsx Cell.tsx非 bordered 模式每个条目渲染为单个td内部用 flex 容器排列 label 与 content并通过colSpan{span}扩展宽度bordered 模式拆分为thtd两个单元格content 的colSpan为span * 2 - 1vertical 模式再进一步拆成 label 行与 content 行两行tr。最终 DOM 结构稳定为div.descriptions div.descriptions-header div.descriptions-view table tbody tr.descriptions-row官方测试用例components/descriptions/tests/index.test.tsx、hooks.test.tsx对上述行计算与响应式逻辑均有覆盖验证。Design Token 定制Descriptions 支持通过主题 Token 统一定制视觉风格组件的ComponentToken定义于 components/descriptions/style/index.ts#L9-L56官方文档以ComponentTokenTable componentDescriptions /动态渲染完整 Token 表格源码中可确认的 Token 包括Token说明默认值由prepareComponentToken派生labelBg标签背景色bordered 模式colorFillAltertitleColor标题文字颜色colorTexttitleMarginBottom标题下间距fontSizeSM * lineHeightSMitemPaddingBottom子项下内边距paddingitemPaddingEnd子项结束右侧内边距paddingcolonMarginRight冒号右间距marginXScolonMarginLeft冒号左间距marginXXS / 2contentColor内容文字颜色colorTextextraColor额外区域文字颜色colorText例如在 ConfigProvider 中定制标签背景色与标题颜色ConfigProvider theme{{ components: { Descriptions: { labelBg: #f5f5f5, titleColor: #1677ff, contentColor: rgba(0, 0, 0, 0.88), }, }, }} Descriptions titleUser Info bordered items{items} / /ConfigProvider典型场景速查仓库 demo 目录 提供了覆盖各场景的完整可运行示例可对照查阅basic.tsx最基础的items用法搭配title展示用户信息border.tsxbordered表格样式 多条目span组合典型订单/账单详情responsive.tsx响应式column与响应式span结合的多端适配方案vertical.tsxlayoutvertical上下堆叠布局size.tsx、padding.tsx尺寸与内边距调节style.tsxlabelStyle/contentStyle 自定义jsx.tsx旧版Descriptions.ItemJSX 写法对照component-token.tsxComponent Token 定制效果。小结Descriptions 的核心价值在于用极少的配置把「一组只读字段」编排成结构清晰、天然响应式的信息表格。掌握要点即可应对绝大多数详情页需求优先使用items数组声明数据5.8.0用数字或断点对象控制column与条目span实现多端自适应借助labelStyle/contentStyle与 Design Token 完成视觉定制理解useRow的列数兜底与开发期告警可快速定位布局异常。如需更完整的参数说明可直接查阅官方文档 components/descriptions/index.en-US.md 及中文版 index.zh-CN.md。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考