NG-ZORRO Select 组件下拉弹出位置（nzPlacement）完整指南：从 Demo 到源码原理-开发者社区

UI组件
前端

【免费下载链接】ng-zorro-antd

Angular UI Component Library based on Ant Design

项目地址：https://gitcode.com/gh_mirrors/ng/ng-zorro-antd

导读

在 NG-ZORRO（ng-zorro-antd）中，nz-select下拉面板默认跟随触发元素底部展开，但在窄容器、页面底部或特殊布局中，开发者往往需要手动控制弹出方向与对齐方式。本文以官方 Demo 文档 placement.md 为骨架，完整讲解nzPlacement的四种取值、Demo 代码实战、与nzDropdownMatchSelectWidth的配合，并深入 select.component.ts 与核心 Overlay 层源码，揭示默认值、位置映射与自动避让的底层实现。读完本文，你将能够精确控制 Select 下拉面板的任意弹出位置，并理解其与 CDK Overlay 的协作机制。

一、placement 是什么：手动指定下拉弹出位置

原文档 placement.md 给出了最精炼的定义（zh-CN）：

可以通过placement手动指定弹出的位置。

对应到组件 API，即nz-select的nzPlacement输入属性。它的类型定义位于 select.types.ts：

export type NzSelectPlacementType = 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight';

即四种取值，语义如下：

取值	含义
`bottomLeft`	下拉面板在触发元素正下方，左对齐展开（默认值）
`bottomRight`	下拉面板在触发元素正下方，右对齐展开
`topLeft`	下拉面板在触发元素正上方，左对齐展开
`topRight`	下拉面板在触发元素正上方，右对齐展开

在组件声明中，该输入定义于 select.component.ts：

@Input() nzPlacement: NzSelectPlacementType | null = null;

注意默认值为null，而组件内部实际使用的默认弹出位置是bottomLeft（见下文源码分析），二者并不矛盾：null表示"未手动指定，交给自动避让逻辑"。

二、官方 Demo 完整实战：四种位置一键切换

官方演示组件 placement.ts 通过nz-radio-group切换四种位置，是最直观的实战参考。完整代码如下：

import { Component, signal } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { NzRadioModule } from 'ng-zorro-antd/radio'; import { NzSelectModule, NzSelectPlacementType } from 'ng-zorro-antd/select'; @Component({ selector: 'nz-demo-select-placement', imports: [FormsModule, NzRadioModule, NzSelectModule], template: ` <nz-radio-group [(ngModel)]="placement"> <label nz-radio-button nzValue="topLeft">topLeft</label> <label nz-radio-button nzValue="topRight">topRight</label> <label nz-radio-button nzValue="bottomLeft">bottomLeft</label> <label nz-radio-button nzValue="bottomRight">bottomRight</label> </nz-radio-group> <br /> <br /> <nz-select [(ngModel)]="value" [nzDropdownMatchSelectWidth]="false" [nzPlacement]="placement()"> <nz-option nzValue="HangZhou" nzLabel="HangZhou #310000" /> <nz-option nzValue="NingBo" nzLabel="NingBo #315000" /> <nz-option nzValue="WenZhou" nzLabel="WenZhou #325000" /> </nz-select> `, styles: ` nz-select { width: 120px; } ` }) export class NzDemoSelectPlacementComponent { readonly placement = signal<NzSelectPlacementType>('topLeft'); readonly value = signal('HangZhou'); }

2.1 代码要点拆解

[nzPlacement]="placement()"：将单选组选中的值实时绑定到 Select 的弹出位置。当用户点选topLeft时，下拉面板立即切换到上方左对齐展开；选bottomRight时切换到下方右对齐。由于信号（signal）驱动的响应式绑定，切换无需任何手动刷新。
[nzDropdownMatchSelectWidth]="false"：让下拉面板宽度不再强制等于触发元素宽度。Demo 中同时展示这一点，是为了在调整弹出位置时能更清晰地观察左右对齐差异（面板宽度大于 120px 的触发元素时，topLeft与topRight的对齐效果一目了然）。该参数与nzPlacement相互独立，可自由组合。
NzSelectPlacementType类型导入：直接从ng-zorro-antd/select导出，保证 signal 初始值与绑定类型一致，编译期即可捕获非法取值。
默认展示topLeft：Demo 初始值为topLeft，便于读者第一眼就看到与默认bottomLeft不同的上方弹出效果。

2.2 最小可运行模板

若只需固定一个方向，最简用法仅需一行属性绑定：

<nz-select nzPlacement="topRight" style="width: 200px"> <nz-option nzValue="HangZhou" nzLabel="HangZhou #310000" /> <nz-option nzValue="NingBo" nzLabel="NingBo #315000" /> </nz-select>

三、源码级原理：从 nzPlacement 到 CDK Overlay

3.1 输入变化的分发逻辑

nzPlacement的变更在 select.component.ts 的ngOnChanges中被处理：

if (nzPlacement) { const { currentValue } = nzPlacement; this.placement.set(currentValue); const listOfPlacement = ['bottomLeft', 'topLeft', 'bottomRight', 'topRight']; if (currentValue && listOfPlacement.includes(currentValue)) { this.positions = [POSITION_MAP[currentValue as POSITION_TYPE]]; } else { this.positions = listOfPlacement.map(e => POSITION_MAP[e as POSITION_TYPE]); } }

