企业官网建设流程全解析

• UI组件
• 前端

导读

nz-float-button（浮动按钮）是 ng-zorro-antd 提供的悬浮于页面边缘的全局操作按钮组件，而形状是其最直观的视觉属性之一。本文以官方 Demo「形状（Shape）」为核心，围绕nzShape属性展开：从最简单的圆形/方形切换、到两种形状在样式层与内容层的差异化实现、再到与nzType、nzIcon、nzDescription的组合用法，并结合组件源码与 Less 样式逐一印证，帮你彻底掌握浮动按钮形状相关的全部细节。

一、核心用法：一行代码切换形状

在 components/float-button/demo/shape.md 中，官方给出的使用方式极其简洁——通过nzShape设置不同的形状：

<nz-float-button nzShape="circle" style="inset-inline-end: 94px" nzType="primary" nzIcon="customer-service" /> <nz-float-button nzShape="square" style="inset-inline-end: 24px" nzType="primary" nzIcon="customer-service" />

对应的完整示例组件（见 components/float-button/demo/shape.ts）会渲染两个按钮：右侧为圆形，左侧为方形，二者都使用primary类型与customer-service图标，仅通过nzShape区分形状，直观展示同一配置在不同形状下的表现差异。

注意：Demo 中style="inset-inline-end: ..."用于让两个按钮在页面上水平错开，而容器.shape设置了position: relative与height: 300px，按钮本身使用position: absolute定位。这是 Demo 页面内部的布局技巧，并非组件自身的行为——组件默认是position: fixed悬浮在视口右下角。

属性签名与取值

nzShape在组件类中的定义如下（见 float-button.component.ts）：

readonly nzShape = input<NzShapeSCType>('circle');

• 取值：'circle' | 'square'，类型定义在 components/core/types/shape.ts 中，即NzShapeSCType = 'square' | 'circle'；
• 默认值：'circle'（圆形）。也就是说，不写nzShape时浮动按钮默认渲染为圆形；
• 模块引入：使用前需要在组件中导入NzFloatButtonModule（见 float-button.module.ts），或在 Standalone 场景下通过imports: [NzFloatButtonModule]引入。

二、形状在样式层如何生效：圆形与方形的实现差异

形状并非仅仅是"圆角大小"的差异，两种形状在尺寸、圆角、角标（Badge）位置等方面都有独立的样式规则，全部集中在 components/float-button/style/index.less 中。

圆形的关键规则

