ng-zorro-antd Button 按钮尺寸完全指南：从 nzSize 三档尺寸到源码级原理

• UI组件
• 前端

导读

本文围绕 ng-zorro-antd（Angular 版本的 Ant Design 组件库）中Button 按钮的尺寸体系展开，核心主题是nzSize属性如何将按钮在大（large）、中（default）、小（small）三档尺寸之间切换。你将学会在模板中为<button>与<a>设置尺寸、配合图标按钮与紧凑组合（nz-space-compact）使用的完整写法，并通过源码理解尺寸如何映射为 CSS 类、如何受全局配置与表单上下文影响。

一、三档尺寸：large/default/small

1.1 核心规则

按钮有大、中、小三种尺寸，通过设置nzSize为large或small分别把按钮设为大、小尺寸。若不设置nzSize，则尺寸为中（即default）。

• nzSize="large"：大尺寸，适合作为页面主 CTA、移动端触摸目标等强调场景；
• 省略nzSize（默认'default'）：中尺寸，绝大多数业务场景的默认选择；
• nzSize="small"：小尺寸，适合表格行内操作、紧凑工具栏等空间受限场景。

对应的类型定义位于 components/core/types/size.ts：

export type NzSizeLDSType = 'large' | 'default' | 'small';

而 Button 组件的nzSize输入正是这一类型，见 components/button/button.component.ts：

export type NzButtonSize = NzSizeLDSType; // ... @Input() @WithConfig() nzSize: NzButtonSize = 'default';

注意nzSize默认值为'default'，且带有@WithConfig()装饰器，意味着它支持通过全局配置（NZ_CONFIG）统一覆盖，详见下文第四节。

1.2 基础写法

对应官方演示源码位于 components/button/demo/size.ts，其核心片段如下：

readonly size = signal<NzButtonSize>('large');

<button nz-button [nzSize]="size()" nzType="primary">Primary</button> <button nz-button [nzSize]="size()" nzType="default">Default</button> <button nz-button [nzSize]="size()" nzType="dashed">Dashed</button> <a nz-button [nzSize]="size()" nzType="link">Link</a>

演示页面用一组nz-radio-group在large/default/small三档间切换，实时展示所有按钮类型（primary、default、dashed、link）随尺寸联动变化的效果。

二、尺寸在源码中的落地：CSS 类映射与计算链

2.1 从nzSize到ant-btn-lg/ant-btn-sm

nzSize并不会直接控制像素值，而是通过 host 绑定把尺寸翻译成 CSS 类，由 Less 样式决定最终视觉效果。见 components/button/button.component.ts：

'[class.ant-btn-lg]': `finalSize() === 'large'`, '[class.ant-btn-sm]': `finalSize() === 'small'`,

当最终尺寸为large时追加ant-btn-lg，为small时追加ant-btn-sm；default时两个类都不加，保持基础类ant-btn即可。

对应的样式定义在 components/button/style/index.less：

&-lg { line-height: @btn-height-lg - 2px; } &-sm { line-height: @btn-height-sm - 2px; }

具体的高宽、内边距、字号等尺寸变量由 components/button/style/mixin.less 中的button-sizemixin 统一注入：

&-lg { .button-size(@btn-height-lg; @btn-padding-horizontal-lg; @btn-font-size-lg; @btn-border-radius-base); } &-sm { .button-size(@btn-height-sm; @btn-padding-horizontal-sm; @btn-font-size-sm; @btn-border-radius-sm); }

这些@btn-height-lg、@btn-height-sm等 Less 变量来自组件库的全局主题变量体系，因此按钮尺寸可以随主题定制（如紧凑主题ng-zorro-antd.compact.less、暗色主题ng-zorro-antd.dark.less、变量主题ng-zorro-antd.variable.less）联动变化。

2.2 测试用例验证

尺寸类名的映射行为有明确的单元测试保障，见 components/button/button.spec.ts：

it('should apply classname based on nzSize', () => { component.nzSize.set('large'); fixture.detectChanges(); expect(buttonElement.classList).toContain('ant-btn-lg'); component.nzSize.set('small'); fixture.detectChanges(); expect(buttonElement.classList).toContain('ant-btn-sm'); component.nzSize.set('default'); fixture.detectChanges(); expect(buttonElement.className).toBe('ant-btn'); });

该用例确认了三件事：large→ 追加ant-btn-lg，small→ 追加ant-btn-sm，default→ 不追加任何尺寸类。

2.3finalSize()：尺寸的最终裁决

组件内部并不是直接读取nzSize，而是通过一个computed信号finalSize()计算最终生效的尺寸，其优先级如下，见 components/button/button.component.ts：

protected readonly finalSize = computed(() => { if (this.formSize?.()) { return this.formSize(); } if (this.compactSize) { return this.compactSize(); } return this.size(); });

