ng-zorro-antd Select 尺寸指南:nzSize 的 large / default / small 三种大小与实现原理

原创2026-09-27 14:22:221,603 阅读
文章标签:UI组件前端

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 });   // 紧凑布局尺寸令牌

由此可以推断并总结出三条实践结论:

  1. 当 Select 位于 nz-form-item 等表单上下文中,且表单整体配置了尺寸时,表单注入的尺寸会覆盖组件上的 nzSize;
  2. 当 Select 作为 nz-space-compact(紧凑组合布局)的子元素时,紧凑尺寸同样优先于 nzSize;
  3. 只有在表单与紧凑布局都没有注入尺寸的情况下,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 样式落地。理解这条链路,你就能在任何需要统一或微调选择器尺寸的场景中游刃有余。

登录后查看全文
ng-zorro-antd