.@{float-btn-prefix-cls}-circle { height: @float-button-size; // 固定高度 40px border-radius: 50%; // 完全圆形 .@{ant-prefix}-badge .@{ant-prefix}-badge-dot { top: @dot-offset-in-circle; // 圆内角标偏移 5.6px inset-inline-end: @dot-offset-in-circle; } .ant-float-btn-inner, .@{float-btn-prefix-cls}-body { border-radius: 50%; } }

方形的关键规则

.@{float-btn-prefix-cls}-square { height: auto; // 高度自适应内容 min-height: @float-button-size; // 最小高度 40px border-radius: @border-radius-base; // 普通圆角 .@{ant-prefix}-badge .@{ant-prefix}-badge-dot { top: @dot-offset-in-square; // 方内角标偏移 1px inset-inline-end: @dot-offset-in-square; } .@{float-btn-prefix-cls}-body { height: auto; border-radius: @border-radius-base; } }

可以总结出四个关键差异：

1. 圆角：圆形使用border-radius: 50%，方形使用主题变量@border-radius-base；
2. 尺寸：圆形高度固定为@float-button-size（40px），方形为height: auto+min-height，允许内容（如文字描述）撑开高度；
3. 角标偏移：圆形与方形使用不同的 dot 偏移量（5.6px vs 1px），保证 Badge 在不同形状下的视觉位置协调；
4. 悬浮基准：组件默认position: fixed; inset-inline-end: 24px; bottom: 48px（见样式文件头部变量@float-button-inset-inline-end: 24px与@float-button-inset-block-end: @float-button-inset-inline-end * 2），Demo 中的绝对定位只是示例页面的局部调整。

此外，float-button.component.ts 中通过linkedSignal(() => this.nzShape())同步形状值，再借助generateClassName生成ant-float-btn-circle/ant-float-btn-square等宿主类名，从而让上述 Less 规则生效。

三、形状对内容的深层影响：为什么 nzDescription 只在方形中显示

形状不仅影响外观，还会影响内容的渲染逻辑。float-button-content.component.ts 中的模板揭示了这一细节：

@if (nzDescription() && nzShape() === 'square') { <div class="ant-float-btn-description"> <ng-container *nzStringTemplateOutlet="nzDescription()"> {{ nzDescription() }} </ng-container> </div> }

• 只有nzShape === 'square'时，nzDescription（文字描述）才会被渲染；
• 圆形按钮因空间受限，只渲染图标，即使传入了nzDescription也不会显示文字；
• 图标与描述同时传入时，圆形仅显示图标，方形则图标 + 文字纵向排列。

同时，nzIcon支持string | TemplateRef<void> | null两种形态：传字符串时通过nz-icon渲染 outline 主题图标；传TemplateRef时可自定义任意内容。若既没有图标也没有描述，组件会回退渲染默认的file-text图标（见 float-button-content.component.ts）。

因此，在选择形状时需注意：需要展示文字说明的场景应使用square，纯图标操作（如"返回顶部""客服"）则circle更紧凑。

四、组合实战：nzShape 与其它属性的搭配

nzShape通常不是孤立使用，以下是与 Demo 一致的完整属性组合（完整 API 见 components/float-button/doc/index.en-US.md）：

结合形状的完整示例

<!-- 圆形 + 主色 + 图标：适合纯图标入口 --> <nz-float-button nzShape="circle" nzType="primary" nzIcon="customer-service" /> <!-- 方形 + 默认色 + 图标与文字：适合带说明的入口 --> <nz-float-button nzShape="square" nzType="default" nzIcon="customer-service" nzDescription="在线客服" (nzOnClick)="onClick()" /> <!-- 方形 + 自定义角标（nzBadge 从 20.4.0 起可用） --> <nz-float-button nzShape="square" nzIcon="message" [nzBadge]="{ nzCount: 5, nzDot: false }" />

值得补充的两个关联能力（与形状同属 FloatButton 家族）：

• 分组场景：在nz-float-button-group中使用时，形状同样作用于组内按钮，且方形分组会产生纵向堆叠、按钮间以1px边框分隔的列表效果（见 style/index.less）；
• 角标位置：nzBadge的偏移在圆形（5.6px）与方形（1px）中不同，切换形状后角标会自动跟随形状微调，无需额外配置。

五、源码脉络与进一步探索

从源码结构看，FloatButton 模块由以下文件构成（公开 API 见 public-api.ts）：

• float-button.component.ts：nz-float-button主组件，定义nzShape等全部输入；
• float-button-content.component.ts：内容渲染组件，承载图标、描述与角标逻辑；
• float-button-group.component.ts：分组组件，支持nzTrigger/nzPlacement/nzOpen等；
• float-button-top.component.ts：回到顶部按钮，支持nzVisibilityHeight/nzTarget/nzDuration；
• typings.ts：NzFloatButtonType与NzFloatButtonBadge类型定义；
• style/index.less：形状、类型、分组、角标的全部样式规则。

官方文档还提供了 index.zh-CN.md 中文版，以及 basic.md、group.md、type.md 等系列 Demo，可以组合出"形状 + 类型 + 分组 + 回到顶部"的完整浮动交互方案。

小结

nzShape是nz-float-button中最直观的配置项之一，只需在'circle'与'square'之间切换即可获得完全不同的视觉与内容承载能力。理解它背后的三点——样式层圆角/尺寸/角标偏移的差异、内容层nzDescription仅方形渲染的约束、以及默认'circle'的取值——就能在实际项目中准确选用形状，避免"传了描述文字却不显示"之类的使用误区。

• UI组件
• 前端