• 表单上下文（NZ_FORM_SIZE）优先级最高：当按钮处于nz-form-control中且表单配置了尺寸时，按钮尺寸会跟随表单尺寸；
• 紧凑组合（NZ_SPACE_COMPACT_SIZE）次之：按钮位于nz-space-compact内且该组合设置了尺寸时，跟随组合尺寸；
• 自身nzSize兜底：以上两种情况都不存在时，才使用按钮自身设置的尺寸。

从源码结构可以推断，这是 ng-zorro-antd 组件库"尺寸联动"设计的一部分：表格、表单、紧凑工具栏中的按钮无需逐个设置，即可保持视觉一致。

三、图标按钮与紧凑组合中的尺寸表现

3.1 纯图标按钮的尺寸

尺寸对纯图标按钮同样生效，官方演示中涵盖了四种形态，见 components/button/demo/size.ts：

<button nz-button nzType="primary" [nzSize]="size()"> <nz-icon nzType="download" /> </button> <button nz-button nzType="primary" [nzSize]="size()" nzShape="circle"> <nz-icon nzType="download" /> </button> <button nz-button nzType="primary" [nzSize]="size()" nzShape="round"> <nz-icon nzType="download" /> </button> <button nz-button nzType="primary" [nzSize]="size()"> <nz-icon nzType="download" /> Download </button>

• 不带文字、仅含一个<nz-icon>的按钮会呈现为图标按钮（组件通过iconOnly计算并追加ant-btn-icon-only类）；
• nzShape="circle"圆形图标按钮与nzShape="round"圆角图标按钮的尺寸同样跟随nzSize，圆形与方形图标按钮在 large / small 下的直径与图标字号由 components/button/style/mixin.less 的&-lg/&-sm规则分别处理。

3.2 紧凑组合 nz-space-compact 的尺寸联动

官方演示还展示了nz-space-compact组合按钮（如"Backward / Forward"分步操作条）在nzSize下的表现：

<nz-space-compact [nzSize]="size()"> <button nz-button nzType="primary"> <nz-icon nzType="left" /> Backward </button> <button nz-button nzType="primary"> Forward <nz-icon nzType="right" /> </button> </nz-space-compact>

nz-space-compact通过NZ_SPACE_COMPACT_SIZE注入器向其内部子组件广播尺寸，见 components/space/space-compact.component.ts：

readonly nzSize = input<NzSizeLDSType>('default'); protected readonly finalSize = computed(() => this.formSize?.() || this.nzSize());

按钮组件通过hostDirectives: [NzSpaceCompactItemDirective]与providers声明自己属于紧凑组合的按钮项（NZ_SPACE_COMPACT_ITEM_TYPE值为'btn'），从而接收组合级尺寸。这也解释了finalSize()中compactSize的优先级逻辑。nz-space-compact的nzSize支持'large' | 'small' | 'default'三档，见 components/space/doc/index.en-US.md。

四、全局配置：让"尺寸"成为站点级统一约束

nzSize带有@WithConfig()标记（components/button/button.component.ts），因此可以通过NZ_CONFIG全局配置统一指定所有 Button 的默认尺寸，而不必在每个按钮上重复书写。组件构造函数中注册了配置变更监听，见 components/button/button.component.ts：

onConfigChangeEventForComponent(NZ_CONFIG_MODULE_NAME, () => { this.size.set(this.nzSize); this.cdr.markForCheck(); });

也就是说，运行时修改全局button.nzSize配置，已渲染的按钮也会随之刷新尺寸。这在站点级换肤、统一收紧/放大按钮密度的场景下非常实用。

五、实用建议与注意事项

1. 省略即默认：不需要中尺寸时无需显式写nzSize="default"，省略即可；但若你的模板中已有动态绑定的[nzSize]，注意空值会回落为组件默认值'default'。
2. 尺寸优先级记忆：按钮自身nzSize< 紧凑组合nz-space-compact的nzSize< 表单nz-form-control上下文尺寸。若发现按钮尺寸"不听话"，先检查它是否处于上述容器中。
3. 配合全局配置做站点级控制：如需统一调整所有按钮尺寸，优先通过NZ_CONFIG的button.nzSize配置，而不是逐个修改模板。
4. 尺寸与形状正交组合：nzSize（large/default/small）与nzShape（circle/round）、nzType（primary/default/dashed/link/text）、nzBlock、nzLoading、nzDanger等属性相互独立、自由组合，API 全表见 components/button/doc/index.en-US.md。
5. 验证入口：行为级验证可直接运行 components/button/button.spec.ts 中的should apply classname based on nzSize用例；视觉层验证可运行官方演示 components/button/demo/size.ts，在large / default / small三档间切换观察所有按钮形态。

六、快速参考

说明：ng-zorro-antd 的尺寸类型统一由 components/core/types/size.ts 的NzSizeLDSType定义，除 Button 外，其他组件（如 components/space/space-compact.component.ts、表单等）复用同一套尺寸语义，理解本文的优先级规则即可触类旁通。

• UI组件
• 前端