ng-zorro-antd Space 组件垂直间距实战指南：从 `nzDirection=“vertical“` 到整行占位的完整方案

• UI组件
• 前端

导读

在 Angular 项目中，如何让一组相邻组件之间保持统一、美观的垂直间距，是布局中最常见的问题之一。ng-zorro-antd 的 Space 组件（nz-space）通过nzDirection="vertical"即可一键完成纵向排列与间距控制，配合width: 100%还能让子元素独占一行。本文将围绕官方文档中的"垂直间距"示例，从组件 API、源码实现、样式原理到测试用例，为你提供一套可直接落地的最优实践。

什么是垂直间距

官方文档（vertical.md）对垂直间距场景的定义非常精炼：

相邻组件垂直间距。

也就是说，当多个组件（卡片、按钮、表单控件等）需要自上而下依次排列，并且彼此之间保持统一间隔时，nz-space的垂直模式就是首选方案。文档同时强调了一个关键能力：

可以设置width: 100%独占一行。

这意味着垂直排列下，如果你希望某个子元素占据整行宽度（例如全宽卡片、全宽输入框），只需要在子元素上设置width: 100%即可，其余子元素仍保持各自的内容宽度。

快速上手：一个可运行的垂直间距示例

官方 Demo（vertical.ts）给出了最直接的用法——垂直排列两张卡片，并为每个子项打上*nzSpaceItem标记：

import { Component } from '@angular/core'; import { NzCardModule } from 'ng-zorro-antd/card'; import { NzSpaceModule } from 'ng-zorro-antd/space'; @Component({ selector: 'nz-demo-space-vertical', imports: [NzCardModule, NzSpaceModule], template: ` <nz-space nzDirection="vertical"> <nz-card *nzSpaceItem nzTitle="Card" style="width: 300px"> <p>Card content</p> <p>Card content</p> </nz-card> <nz-card *nzSpaceItem nzTitle="Card" style="width: 300px"> <p>Card content</p> <p>Card content</p> </nz-card> </nz-space> ` }) export class NzDemoSpaceVerticalComponent {}

使用要点拆解

• <nz-space nzDirection="vertical">：nzDirection是方向开关，取值为'vertical' | 'horizontal'（默认'horizontal'，见 types.ts）。这里显式设为vertical，组件就会以纵向 flex 布局排列子项。
• *nzSpaceItem：这是NzSpaceItemDirective（定义于 space-item.directive.ts，选择器为[nzSpaceItem]）。只有被打上该标记的内容才会被nz-space识别为间距项并逐项包裹渲染；不加标记的内容不会参与间距计算。
• style="width: 300px"：示例通过固定宽度控制卡片大小。若去掉宽度改为width: 100%，卡片即可在垂直方向上独占一整行，这与文档中"可以设置width: 100%独占一行"的说明完全对应。
• 模块导入：需要在组件的imports中引入NzSpaceModule（space.module.ts）以及子组件自身的模块（这里是NzCardModule）。

让子元素独占一行：width: 100%的两种落地写法

垂直间距最常见的场景是表单布局——每一项输入框都要撑满容器宽度。两种等价写法：

<!-- 写法一：直接在子组件上设置 --> <nz-space nzDirection="vertical" style="width: 100%"> <input *nzSpaceItem nz-input placeholder="用户名" style="width: 100%" /> <input *nzSpaceItem nz-input placeholder="密码" style="width: 100%" /> </nz-space>

<!-- 写法二：在容器上统一约束宽度 --> <nz-space nzDirection="vertical" style="width: 100%"> <input *nzSpaceItem nz-input style="width: 100%" /> </nz-space>

原理说明：nz-space根元素的样式是display: inline-flex（见 style/index.less），内联元素默认宽度由内容决定；而垂直模式下flex-direction: column，交叉轴方向（水平方向）的默认对齐是stretch，因此只要给子项（或容器）设定width: 100%，子项就会拉伸到与容器同宽，从而"独占一行"。这也是文档推荐该写法背后的样式机制。

垂直间距相关的完整 API 一览

垂直模式只是nz-space的一个方向选项，实际使用时通常会与间距、对齐等参数搭配。下表来自组件官方文档（index.zh-CN.md），已结合源码注释补充默认值与行为细节：

其中nzSize的类型定义（types.ts）：

export type NzSpaceType = 'small' | 'middle' | 'large'; export type NzSpaceSize = NzSpaceType | number;

垂直模式下的参数使用建议

