ng-zorro-antd Select 尺寸指南:nzSize 的 large / default / small 三种大小与实现原理
ng-zorro-antd Select 尺寸指南:nzSize 的 large / default / small 三种大小与实现原理
nzSize 是 ng-zorro-antd Select(下拉选择器)组件用于控制选择框高度的核心输入属性,仅接受 large、default、small 三种取值,分别对应 40px、32px、24px 的输入框高度。本文以 components/select/demo/size.md 官方演示文档为骨架,结合 select.component.ts 源码与 select.spec.ts 测试用例,完整讲解 nzSize 的用法、与其他尺寸体系的优先级关系,以及底层 CSS 类映射原理。读完本文,你将能精准控制 Select 在不同表单密度下的外观,并理解它如何与 Form、Space(compact) 等组件的尺寸体系协同工作。
nzSize 参数定义与取值
在官方 API 文档 components/select/doc/index.zh-CN.md 中,nzSize 的定义如下:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
[nzSize] |
选择框大小 | 'large' | 'small' | 'default' |
'default' |
三种取值对应的高度规格(来自 components/select/demo/size.md 的官方说明):
large:输入框高度40px;default(缺省值):输入框高度32px;small:输入框高度24px。
在源码层面,该输入属性定义于 select.component.ts:
@Input() nzSize: NzSelectSizeType = 'default';
其类型 NzSelectSizeType 直接复用了核心类型模块中的通用尺寸联合类型 select.component.ts:
export type NzSelectSizeType = NzSizeLDSType;
也就是说,large / default / small 这套命名并非 Select 组件独有,而是 ng-zorro-antd 中 Button、Input、Radio 等多个表单类组件共享的 LDS(Large / Default / Small)尺寸体系,掌握了 nzSize 的用法即可举一反三。
完整可运行示例:三种大小实时切换
官方演示 size.ts 给出了一个非常实用的场景:用 nz-radio-group 提供 Large / Default / Small 三个切换按钮,通过信号(signal)动态驱动下方多个 Select 的 nzSize,一次性覆盖了单选、可搜索单选、多选(multiple)、标签(tags)四种形态。下面为完整示例(已补充注释,可直接复制运行):
import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NzRadioModule } from 'ng-zorro-antd/radio';
import { NzSelectModule, NzSelectSizeType } from 'ng-zorro-antd/select';
function alphabet(): string[] {
const children: string[] = [];
for (let i = 10; i < 36; i++) {
children.push(i.toString(36) + i); // 生成 a10、b11、c12 ... z35 形式的选项
}
return children;
}
@Component({
selector: 'nz-demo-select-size',
imports: [FormsModule, NzSelectModule, NzRadioModule],
template: `
<!-- 用单选按钮组切换三种尺寸 -->
<nz-radio-group [(ngModel)]="size">
<label nz-radio-button nzValue="large">Large</label>
<label nz-radio-button nzValue="default">Default</label>
<label nz-radio-button nzValue="small">Small</label>
</nz-radio-group>
<br />
<br />
<!-- 基础单选 -->
<nz-select [nzOptions]="options" [(ngModel)]="singleValue" [nzSize]="size()" />
<br />
<br />
<!-- 可搜索单选 -->
<nz-select [nzOptions]="options" [(ngModel)]="singleValue" [nzSize]="size()" nzShowSearch />
<br />
<br />
<!-- 多选模式 -->
<nz-select
[nzOptions]="options"
[(ngModel)]="multipleValue"
[nzSize]="size()"
nzMode="multiple"
nzPlaceHolder="Please select"
/>
<br />
<br />
<!-- 标签模式(可自由输入创建新选项) -->
<nz-select
[nzOptions]="options"
[(ngModel)]="tagValue"
[nzSize]="size()"
nzMode="tags"
nzPlaceHolder="Please select"
/>
`,
styles: `
nz-select {
width: 100%; /* 演示中让选择框占满宽度,更便于观察高度差异 */
}
`
})
export class NzDemoSelectSizeComponent {
readonly options = alphabet().map(item => ({ label: item, value: item }));
readonly size = signal<NzSelectSizeType>('default'); // 当前尺寸,默认 default
readonly singleValue = signal('a10');
readonly multipleValue = signal(['a10', 'c12']);
readonly tagValue = signal(['a10', 'c12', 'tag']);
}
使用要点:
nzSize对default(单选)、multiple(多选)、tags(标签)三种nzMode均生效,可配合nzShowSearch在可搜索场景下使用;- 示例中
size用signal<NzSelectSizeType>('default')管理,模板里通过[nzSize]="size()"单向绑定;若你的项目仍使用组件类属性写法,用[nzSize]="size"并配合ngModel/FormControl同样可行; - 尺寸切换是响应式的:从 select.component.ts 的
ngOnChanges钩子可以看出,当nzSize输入变化时组件会通过this.size.set(nzSize.currentValue)(select.component.ts)更新内部状态,进而驱动 CSS 类与整体布局刷新。
尺寸的最终确定:三级优先级链
nzSize 并不是决定最终尺寸的唯一来源。从源码看,组件内部存在一个 finalSize 计算信号,其优先级从高到低为(select.component.ts):
protected finalSize = computed(() => {
if (this.formSize?.()) {
return this.formSize(); // 1. 表单(Form)注入的尺寸
}
if (this.compactSize) {
return this.compactSize(); // 2. Space 紧凑布局(nzSpaceCompact)注入的尺寸
}
return this.size(); // 3. 自身 nzSize 输入属性
});
对应地,组件分别从三个来源注入/初始化尺寸(select.component.ts):
private readonly size = signal<NzSizeLDSType>(this.nzSize); // 组件自身 nzSize
private readonly formSize = inject(NZ_FORM_SIZE, { optional: true }); // 表单尺寸令牌
private compactSize = inject(NZ_SPACE_COMPACT_SIZE, { optional: true }); // 紧凑布局尺寸令牌
由此可以推断并总结出三条实践结论:
- 当 Select 位于
nz-form-item等表单上下文中,且表单整体配置了尺寸时,表单注入的尺寸会覆盖组件上的nzSize; - 当 Select 作为
nz-space-compact(紧凑组合布局)的子元素时,紧凑尺寸同样优先于nzSize; - 只有在表单与紧凑布局都没有注入尺寸的情况下,
nzSize才作为最终生效值。
这一设计保证了"表单统一控尺寸、局部可单独覆盖"的灵活度,与 ng-zorro-antd 全局尺寸配置体系的思路一脉相承。
源码实现:尺寸如何映射为 CSS 类
nzSize 的数值(40px / 32px / 24px)并非通过内联样式硬编码,而是通过绑定尺寸类名交给 Less 样式体系处理。在 select.component.ts 的宿主类绑定中可以看到:
'[class.ant-select-lg]': 'finalSize() === "large"',
'[class.ant-select-sm]': 'finalSize() === "small"',
即:large 对应 ant-select-lg 类,small 对应 ant-select-sm 类,而默认值 default 不附加任何尺寸类,直接使用 .ant-select 的基础样式。对应的样式文件位于 components/select/style 目录(entry.less、single.less、multiple.less 等),最终呈现为 40px / 32px / 24px 三档高度。
值得注意的是,尺寸类绑定的判断基于 finalSize() 而非 nzSize 本身——这再次印证了上一节的三级优先级链:即使你在模板中写了 nzSize="large",只要表单或紧凑布局注入了其他尺寸,实际渲染的类名也会随之变化。
测试验证:类名行为有据可依
尺寸映射的正确性由单元测试直接锁定。在 select.spec.ts 中,should nzSize work 用例完整验证了两档尺寸的类名切换:
it('should nzSize work', () => {
component.nzSize.set('large');
fixture.detectChanges();
expect(selectElement.classList).toContain('ant-select-lg');
component.nzSize.set('small');
fixture.detectChanges();
expect(selectElement.classList).toContain('ant-select-sm');
});
该用例覆盖了"设置 large → 出现 ant-select-lg 类;切换为 small → 出现 ant-select-sm 类"的完整交互路径,说明尺寸切换与类名更新在多次变更下都能正确工作(内部即通过前述 ngOnChanges 中 size 信号的更新链路实现)。
实践建议与小结
综合官方演示、源码与测试,使用 nzSize 时有以下几点建议:
- 按表单密度选尺寸:数据密集的后台列表筛选场景优先
small(24px)以节省纵向空间;面向普通用户的表单页面用default(32px);需要视觉突出或移动端触控友好的场景可考虑large(40px); - 明确覆盖语义:当表单或紧凑布局已注入统一尺寸时,单独设置
nzSize不会生效,需通过调整父级表单/紧凑容器的尺寸来统一控制; - 模式全兼容:
nzSize对单选、多选、标签、可搜索等所有nzMode形态一致生效,可按 size.ts 的演示一次性验证四种形态下的视觉效果。
总而言之,nzSize 是一个"取值简单、生效链路清晰"的尺寸控制入口:三个枚举值对应三档高度,经由 finalSize 优先级链裁决后映射为 ant-select-lg / ant-select-sm 类名,最终由 Less 样式落地。理解这条链路,你就能在任何需要统一或微调选择器尺寸的场景中游刃有余。