Ant Design Descriptions 描述列表组件完全指南从 items 配置到响应式布局与源码实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文以 Ant DesignantdDescriptions描述列表组件为核心系统讲解如何在详情页中高效展示只读字段组合。你将掌握items配置式写法与Descriptions.Item子组件写法的差异与取舍、column/span的响应式规则、bordered/size/layout等全部 API 参数并通过阅读 组件入口源码、行布局算法 与 单元格渲染理解其底层实现原理最终能独立构建出带边框、垂直、响应式的专业详情页。何时使用 DescriptionsDescriptions组件常用于详情页的信息展示用于在页面上以「标签 内容」的规整列表形式呈现一组只读字段例如订单详情、用户资料、云资源实例配置等场景。与Table相比它不承载复杂交互专注静态信息的视觉组织与Card 手工排版相比它内置了列数控制、边框、标签对齐与响应式能力开箱即用。从 组件实现 可以看出Descriptions 最终渲染为一个table结构prefixCls-view包裹将数据以行、列的方式排布语义上天然适合「字段-值」型只读信息的展示。两种数据写法items 配置式与 Item 子组件式items 配置式 5.8.0 推荐自 antd 5.8.0 起官方推荐使用items配置数组写法数据与渲染分离结构更清晰// 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} /;从源码看DescriptionsItemType 类型允许每个 item 携带key、label、children、span数字或响应式对象、labelStyle、contentStyle、className、style等字段组件内部 通过useItems(screens, items, children)优先消费items。Item 子组件式 5.8.0 兼容写法对于 5.8.0 以下版本或偏好 JSX 声明式写法的场景可以使用Descriptions.Item子组件// 5.8.0 可用5.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;有趣的是Item.ts 中的DescriptionsItem本身并不渲染任何 DOM它只是把children原样返回({ children }) children真正的数据采集发生在 useItems.ts 中通过rc-util的toArray遍历子节点再{ ...node?.props, key: node.key }把每个Descriptions.Item的 props 拍平成与items数组同构的数据。因此两种写法在渲染层完全等价items只是把这种「运行时采集」提前到了业务代码中。Descriptions 完整 API 参数详解Descriptions 属性总览以下表格完整覆盖 index.zh-CN.md 中定义的 API并补充了源码中的行为细节。参数说明类型默认值版本bordered是否展示边框booleanfalsecolon配置Descriptions.Item的colon的默认值。表示是否显示 label 后面的冒号booleantruecolumn一行的DescriptionItems数量可以写成像素值或支持响应式的对象写法{ xs: 8, sm: 16, md: 24}number |RecordBreakpoint, number3contentStyle自定义内容样式CSSProperties-4.10.0extra描述列表的操作区域显示在右上方ReactNode-4.5.0items描述列表项内容DescriptionsItem[]-5.8.0labelStyle自定义标签样式CSSProperties-4.10.0layout描述布局horizontal|verticalhorizontalsize设置列表的大小。可以设置为middle、small或不填只有设置bordered{true}生效default|middle|small-title描述列表的标题显示在最顶部ReactNode-DescriptionItem 属性参数说明类型默认值版本contentStyle自定义内容样式CSSProperties-4.9.0label内容的描述ReactNode-labelStyle自定义标签样式CSSProperties-4.9.0span包含列的数量number |Screens1screens: 5.9.0span 语义说明span是Description.Item的数量span{2}会占用两个DescriptionItem的宽度。当同时配置style和labelStyle或contentStyle时两者会同时作用样式冲突时后者会覆盖前者。关键参数源码级解读column 的响应式解析组件实现 中通过matchScreen(screens, { ...DEFAULT_COLUMN_MAP, ...column })合并用户配置与默认映射未命中任何断点时兜底为3。constant.ts 定义了各断点默认列数xxl: 3、xl: 3、lg: 3、md: 3、sm: 2、xs: 1——即默认情况下小屏手机每行 1 项平板每行 2 项桌面及以上每行 3 项。bordered 的渲染分支bordered 模式下每个 item 是独立的一个th/td单元格非 bordered 模式下 label 与 content 被合并进同一个td的item-container容器内用两个span展示见 Cell.tsx。size 的生效条件从源码看mergedSize通过useSize获取继承 ConfigProvider 的组件尺寸并仅在非default时追加${prefixCls}-${mergedSize}类名。文档明确说明size只有在设置bordered{true}时才生效因此无边框模式下设置 size 不会产生视觉差异。title 与 extra 的布局组件实现 中当title或extra存在时渲染descriptions-header头部分区title居左、extra居右常用于放置「编辑」「详情」等操作按钮。实战示例从基本用法到复杂场景基本用法最简用法直接传入title与items参见 demo/basic.tsximport React from react; import { Descriptions } from antd; import type { DescriptionsProps } from antd; 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: Remark, children: empty }, { key: 5, label: Address, children: No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China }, ]; const App: React.FC () Descriptions titleUser Info items{items} /; export default App;带边框的 Descriptions设置bordered后label 与 content 拥有独立单元格和边框适合需要强调字段归属的信息密度较高的场景完整示例见 demo/border.tsx。注意其中span的用法Usage Time设置span: 2、Status设置span: 3实现跨列占位const items: DescriptionsProps[items] [ { key: 5, label: Usage Time, children: 2019-04-24 18:00:00, span: 2 }, { key: 6, label: Status, children: Badge statusprocessing textRunning /, span: 3 }, // ... ]; const App: React.FC () Descriptions titleUser Info bordered items{items} /;垂直布局vertical设置layoutvertical后label 在上、content 在下。从 Row.tsx 可以看出垂直模式将一行拆成两个trlabel 行th与 content 行td典型示例如下完整见 demo/vertical.tsxconst items: DescriptionsProps[items] [ { key: 1, label: UserName, children: Zhou Maomao }, { key: 4, label: Address, span: 2, children: No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China }, // ... ]; const App: React.FC () Descriptions titleUser Info layoutvertical items{items} /;垂直布局同样可以叠加bordered参见 demo/vertical-border.tsx并在Responsive案例中与响应式 column 组合使用。响应式列数与响应式 spancolumn与span都支持断点对象写法。column控制整表每行列数span控制单个 item 占用的列数二者可同时使用。以下示例来自 demo/responsive.tsxcolumn在手机上 1 列、桌面 4 列同时部分 item 的span按断点变化const items: DescriptionsProps[items] [ { label: Product, children: Cloud Database }, { label: Billing, children: Prepaid }, { label: Time, children: 18:00:00 }, { label: Amount, children: $80.00 }, { label: Discount, span: { xl: 2, xxl: 2 }, children: $20.00 }, { label: Official, span: { xl: 2, xxl: 2 }, children: $60.00 }, { 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 / ), }, // ... ]; const App: React.FC () ( Descriptions titleResponsive Descriptions bordered column{{ xs: 1, sm: 2, md: 3, lg: 3, xl: 4, xxl: 4 }} items{items} / );响应式span的解析同样发生在 useItems.ts当span是对象时通过matchScreen(screens, span)依据当前视口断点换算为实际列数当span为数字时直接透传。注意span的响应式对象写法自 5.9.0 起支持。自定义尺寸设置sizesmall或sizemiddle可调整表格内边距与字号仅在bordered下生效参见 demo/size.tsx。若不传size会继承 ConfigProvider 全局配置的组件尺寸。自定义 label / content 样式labelStyle与contentStyle既可以在Descriptions上统一设置作用所有 item见 demo/style.tsx也可以在单个 item 上单独覆盖。合并逻辑位于 Cell.tsx 与 Row.tsx渲染时通过{ ...rootLabelStyle, ...labelStyle }逐级合并item 级样式优先级更高此外二者经 DescriptionsContext 从顶层向单元格传递这也是组件内共享样式配置的实现通道。复杂文本与间距控制复杂内容如多行文本、换行、富节点在 bordered 模式下表现更规整相关调试示例见 demo/text.tsx 与 demo/padding.tsx。children接受任意ReactNode可以嵌入Badge、Tag、br /等组合元素如上面 border 示例中的Badge statusprocessing textRunning /。底层实现原理从数据到表格的完整流水线Descriptions 的渲染流程可以概括为「列数合并 → 数据归一化 → 行布局 → 单元格渲染」四个阶段对应源码中的四个关键模块列数合并column组件实现 通过useMemo合并DEFAULT_COLUMN_MAP与用户column配置得到当前断点下的mergedColumnuseBreakpoint负责订阅视口断点变化这也是响应式能力的来源。数据归一化items/childrenuseItems.ts 优先取items否则将children中的Descriptions.Item拍平为同一数据结构再统一完成响应式span解析输出InternalDescriptionsItemType[]。行布局算法useRowuseRow.ts 按mergedColumn把扁平数组切分为二维行数组逐个 item 累加span当前行剩余列数不足时换行末尾 item 自动用剩余列数填充其spangetFilledItem。当出现「某行 span 之和与 column 不匹配」的情况时开发环境下会通过devUseWarning输出警告Sum of column span in a line not match column of Descriptions.——这意味着你可以借助该警告在开发期快速定位跨行配置错误。单元格渲染Row / CellRow.tsx 依据layouthorizontal / vertical与bordered决定 DOM 结构垂直模式拆分为 label、content 两个tr水平模式单tr内完成 labelcontent 组合。最终由 Cell.tsx 输出th/td并计算colSpan。上述阶段均有对应的单元测试覆盖例如 index.test.tsx 验证 API 行为与渲染结果hooks.test.tsx 单独验证useRow/useItems等 hook 的布局与数据转换逻辑可作为理解实现细节的补充材料。主题变量Design TokenDescriptions支持通过 CSS-in-JS 主题变量进行定制官方文档通过ComponentTokenTable componentDescriptions /动态渲染其 Token 列表见 index.zh-CN.md 的「主题变量Design Token」小节样式实现位于 style/index.ts包含 label 底色、边框颜色、cell padding 等 Token。通过 ConfigProvider 的theme.components.Descriptions即可按项目规范统一调整描述列表的外观。小结本文完整覆盖了 Ant DesignDescriptions的两种数据写法、全部 API 参数与默认值、四种典型实战场景边框、垂直、响应式、自定义样式并从 index.tsx、useRow.ts、Cell.tsx 等源码出发讲清了「列数合并 → 数据归一化 → 行布局 → 单元格渲染」的实现链路。无论你是要在详情页快速落地只读信息展示还是想深入理解 antd 表格类组件的内部设计本文提供的配置与源码对照都可供直接参考与复用。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ant Design Descriptions 描述列表组件完全指南：从 items 配置到响应式布局与源码实现
Ant Design Descriptions 描述列表组件完全指南从 items 配置到响应式布局与源码实现【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design导读本文以 Ant DesignantdDescriptions描述列表组件为核心系统讲解如何在详情页中高效展示只读字段组合。你将掌握items配置式写法与Descriptions.Item子组件写法的差异与取舍、column/span的响应式规则、bordered/size/layout等全部 API 参数并通过阅读 组件入口源码、行布局算法 与 单元格渲染理解其底层实现原理最终能独立构建出带边框、垂直、响应式的专业详情页。何时使用 DescriptionsDescriptions组件常用于详情页的信息展示用于在页面上以「标签 内容」的规整列表形式呈现一组只读字段例如订单详情、用户资料、云资源实例配置等场景。与Table相比它不承载复杂交互专注静态信息的视觉组织与Card 手工排版相比它内置了列数控制、边框、标签对齐与响应式能力开箱即用。从 组件实现 可以看出Descriptions 最终渲染为一个table结构prefixCls-view包裹将数据以行、列的方式排布语义上天然适合「字段-值」型只读信息的展示。两种数据写法items 配置式与 Item 子组件式items 配置式 5.8.0 推荐自 antd 5.8.0 起官方推荐使用items配置数组写法数据与渲染分离结构更清晰// 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} /;从源码看DescriptionsItemType 类型允许每个 item 携带key、label、children、span数字或响应式对象、labelStyle、contentStyle、className、style等字段组件内部 通过useItems(screens, items, children)优先消费items。Item 子组件式 5.8.0 兼容写法对于 5.8.0 以下版本或偏好 JSX 声明式写法的场景可以使用Descriptions.Item子组件// 5.8.0 可用5.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;有趣的是Item.ts 中的DescriptionsItem本身并不渲染任何 DOM它只是把children原样返回({ children }) children真正的数据采集发生在 useItems.ts 中通过rc-util的toArray遍历子节点再{ ...node?.props, key: node.key }把每个Descriptions.Item的 props 拍平成与items数组同构的数据。因此两种写法在渲染层完全等价items只是把这种「运行时采集」提前到了业务代码中。Descriptions 完整 API 参数详解Descriptions 属性总览以下表格完整覆盖 index.zh-CN.md 中定义的 API并补充了源码中的行为细节。参数说明类型默认值版本bordered是否展示边框booleanfalsecolon配置Descriptions.Item的colon的默认值。表示是否显示 label 后面的冒号booleantruecolumn一行的DescriptionItems数量可以写成像素值或支持响应式的对象写法{ xs: 8, sm: 16, md: 24}number |RecordBreakpoint, number3contentStyle自定义内容样式CSSProperties-4.10.0extra描述列表的操作区域显示在右上方ReactNode-4.5.0items描述列表项内容DescriptionsItem[]-5.8.0labelStyle自定义标签样式CSSProperties-4.10.0layout描述布局horizontal|verticalhorizontalsize设置列表的大小。可以设置为middle、small或不填只有设置bordered{true}生效default|middle|small-title描述列表的标题显示在最顶部ReactNode-DescriptionItem 属性参数说明类型默认值版本contentStyle自定义内容样式CSSProperties-4.9.0label内容的描述ReactNode-labelStyle自定义标签样式CSSProperties-4.9.0span包含列的数量number |Screens1screens: 5.9.0span 语义说明span是Description.Item的数量span{2}会占用两个DescriptionItem的宽度。当同时配置style和labelStyle或contentStyle时两者会同时作用样式冲突时后者会覆盖前者。关键参数源码级解读column 的响应式解析组件实现 中通过matchScreen(screens, { ...DEFAULT_COLUMN_MAP, ...column })合并用户配置与默认映射未命中任何断点时兜底为3。constant.ts 定义了各断点默认列数xxl: 3、xl: 3、lg: 3、md: 3、sm: 2、xs: 1——即默认情况下小屏手机每行 1 项平板每行 2 项桌面及以上每行 3 项。bordered 的渲染分支bordered 模式下每个 item 是独立的一个th/td单元格非 bordered 模式下 label 与 content 被合并进同一个td的item-container容器内用两个span展示见 Cell.tsx。size 的生效条件从源码看mergedSize通过useSize获取继承 ConfigProvider 的组件尺寸并仅在非default时追加${prefixCls}-${mergedSize}类名。文档明确说明size只有在设置bordered{true}时才生效因此无边框模式下设置 size 不会产生视觉差异。title 与 extra 的布局组件实现 中当title或extra存在时渲染descriptions-header头部分区title居左、extra居右常用于放置「编辑」「详情」等操作按钮。实战示例从基本用法到复杂场景基本用法最简用法直接传入title与items参见 demo/basic.tsximport React from react; import { Descriptions } from antd; import type { DescriptionsProps } from antd; 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: Remark, children: empty }, { key: 5, label: Address, children: No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China }, ]; const App: React.FC () Descriptions titleUser Info items{items} /; export default App;带边框的 Descriptions设置bordered后label 与 content 拥有独立单元格和边框适合需要强调字段归属的信息密度较高的场景完整示例见 demo/border.tsx。注意其中span的用法Usage Time设置span: 2、Status设置span: 3实现跨列占位const items: DescriptionsProps[items] [ { key: 5, label: Usage Time, children: 2019-04-24 18:00:00, span: 2 }, { key: 6, label: Status, children: Badge statusprocessing textRunning /, span: 3 }, // ... ]; const App: React.FC () Descriptions titleUser Info bordered items{items} /;垂直布局vertical设置layoutvertical后label 在上、content 在下。从 Row.tsx 可以看出垂直模式将一行拆成两个trlabel 行th与 content 行td典型示例如下完整见 demo/vertical.tsxconst items: DescriptionsProps[items] [ { key: 1, label: UserName, children: Zhou Maomao }, { key: 4, label: Address, span: 2, children: No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China }, // ... ]; const App: React.FC () Descriptions titleUser Info layoutvertical items{items} /;垂直布局同样可以叠加bordered参见 demo/vertical-border.tsx并在Responsive案例中与响应式 column 组合使用。响应式列数与响应式 spancolumn与span都支持断点对象写法。column控制整表每行列数span控制单个 item 占用的列数二者可同时使用。以下示例来自 demo/responsive.tsxcolumn在手机上 1 列、桌面 4 列同时部分 item 的span按断点变化const items: DescriptionsProps[items] [ { label: Product, children: Cloud Database }, { label: Billing, children: Prepaid }, { label: Time, children: 18:00:00 }, { label: Amount, children: $80.00 }, { label: Discount, span: { xl: 2, xxl: 2 }, children: $20.00 }, { label: Official, span: { xl: 2, xxl: 2 }, children: $60.00 }, { 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 / ), }, // ... ]; const App: React.FC () ( Descriptions titleResponsive Descriptions bordered column{{ xs: 1, sm: 2, md: 3, lg: 3, xl: 4, xxl: 4 }} items{items} / );响应式span的解析同样发生在 useItems.ts当span是对象时通过matchScreen(screens, span)依据当前视口断点换算为实际列数当span为数字时直接透传。注意span的响应式对象写法自 5.9.0 起支持。自定义尺寸设置sizesmall或sizemiddle可调整表格内边距与字号仅在bordered下生效参见 demo/size.tsx。若不传size会继承 ConfigProvider 全局配置的组件尺寸。自定义 label / content 样式labelStyle与contentStyle既可以在Descriptions上统一设置作用所有 item见 demo/style.tsx也可以在单个 item 上单独覆盖。合并逻辑位于 Cell.tsx 与 Row.tsx渲染时通过{ ...rootLabelStyle, ...labelStyle }逐级合并item 级样式优先级更高此外二者经 DescriptionsContext 从顶层向单元格传递这也是组件内共享样式配置的实现通道。复杂文本与间距控制复杂内容如多行文本、换行、富节点在 bordered 模式下表现更规整相关调试示例见 demo/text.tsx 与 demo/padding.tsx。children接受任意ReactNode可以嵌入Badge、Tag、br /等组合元素如上面 border 示例中的Badge statusprocessing textRunning /。底层实现原理从数据到表格的完整流水线Descriptions 的渲染流程可以概括为「列数合并 → 数据归一化 → 行布局 → 单元格渲染」四个阶段对应源码中的四个关键模块列数合并column组件实现 通过useMemo合并DEFAULT_COLUMN_MAP与用户column配置得到当前断点下的mergedColumnuseBreakpoint负责订阅视口断点变化这也是响应式能力的来源。数据归一化items/childrenuseItems.ts 优先取items否则将children中的Descriptions.Item拍平为同一数据结构再统一完成响应式span解析输出InternalDescriptionsItemType[]。行布局算法useRowuseRow.ts 按mergedColumn把扁平数组切分为二维行数组逐个 item 累加span当前行剩余列数不足时换行末尾 item 自动用剩余列数填充其spangetFilledItem。当出现「某行 span 之和与 column 不匹配」的情况时开发环境下会通过devUseWarning输出警告Sum of column span in a line not match column of Descriptions.——这意味着你可以借助该警告在开发期快速定位跨行配置错误。单元格渲染Row / CellRow.tsx 依据layouthorizontal / vertical与bordered决定 DOM 结构垂直模式拆分为 label、content 两个tr水平模式单tr内完成 labelcontent 组合。最终由 Cell.tsx 输出th/td并计算colSpan。上述阶段均有对应的单元测试覆盖例如 index.test.tsx 验证 API 行为与渲染结果hooks.test.tsx 单独验证useRow/useItems等 hook 的布局与数据转换逻辑可作为理解实现细节的补充材料。主题变量Design TokenDescriptions支持通过 CSS-in-JS 主题变量进行定制官方文档通过ComponentTokenTable componentDescriptions /动态渲染其 Token 列表见 index.zh-CN.md 的「主题变量Design Token」小节样式实现位于 style/index.ts包含 label 底色、边框颜色、cell padding 等 Token。通过 ConfigProvider 的theme.components.Descriptions即可按项目规范统一调整描述列表的外观。小结本文完整覆盖了 Ant DesignDescriptions的两种数据写法、全部 API 参数与默认值、四种典型实战场景边框、垂直、响应式、自定义样式并从 index.tsx、useRow.ts、Cell.tsx 等源码出发讲清了「列数合并 → 数据归一化 → 行布局 → 单元格渲染」的实现链路。无论你是要在详情页快速落地只读信息展示还是想深入理解 antd 表格类组件的内部设计本文提供的配置与源码对照都可供直接参考与复用。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