• nzSize：三档预设small（8px）、middle（16px）、large（24px），也可以直接传数字（如36）或数组[36, 18]分别指定水平间距与垂直间距。默认'small'，即垂直模式下相邻组件间距为 8px。
• nzAlign：在垂直模式下，start / center / end / baseline控制的是子项在水平方向的交叉轴对齐（如center让所有卡片水平居中，配合固定宽度使用效果最佳）。
• nzWrap：官方文档明确标注"仅在horizontal时有效"，垂直模式下无需关心。
• nzSplit：在子项之间插入分隔符（字符串或模板），例如垂直步骤流中的分割线场景。

源码级原理：垂直间距是如何实现的

垂直间距的能力并非魔法，它由三部分代码协同完成，均在仓库内可查证：

1. 组件模板与宿主样式绑定

在 space.component.ts 中，nz-space的宿主绑定会根据方向动态切换 CSS 类：

host: { class: 'ant-space', '[class.ant-space-horizontal]': 'nzDirection === "horizontal"', '[class.ant-space-vertical]': 'nzDirection === "vertical"', // ...对齐类与换行绑定 '[style.column-gap.px]': 'horizontalSize', '[style.row-gap.px]': 'verticalSize' }

可见间距最终通过 CSScolumn-gap/row-gap直接以内联样式生效，垂直模式下真正起作用的是row-gap（行间距）。

2. 间距数值的归一化

源码中的SPACE_SIZE常量与normalizeSpaceSize函数（space.component.ts）是间距计算的核心：

const SPACE_SIZE: Record<NzSpaceType, number> = { small: 8, middle: 16, large: 24 }; function normalizeSpaceSize(size: NzSpaceSize | [NzSpaceSize, NzSpaceSize]) { const [horizontalSize, verticalSize] = (Array.isArray(size) ? size : [size, size]).map(s => typeof s === 'number' ? s : SPACE_SIZE[s] ); return { horizontalSize, verticalSize }; }

当nzSize传单个值时，水平、垂直间距取相同值；传数组[水平, 垂直]时可分别控制。这也是垂直布局中想让"行间距"与"列间距"不同时的官方支持方式。

3. 样式层：flex 纵向排列

style/index.less 定义了布局根基：

.@{space-prefix-cls} { display: inline-flex; &-vertical { flex-direction: column; } // ... align-* 对齐类 }

总结调用链：nzDirection="vertical"→ 添加ant-space-vertical类 →flex-direction: column→ 子项纵向堆叠；nzSize→normalizeSpaceSize解析 →row-gap生效 → 相邻组件之间出现统一间距；*nzSpaceItem标记的子项被逐个包裹为.ant-space-item（见组件模板中的@for循环）。

测试用例验证：间距与方向的确定性行为

仓库中的 space.component.spec.ts 用单元测试锁定了垂直间距的关键行为，可作为你使用时的行为契约：

• 方向切换：direction.set('vertical')后断言根元素包含ant-space-vertical类；切回horizontal则包含ant-space-horizontal。
• 预设尺寸：small→columnGap/rowGap均为8px；middle→16px；large→24px，与源码常量完全一致。
• 自定义尺寸：nzSize = 36时两个 gap 均为36px；nzSize = [36, 18]时columnGap为36px、rowGap为18px，验证了数组参数的分向生效。
• 对齐兜底：horizontal方向且未显式设置nzAlign时，自动使用center对齐（源码ngOnChanges中的兜底逻辑，space.component.ts）；垂直方向则不做默认对齐。

与其他 Space 场景的区分与组合

垂直间距并非孤立功能，它与同组件的其他 Demo 构成完整能力矩阵（均位于 components/space/demo）：

• 水平间距（basic.ts）：默认方向horizontal，适合按钮组、操作栏等行内元素场景，是垂直模式的"镜像"用法。
• 间距大小（size.md）：专门演示nzSize的large/middle三档切换，未设置时默认为small。
• 紧凑模式（nz-space-compact）：当需要表单组件之间紧凑连接且合并边框（如 Button、Input、Select、DatePicker、Cascader、TimePicker、TreeSelect）时使用，与nz-space的等距排列诉求互补，二者适用场景不同。

按官方文档的定位：Space 为内联元素提供间距并逐项包裹子元素，适合行、列中多个子元素的等距排列；Flex 组件则是块级布局工具，适合更灵活的分布控制。垂直间距场景下，nz-space nzDirection="vertical"通常比手写 CSS 更简洁、可维护。

小结

• 垂直间距 =nz-space+nzDirection="vertical"+ 子项标记*nzSpaceItem，开箱即用；
• 需要子元素整行占位时，配合width: 100%即可，机制由inline-flex + flex-direction: column保证；
• 间距由nzSize驱动（预设 8/16/24px 或任意数字、数组），通过row-gap内联样式生效；
• 官方单元测试已锁定方向切换、尺寸归一化与对齐兜底行为，可放心在生产环境中使用。

• UI组件
• 前端