这段代码揭示了两个关键行为：

指定了合法位置（四种之一）时，positions只包含唯一的连接位置对，面板被"钉死"在指定方向，不做自动翻转；
nzPlacement为null或传入非法值时，positions依次注册全部四种位置（bottomLeft → topLeft → bottomRight → topRight），交给 CDK Overlay 的自动避让机制去选择最合适的落点。

3.2 位置映射表 POSITION_MAP

POSITION_MAP定义于核心 Overlay 模块 overlay-position.ts，它把topLeft、bottomRight等名称翻译成 CDK 的ConnectionPositionPair（分别描述触发元素侧连接点 originX/originY 与浮层侧连接点 overlayX/overlayY）。以 select 相关的四组为例：

topLeft: new ConnectionPositionPair({ originX: 'start', originY: 'top' }, { overlayX: 'start', overlayY: 'bottom' }), topRight: new ConnectionPositionPair({ originX: 'end', originY: 'top' }, { overlayX: 'end', overlayY: 'bottom' }), bottomLeft: new ConnectionPositionPair({ originX: 'start', originY: 'bottom' }, { overlayX: 'start', overlayY: 'top' }), bottomRight: new ConnectionPositionPair({ originX: 'end', originY: 'bottom' }, { overlayX: 'end', overlayY: 'top' }),

可见top*系列将浮层连接在触发元素上缘（originY: 'top'），并让浮层底边对齐（overlayY: 'bottom'），实现"向上弹出"；bottom*系列反之。左右对齐则由start/end（随文档方向 RTL/LTR 自动适配）决定。

3.3 默认位置与纵向偏移

组件内部的位置状态定义于 select.component.ts：

protected readonly placement = signal<NzSelectPlacementType>('bottomLeft');

即未手动指定时默认向下弹出（bottomLeft），这与主流 UI 习惯一致。同时，为了贴合 Ant Design 的视觉间距，模板通过 cdkConnectedOverlayOffsetY 依据当前方向设置纵向偏移：

[cdkConnectedOverlayOffsetY]="placement().startsWith('top') ? -4 : 4"

即向上弹出时浮层整体上移 4px、向下弹出时下移 4px，并对应绑定ant-select-dropdown-placement-topLeft/bottomLeft/...等样式类（见 select.component.ts），供主题样式区分方向。

3.4 实际位置的动态回写

当未指定位置、由 CDK 自动避让选择落点时，组件通过positionChange事件感知实际渲染位置并回写状态（select.component.ts）：

onPositionChange(position: ConnectedOverlayPositionChange): void { const placement = getPlacementName(position); this.placement.set(placement as NzSelectPlacementType); }

getPlacementName（见 overlay-position.ts）通过比对当前连接对与POSITION_MAP中每一项的 originX/originY/overlayX/overlayY，还原出topLeft这类名称，从而保证即便自动避让发生翻转，内部状态（以及偏移量、样式类）始终与实际视觉位置一致。

四、测试与边界行为验证

组件测试 select.spec.ts 中包含专门针对该场景的测试组件，其声明为：

readonly nzPlacement = signal<NzSelectPlacementType | null>('bottomLeft');

可据此验证两点边界行为：

合法取值：传入四种位置之一时，面板严格出现在对应方向；
null回退：当值为null时，组件退化为四种位置候选交由 CDK 自动避让，在页面底部等空间不足场景会自动翻转到上方，避免面板被视口裁切。

五、实战建议与注意事项

空间预判优先用自动避让：不要滥用固定nzPlacement。当页面空间可能不足时，保持nzPlacement为默认null（或合法值外的任意值），让 select.component.ts 注册的全候选位置列表生效，由 CDK 自动翻转，避免面板溢出视口。
固定位置用于特殊布局：在表格底部工具栏、模态框底部、或需要与其它浮层保持方向一致的场景中，显式指定nzPlacement（如topRight）可获得确定性表现。
与宽度参数配合：nzDropdownMatchSelectWidth（Demo 中设为false）决定面板宽度是否跟随触发元素。调整弹出位置时建议结合该参数观察对齐效果；二者无依赖关系，可按需自由组合。
类型安全：绑定动态值时使用NzSelectPlacementType类型（select.types.ts），编译期即可排除非法字符串。
RTL 方向：topLeft/topRight中的start/end连接点随文档方向自动适配，在 RTL 环境下左右对齐语义会自动翻转，无需额外处理。

六、小结

nzPlacement是 NG-ZORRO Select 组件控制下拉弹出位置的唯一入口，取值限定为topLeft、topRight、bottomLeft、bottomRight四种。其核心机制建立在 CDK Overlay 之上：指定位置时写入单候选ConnectionPositionPair锁定方向，未指定时注册全部候选交由自动避让，并通过onPositionChange动态回写实际落点以保持内部状态一致。结合官方 Demo placement.ts 与源码 select.component.ts、overlay-position.ts，开发者既可以快速上手固定方向的弹层布局，也能深入理解乃至定制 Overlay 层的连接策略。