ng-zorro-antd Spin 组件尺寸详解:small / default / large 三种加载态的选型与实践
ng-zorro-antd Spin 组件尺寸详解:small / default / large 三种加载态的选型与实践
Spin(加载中)是 ng-zorro-antd(基于 Ant Design 的 Angular UI 组件库)中最基础的反馈类组件之一,用于在页面或区块处于等待异步数据、正在渲染的过程中缓解用户的等待焦虑。本文以 components/spin/demo/size.md 文档为主线,完整讲解 Spin 的三种尺寸(small、default、large)各自适用的加载场景,并结合 spin.component.ts、样式源码与测试用例,说明尺寸属性在底层是如何生效的。读完本文,你将能够根据「文本加载 / 卡片级加载 / 页面级加载」三种典型场景为 nz-spin 正确选型,并掌握与 nzTip、nzSimple、全局配置等特性的组合用法。
一、三种尺寸的核心选型原则
nz-spin 通过 nzSize 输入属性控制组件大小,可选值只有三个:'small' | 'default' | 'large',默认值为 'default'。该类型定义在 components/core/types/size.ts:
export type NzSizeLDSType = 'large' | 'default' | 'small';
尺寸文档(size.md)给出的选型建议非常明确,这也是 Ant Design 生态中对 Spin 尺寸的通行约定:
| 尺寸 | 英文说明 | 适用场景 |
|---|---|---|
small(小) |
A small Spin use in loading text | 用于文本加载,例如按钮内部、行内文本、输入框旁的加载提示 |
default(默认) |
Default Spin use in loading card-level block | 用于卡片容器级加载,即包裹卡片、表格、列表等中等区块 |
large(大) |
Large Spin use in loading page | 用于页面级加载,即整页刷新或首屏数据等待 |
简言之:小的用于文本加载,默认用于卡片容器级加载,大的用于页面级加载。这一约定贯穿于 Ant Design 的视觉体系:小尺寸的点阵足够紧凑,不会干扰行内文字;大尺寸的点阵在整页居中时视觉重心更稳,能清晰传达「整页正在加载」的信号。
二、演示代码与最小可运行示例
官方演示(components/spin/demo/size.ts)用一个组件同时渲染三种尺寸,并通过 nzSimple 开启「不包裹子元素」的独立加载形态:
import { Component } from '@angular/core';
import { NzSpinModule } from 'ng-zorro-antd/spin';
@Component({
selector: 'nz-demo-spin-size',
imports: [NzSpinModule],
template: `
<nz-spin nzSimple nzSize="small" />
<nz-spin nzSimple />
<nz-spin nzSimple nzSize="large" />
`,
styles: `
nz-spin {
display: inline-block;
margin-right: 16px;
}
`
})
export class NzDemoSpinSizeComponent {}
这里有两个值得注意的细节:
nzSimple属性:当只展示加载点本身、不需要包裹内容时使用(如本演示),其默认值为false。从 spin.component.ts 可以看到它由booleanAttribute转换:@Input({ transform: booleanAttribute }) nzSimple = false;。当nzSimple为true时,组件不会渲染.ant-spin-container包裹层(对应测试 spin.spec.ts 中should wrapper work用例)。nzSize绑定写法:模板中直接使用属性绑定nzSize="small"即可;若需要动态切换,可写成<a href="https://link.gitcode.com/i/e3055509c7cf85c3827455e515c50cc2" target="_blank">nzSize]="size()"(signal 写法)或[nzSize]="sizeVar",测试组件 [spin.spec.ts 中即采用[nzSize]="size()"的绑定方式。
三、尺寸属性在源码中如何生效
3.1 输入定义与默认值
nzSize 在 spin.component.ts 中被定义为普通输入(非全局配置项,注意与 nzIndicator 不同):
@Input() nzSize: NzSizeLDSType = 'default';
结合 components/spin/doc/index.zh-CN.md 的 API 表格,nzSize 的完整定义如下:
| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
[nzSize] |
组件大小 | 'large' | 'small' | 'default' |
'default' |
—(不支持全局配置) |
也就是说,nzSize 只能通过组件实例级绑定控制,无法像 nzIndicator 那样通过 NzConfigService 做全局统一配置;而全局配置 spin 模块的 key 为 'spin'(见 spin.component.ts 的 const NZ_CONFIG_MODULE_NAME: NzConfigKey = 'spin')。
3.2 模板中的 class 映射
组件模板(spin.component.ts)在渲染加载点时,根据 nzSize 的值动态切换两个样式类:
<div
class="ant-spin ant-spin-spinning"
[class.ant-spin-rtl]="dir() === 'rtl'"
[class.ant-spin-lg]="nzSize === 'large'"
[class.ant-spin-sm]="nzSize === 'small'"
[class.ant-spin-show-text]="nzTip"
>
由此可以看到尺寸体系的实现约定:
nzSize === 'large'→ 追加ant-spin-lg类;nzSize === 'small'→ 追加ant-spin-sm类;default不追加任何尺寸类,使用默认样式。
这一映射关系在单元测试 spin.spec.ts 中被直接验证:
it('should size work', () => {
testComponent.size.set('small');
fixture.detectChanges();
expect(spin.nativeElement.querySelector('.ant-spin').classList).toContain('ant-spin-sm');
testComponent.size.set('large');
fixture.detectChanges();
expect(spin.nativeElement.querySelector('.ant-spin').classList).toContain('ant-spin-lg');
});
测试证明了:切换 nzSize 后,.ant-spin 元素上会同步出现/消失 ant-spin-sm 与 ant-spin-lg 类——这正是尺寸样式的唯一作用点。
3.3 视觉尺寸的具体数值
三种尺寸对应的点阵(dot)尺寸在主题变量中定义。以默认主题为例(components/style/themes/default.less,变量主题 variable.less 相同):
@spin-dot-size-sm: 14px;
@spin-dot-size: 20px;
@spin-dot-size-lg: 32px;
在 components/spin/style/index.less 中,这些变量被用来控制点阵字号与内部圆点(dot-item)的实际尺寸:
- 默认尺寸:点阵容器
font-size: @spin-dot-size(20px),四个圆点均为9px × 9px; &-sm &-dot(small):点阵容器font-size: 14px,圆点缩小为6px × 6px;&-lg &-dot(large):点阵容器font-size: 32px,圆点放大为14px × 14px。
四个圆点本身通过 animation: antSpinMove 1s infinite linear alternate 依次错开 0.4s / 0.8s / 1.2s 的动画延迟形成扩散闪烁效果,点阵整体再以 antRotate 1.2s infinite linear 旋转(index.less)。
3.4 尺寸与嵌套加载(nested loading)的协同
当 nzSimple 为 false(默认)时,nz-spin 会包裹子内容并渲染 .ant-spin-container,加载点以绝对定位居中覆盖在内容之上,同时内容区叠加 .ant-spin-blur 模糊效果。此时 ant-spin-sm / ant-spin-lg 同样会影响加载点与文案的相对位置(index.less):small 时点阵与 nzTip 文案的间距按 @spin-dot-size-sm(14px)计算,large 时按 @spin-dot-size-lg(32px)计算,保证不同尺寸下「点阵 + 描述文案」的组合始终视觉居中。这正是「卡片级加载」与「页面级加载」场景下给加载点配 nzTip 文案时的底层排版依据。
四、三种尺寸的实战组合用法
4.1 small:文本加载
适用于按钮、输入框、行内文字旁的小型加载提示。实际项目中通常会与 nzSimple 组合,避免额外生成包裹层,例如:
<nz-spin nzSimple nzSize="small" [nzSpinning]="isSaving" />
<button nz-button [nzLoading]="isSaving">保存</button>
当 nzSize="small" 且不设置 nzTip 时,ant-spin-show-text 类不会出现,点阵保持最紧凑的 6px 圆点、14px 点阵,视觉上不会挤压行内文本。
4.2 default:卡片容器级加载
这是最常用的形态:默认尺寸(20px 点阵)包裹卡片、表格或列表,加载时内容区半透明模糊。例如:
<nz-spin [nzSpinning]="loading" nzTip="加载中...">
<nz-table [nzData]="data"></nz-table>
</nz-spin>
此时 nzTip 文案会根据 default 尺寸(@spin-dot-size = 20px)自动计算点阵与文案的间距,确保整体居中。
4.3 large:页面级加载
用于整页刷新或首屏数据等待,点阵放大到 14px 圆点、32px 点阵,视觉重心更明显。可配合全屏容器居中展示:
<div class="page-loading">
<nz-spin nzSimple nzSize="large" />
</div>
也可以与 nzDelay 组合使用(<a href="https://link.gitcode.com/i/b9a6a2aaa802f7f6f237f474db0a14c3" target="_blank">nzDelay]="100"),延迟 100ms 再显示加载点,避免快速完成的请求导致加载动效闪烁——nzDelay 的底层实现见 [spin.component.ts,它通过 setTimeout 对 nzSpinning 的变化做延迟翻转,且只在「由加载中变为非加载」时立即生效、反向延迟,防止闪烁。
五、尺寸与全局配置、RTL 的边界说明
- 尺寸不支持全局配置:在 components/spin/doc/index.zh-CN.md 的 API 表格中,只有
[nzIndicator]标注了「全局配置 ✅」;nzSize需要每个组件实例单独绑定。 - RTL 兼容:模板中
<a href="https://link.gitcode.com/i/93a9692ed22de2bf56ef75cda60c5c7c" target="_blank">class.ant-spin-rtl]="dir() === 'rtl'"会根据Directionality服务自动切换 RTL 方向([spin.component.ts),样式侧.ant-spin-rtl { direction: rtl; }与之对应(index.less),三种尺寸在 RTL 模式下同样生效。 - 主题定制:若需调整尺寸观感,可通过主题变量覆盖
@spin-dot-size-sm、@spin-dot-size、@spin-dot-size-lg(默认主题定义于 components/style/themes/default.less),无需修改组件源码。
六、小结
nz-spin 的三种尺寸对应三种明确的使用场景:small 服务文本级加载、default 服务卡片容器级加载、large 服务页面级加载。尺寸通过 nzSize 输入(默认 'default')驱动模板切换 ant-spin-sm / ant-spin-lg 样式类,再由 Less 主题变量(14px / 20px / 32px)最终决定点阵的视觉大小。理解这套「输入属性 → 样式类 → 主题变量」的链路,你就能在各类加载场景中快速做出正确的尺寸选型,并与 nzSimple、nzTip、nzDelay 等特性自由组合出符合 Ant Design 规范的加载体验。