UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本篇指南围绕 NG-ZORROng-zorro-antd的 Descriptions描述列表组件展开基于其官方文档 components/descriptions/doc/index.en-US.md 中的 API 定义结合 主组件源码 与 测试用例 深入讲解如何分组展示多个只读字段、nzColumn响应式列数如何按断点生效、nzSpan参与行排布的底层算法以及nzBordered、nzLayout、nzSize等属性在模板中的实际渲染差异。读完后可掌握描述列表的完整用法、布局原理与常见警告的成因。组件定位详情页中的只读字段分组展示官方文档对 Descriptions 的定位非常明确Display multiple read-only fields in a group.以分组形式展示多个只读字段。其典型使用场景是详情页Commonly displayed on the details page——例如用户信息页、订单信息页、资源实例详情页需要将用户名 / 电话 / 地址等一组键值对字段以整齐的网格形式呈现。组件属于数据展示Data Display类别由两个核心构件组成构件选择器源码位置描述列表容器nz-descriptionsdescriptions.component.ts描述列表项nz-descriptions-itemdescriptions-item.component.ts两者均通过NzDescriptionsModule对外导出见 public-api.ts 与 descriptions.module.ts也可作为独立组件按需导入。快速上手在组件中导入NzDescriptionsModule后即可声明式地定义标题、字段与内容。以下示例与官方示例 basic.ts 一致import { Component } from angular/core; import { NzDescriptionsModule } from ng-zorro-antd/descriptions; Component({ selector: nz-demo-descriptions-basic, imports: [NzDescriptionsModule], template: nz-descriptions nzTitleUser Info nz-descriptions-item nzTitleUserNameZhou Maomao/nz-descriptions-item nz-descriptions-item nzTitleTelephone18100000000/nz-descriptions-item nz-descriptions-item nzTitleLiveHangzhou, Zhejiang/nz-descriptions-item nz-descriptions-item nzTitleRemarkEmpty/nz-descriptions-item nz-descriptions-item nzTitleAddress No. 18, Wantang Road, Xihu District, Hangzhou, Zhejiang, China /nz-descriptions-item /nz-descriptions }) export class NzDemoDescriptionsBasicComponent {}对应的静态示例文档见 demo/basic.md。更多官方示例带边框、响应式、纵向布局、自定义尺寸分别位于 demo/border.md、demo/responsive.md、demo/vertical.md、demo/custom-size.md。nz-descriptions 属性详解官方文档给出的容器属性表如下此处完整继承并补充源码默认值说明PropertyDescriptionTypeDefaultGlobal Config[nzTitle]列表标题显示在顶部string \| TemplateRefvoidfalse[nzExtra]操作区域置于右上角string \| TemplateRefvoid-[nzBordered]是否显示边框booleanfalse✅[nzColumn]每行nz-descriptions-item的数量可为数字或{ xs: 8, sm: 16, md: 24 }这类对象number \| object{ xxl: 3, xl: 3, lg: 3, md: 3, sm: 2, xs: 1 }✅[nzSize]列表尺寸仅在nzBordered开启时生效default \| middle \| smalldefault✅[nzColon]标题后是否显示冒号booleantrue✅[nzLayout]列表布局方式horizontal \| verticalhorizontal对照 descriptions.component.ts 的Input声明可以确认文档与源码的对应关系Input({ transform: booleanAttribute }) WithConfig() nzBordered: boolean false; Input() nzLayout: NzDescriptionsLayout horizontal; Input() WithConfig() nzColumn: number | PartialResponsiveLikenumber defaultColumnMap; Input() WithConfig() nzSize: NzDescriptionsSize default; Input() nzTitle: string | TemplateRefvoid ; Input() nzExtra?: string | TemplateRefvoid; Input({ transform: booleanAttribute }) WithConfig() nzColon: boolean true;几个值得注意的实现细节nzBordered与nzColon使用booleanAttribute转换因此模板中nzBordered不带值绑定时会按布尔属性规则解析nzColumn的完整内置默认值源码中的defaultColumnMapdescriptions.component.ts实际为{ xxxl: 4, xxl: 3, xl: 3, lg: 3, md: 3, sm: 2, xs: 1 }即文档默认值之外还包含xxxl: 4一档当传入对象缺少当前断点时回退常量为DEFAULT_COLUMN_NUM 3nzTitle/nzExtra支持TemplateRef模板中通过*nzStringTemplateOutlet渲染descriptions.component.ts所以nzExtra可以传入模板引用放置按钮等操作内容官方示例 custom-size.ts 就传入了一个包含Edit按钮的#extraTpl模板nzSize的实现源码在 host 上按值绑定ant-descriptions-middle/ant-descriptions-small类名descriptions.component.ts文档同时声明该属性仅在nzBordered开启时生效即边框样式下的密度调整行高、内边距等由样式层控制。nz-descriptions-item 属性与 nzSpan列表项的属性如下与官方文档一致PropertyDescriptionTypeDefault[nzTitle]内容对应的标题string \| TemplateRefvoid-[nzSpan]该项跨占的列数number1从 descriptions-item.component.ts 的实现看每个 item 本身并不渲染任何可见结构——它的模板只是一个包裹ng-content /的ng-templatedescriptions-item.component.ts。item 的真实渲染由父组件nz-descriptions统一接管父组件通过ContentChildren(NzDescriptionsItemComponent)收集所有子项取其nzTitle、nzSpan与内容模板重新组装成表格行下文详述。nzSpan支持numberAttribute转换因此[nzSpan]2这种数字绑定方式是被明确支持的。带边框示例 border.ts 中可以看到典型的跨列用法z-descriptions-item nzTitleUsage Time [nzSpan]2 2018-04-24 18:00:00 To 2019-04-24 18:00:00 /nz-descriptions-item z-descriptions-item nzTitleStatus [nzSpan]3 nz-badge nzStatusprocessing nzTextRunning / /z-descriptions-item行排布算法prepareMatrix 如何把 items 铺成行理解 Descriptions 的布局行为关键在于源码中 prepareMatrix() 的排布算法。它维护一个累加宽度width按顺序遍历所有 item将当前 item 的nzSpan累加到width若width column达到一行容量该 item 的实际跨列被改写为column - (width - span)——即让最后一个 item 吃掉整行剩余空间然后换行并清零若width column超出一行容量源码会调用warn输出类似nzColumn is 3 but we have row length 5的告警但仍按填满剩余空间处理若遍历到最后一个 item 且未达行容量同样按剩余空间补齐i length - 1分支。这段逻辑解释了两个常见行为行内最后一项自动拉伸例如nzColumn为 3、items 的 span 为[1, 1]时第二项会以colSpan2渲染。测试用例 专门验证了这一点colspanArray设为[1, 1]后断言第二个td的colSpan为 4nzColumn为 5 时。span 总和超过nzColumn的告警descriptions.spec.ts 中断言了nzColumn is 3 but we have row length 5、nzColumn is 3 but we have row length 6等警告文本且行数按溢出截断到一行的方式计算span 为[1, 1, 1, 2, 3, 1, 5]时得到 3 行。遇到控制台告警时应检查各行 item 的nzSpan之和是否小于等于nzColumn。排布的触发时机也值得注意ngAfterContentInit中监听了三路信号——item 列表的增删items.changes、各 item 输入变化inputChange$带 16msauditTime节流、以及断点服务descriptions.component.ts任一变化都会重算itemMatrix并markForCheck。这意味着nzSpan、nzTitle的动态变更和窗口尺寸变化都能驱动重新布局测试用例 验证了内容切换后标题能正确刷新。模板渲染差异bordered 与非 bordered 的表格结构nz-descriptions的内容区最终渲染为一个table外层.ant-descriptions-viewdescriptions.component.tsnzBordered与nzLayout决定了完全不同的单元格结构nzLayouthorizontal 无边框每个 item 占一个td classant-descriptions-itemcolSpanitem.span标签与内容以span.ant-descriptions-item-label/ant-descriptions-item-content横向排布在同一格内nzLayouthorizontalnzBordered每个 item 拆成两个格子——标签格td classant-descriptions-item-label与内容格td classant-descriptions-item-content内容格的colSpan item.span * 2 - 1descriptions.component.ts。也就是说边框模式下内部表格列数是nzColumn的两倍跨列跨度会被放大计算nzLayoutvertical标签行与内容行拆成两条tr交替出现边框与非边框两种变体分别对应不同单元格类名descriptions.component.ts标签在上、内容在下。官方示例 vertical.ts 展示了nzLayoutvertical的用法其中Address 项通过[nzSpan]2让长地址跨两列vertical-border.ts 则演示了边框模式下的纵向布局。nzColon作用于无边框横向模式下的标签源码中通过[class.ant-descriptions-item-no-colon]!nzColon切换类名descriptions.component.ts关闭后标签后的冒号样式被移除。响应式列数nzColumn 与断点联动nzColumn既可传数字所有断点统一也可传对象按断点配置。官方示例 responsive.tsz-descriptions nzTitleResponsive Descriptions nzBordered [nzColumn]{ xxl: 4, xl: 3, lg: 3, md: 3, sm: 2, xs: 1 } nz-descriptions-item nzTitleProductCloud Database/nz-descriptions-item nz-descriptions-item nzTitleBillingPrepaid/nz-descriptions-item nz-descriptions-item nzTitletime18:00:00/nz-descriptions-item !-- 其余 items 省略共 7 项 -- /nz-descriptions底层机制见 getColumn()private getColumn(): number { if (typeof this.nzColumn ! number) { return this.nzColumn[this.breakpoint] ?? DEFAULT_COLUMN_NUM; } return this.nzColumn; }断点值来自注入的NzBreakpointService组件在初始化时以gridResponsiveMap订阅断点变化descriptions.component.ts窗口 resize 会触发breakpoint更新并调用prepareMatrix()重排对象中缺失的断点回退到DEFAULT_COLUMN_NUM 3因此传{ xs: 1 }这类部分配置是安全的当nzColumn被外部改动ngOnChanges时同样会立即重排descriptions.component.ts。响应式测试用例 模拟了视口从 1024px 到 320px 的变化断点命中md时同一组 item 排成 3 行缩小到xs单列后排成 7 行验证了断点驱动的列数切换。另一个针对 resize 的回归测试descriptions.spec.ts注释标注 fix #9927则确认了缩小再放大窗口后 item 内容不丢失。全局配置API 表中标注 ✅ 的属性nzBordered、nzColumn、nzSize、nzColon都带WithConfig()装饰器且组件声明了配置键const NZ_CONFIG_MODULE_NAME: NzConfigKey descriptions; // ... readonly _nzModuleName: NzConfigKey NZ_CONFIG_MODULE_NAME;即这些属性可纳入 NG-ZORRO 的全局配置机制在应用层面以descriptions为模块名统一覆盖默认值例如全局开启nzBordered、统一nzColon策略各组件内未显式绑定的输入将回落到全局配置。全局配置的整体用法可参考 docs/global-config.zh-CN.md。而nzLayout无全局配置标记需在模板中逐处设置。RTL 支持与验证方式从源码结构看nz-descriptions的 host 绑定了[class.ant-descriptions-rtl]dir() rtldescriptions.component.ts依赖angular/cdk/bidi的Directionality信号实现从右到左布局的类名切换RTL 测试 验证了dir在rtl与ltr间切换时ant-descriptions-rtl类名的增删。日常开发中可参考 descriptions.spec.ts 的断言方式自验组件行为通过.ant-descriptions-row数量验证行数是否符合nzColumn/nzSpan组合预期通过td的colSpan验证跨列与末项补满行为通过console.warn的 spy 验证列宽溢出告警文本。样式层面组件样式入口位于 style/index.less另有 patch.less 处理覆盖细节类名前缀为ant-descriptionshost 绑定class: ant-descriptionsdescriptions.component.ts。小结Descriptions 以父组件收集 item、统一铺排表格的架构把布局复杂度集中在 prepareMatrix() 一处nzColumn决定列容量数字或按断点响应nzSpan决定单项占宽末项自动补满剩余空间、溢出时给出明确告警。掌握行内 span 之和 ≤ 当前断点列数这一约束配合nzBordered/nzLayout/nzSize的外观开关与nzTitle/nzExtra的头部能力即可在各类详情页中稳定构建 Ant Design 风格的描述列表。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Descriptions 响应式布局nzColumn 断点配置与源码解析ng zorro antd Descriptions 响应式布局nzColumn 断点配置与源码解析 ng zorro antd 的 DescriptionsUI组件前端ng-zorro-antd 描述列表实战nz-descriptions 垂直布局与边框模式的完整实现解析ng zorro antd 描述列表实战nz descriptions 垂直布局与边框模式的完整实现解析 在 ng zorro antd 中 nz descUI组件前端ng-zorro-antd 描述列表带边框模式实战nzBordered、nzSpan 与表格化渲染原理ng zorro antd 描述列表带边框模式实战nzBordered、nzSpan 与表格化渲染原理 本篇围绕 ng zorro antd 中 nz desUI组件前端上一篇把一条带底噪的访谈录音修成能发布的成品Audacity 音频编辑快速上手下一篇RedisShake 4.x终极Redis数据迁移工具完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考