企业官网建设流程全解析

• UI组件
• 前端

导读：nz-select是 ng-zorro-antd 提供的下拉选择组件，是原生<select>元素的优雅替代品，同时支持单选（default）、多选（multiple）与标签（tags）三种模式，并深度集成 Angular 表单体系（ngModel/ 响应式表单）。本文将围绕官方文档（components/select/doc/index.en-US.md）的完整 API，结合仓库源码（select.component.ts）与全部 21 个官方 demo，带你掌握从基础用法、搜索过滤、自定义模板到大数据虚拟滚动的完整实战方案，并理解其底层实现原理。

一、何时使用 Select

官方文档给出了三个明确的使用场景判断标准：

1. 下拉菜单展示选项：当需要在一个紧凑控件中展示一组可选值时，nz-select是比原生<select>更优雅的选择，支持搜索、标签化多选、自定义渲染等能力。
2. 选项少于 5 个时，优先考虑 Radio 组件：选项极少时单选按钮组的信息密度与可扫视性更好。
3. 需要"既可输入又可选择"时，改用 AutoComplete 组件：nz-select的搜索只是对已有选项的过滤，而 AutoComplete 面向的是自由输入 + 联想候选的场景。

二、快速开始：最小可用示例

先看官方 demo（basic.ts）中提炼出的最小结构：

<nz-select ngModel="lucy"> <nz-option nzValue="jack" nzLabel="Jack" /> <nz-option nzValue="lucy" nzLabel="Lucy" /> <nz-option nzValue="disabled" nzLabel="Disabled" nzDisabled /> </nz-select>

要点：

• 使用前需在模块中导入NzSelectModule（见 select.module.ts），并在组件imports中同时引入FormsModule（配合模板驱动表单）或ReactiveFormsModule。
• 子选项通过<nz-option>声明，核心属性是nzValue（实际绑定到ngModel的值）与nzLabel（界面展示的文本）。
• 更多基础状态组合（禁用、加载、可清除、占位符）参考官方 demo basic.md：

<nz-select ngModel="lucy" nzDisabled> <nz-option nzValue="lucy" nzLabel="Lucy" /> </nz-select> <nz-select ngModel="lucy" nzLoading> <nz-option nzValue="lucy" nzLabel="Lucy" /> </nz-select> <nz-select ngModel="lucy" nzAllowClear nzPlaceHolder="Choose"> <nz-option nzValue="lucy" nzLabel="Lucy" /> </nz-select>

三、nz-select 完整 API 手册

以下属性表完整继承自官方文档，并结合源码（select.component.ts）中的实际@Input/@Output声明做了补充注释。默认值列标记 ✅ 表示支持通过NZ_CONFIG全局配置覆盖（源码中该属性使用@WithConfig()装饰器，模块名称为'select'）。

3.1 输入属性（nz-select）

源码补充：上述属性中带booleanAttribute变换的（如nzAllowClear、nzShowSearch、nzLoading、nzAutoFocus、nzAutoClearSearchValue、nzServerSearch、nzDisabled、nzOpen、nzSelectOnTab、nzBackdrop、nzShowArrow），在模板中可以省略[ ]直接写布尔属性名（如nzDisabled）。nzMaxMultipleCount使用numberAttributeWithInfinityFallback变换，未设置时回退为Infinity，见 select.component.ts。

3.2 输出事件（nz-select）

源码中事件在 select.component.ts 声明，其中nzOnClear使用 Angular 新的output()函数式声明，其余为EventEmitter。焦点事件通过 CDK 的FocusMonitor监控宿主元素触发（见 select.component.ts），失焦时还会调用onTouched()完成表单 touched 状态上报。

3.3 实例方法

方法在源码中委托给内部nz-select-top-control组件实现（select.component.ts），通过模板引用变量调用：<nz-select #select />后select.focus()。

四、nz-option 与 nz-option-group API

4.1 nz-option

声明式选项组件，源码见 option.component.ts，其模板仅是一个<ng-template>包裹的<ng-content />，意味着选项内容本质是可投影的内容。

nzKey 的源码依据：在 select.component.ts 的选项归一化逻辑中，key: nzKey === undefined ? nzValue : nzKey——未显式传入nzKey时默认以nzValue作为键；当nzValue是对象时（对象引用不稳定），显式传入nzKey可保证track与比较的高效与稳定。类型定义见 select.types.ts。

4.2 nz-option-group

分组容器，源码见 option-group.component.ts。

组合用法（官方 demo optgroup.ts）：

<nz-select ngModel="lucy" nzAllowClear nzPlaceHolder="Choose" nzShowSearch> <nz-option-group nzLabel="Manager"> <nz-option nzValue="jack" nzLabel="Jack" /> <nz-option nzValue="lucy" nzLabel="Lucy" /> </nz-option-group> <nz-option-group nzLabel="Engineer"> <nz-option nzValue="tom" nzLabel="Tom" /> </nz-option-group> </nz-select>

分组渲染原理：nz-option-group内部也维护一个changes主题（option-group.component.ts），nz-option在ngOnInit时订阅其父级分组的nzLabel并同步到自身groupLabel字段（option.component.ts）；随后 select 组件把同一groupLabel的选项组织成带分组头（type: 'group'）的容器项序列（select.component.ts）。

五、三种模式详解：default / multiple / tags

nzMode支持三种取值（类型定义见 select.types.ts），组件通过isMultiple判断是否为多选类模式（select.component.ts）。

5.1 单选模式（default）

默认行为：点击选中后自动收起下拉。源码中onItemClick对default模式先比较新旧值再updateListOfValue([value])，随后立即setOpenState(false)关闭面板（select.component.ts）。

5.2 多选模式（multiple）

选项以标签（tag）形式平铺展示，支持选中/取消、移除标签。参考官方 demo multiple.ts，配合nzMaxTagCount与nzMaxTagPlaceholder控制标签显示数量：

<nz-select [nzOptions]="options" [nzMaxTagCount]="3" [nzMaxTagPlaceholder]="tagPlaceHolder" nzMode="multiple" nzAllowClear nzPlaceHolder="Please select" [(ngModel)]="value" /> <ng-template #tagPlaceHolder let-selectedList>and {{ selectedList.length }} more selected</ng-template>

nzMaxTagPlaceholder模板的$implicit上下文是超出部分的已选值数组。多选模式与nzMaxMultipleCount组合可限制最大选择数（官方 demo max-count.ts）：[nzMaxMultipleCount]="3"。源码中当已达上限时isMaxMultipleCountReached为true，onItemClick中listOfValue.length < this.nzMaxMultipleCount的条件会阻止继续添加（select.component.ts），onTokenSeparate中也会通过limitWithinMaxCount对分词批量添加做截断（select.component.ts）。

5.3 标签模式（tags）

与 multiple 的区别：允许输入任意文本创建新选项。官方 demo tags.ts：

<nz-select [nzOptions]="options" nzMode="tags" nzPlaceHolder="Tag Mode" />

源码实现位于updateListOfContainerItem（select.component.ts）：当nzMode === 'tags'且存在搜索词时，会先查找已存在的匹配选项；若无匹配，则通过generateTagItem把输入文本包装成临时标签项并置顶展示。选中后该标签会通过listOfTagItem分支持久化为真实选中值（select.component.ts）。

自动分词（官方 demo automatic-tokenization.ts）：设置[nzTokenSeparators]="[',']"后，粘贴或输入带分隔符的文本会自动拆分为多个标签。核心逻辑在tokenSeparate方法（select-top-control.component.ts）：检测输入串末段是否包含分隔符，命中则按正则拆分并去重，触发tokenize事件交给外层 select 落库。

六、搜索与过滤：本地过滤与远程搜索

6.1 本地搜索（nzShowSearch）

单选模式设置nzShowSearch即出现搜索框（官方 demo search.ts）：

<nz-select [nzOptions]="options" nzShowSearch nzAllowClear nzPlaceHolder="Select a person" />

过滤由默认的defaultFilterOption实现（select.component.ts）：将选项nzLabel转为小写后判断是否包含搜索词。可用[nzFilterOption]替换为自定义过滤函数，函数签名为(input: string, option: NzSelectItemInterface) => boolean（select.types.ts）。

6.2 远程搜索（nzServerSearch + nzOnSearch）

当数据量很大或需服务端检索时，设置nzServerSearch关闭本地过滤，配合(nzOnSearch)发起请求（官方 demo search-box.ts）：

<nz-select [nzOptions]="options()" nzShowSearch nzServerSearch nzPlaceHolder="input search text" [nzShowArrow]="false" [nzFilterOption]="filterFn" (nzOnSearch)="search($event)" />

组件侧的过滤条件判断位于updateListOfContainerItem（select.component.ts）：if (!this.nzServerSearch && this.searchValue)才执行本地过滤，因此服务端模式下只需让nzFilterOption恒返回true（demo 中filterFn = () => true），所有筛选交由远程接口完成。更完整的异步示例见 select-users.ts，它使用BehaviorSubject + debounceTime(500) + switchMap组合实现输入防抖与竞态取消，加载期间通过nz-option nzDisabled nzCustomContent渲染 "Loading Data..." 占位项。

七、自定义渲染：模板、内容与下拉菜单

7.1 nzCustomTemplate：定制已选中项外观

官方 demo custom-template.ts，用图标 + 文本渲染选中项：

<nz-select nzAllowClear nzPlaceHolder="Select OS" [nzCustomTemplate]="defaultTemplate"> <nz-option nzLabel="Windows" nzValue="windows" /> <nz-option nzLabel="Apple" nzValue="apple" /> <nz-option nzLabel="Android" nzValue="android" /> </nz-select> <ng-template #defaultTemplate let-selected> <nz-icon [nzType]="selected.nzValue" /> {{ selected.nzLabel }} </ng-template>

模板上下文$implicit是当前选中的选项对象（含nzValue、nzLabel等字段）。该模板在nz-select-top-control中通过contentTemplateOutlet管道注入渲染（select-top-control.component.ts）。

7.2 nzCustomContent：定制下拉选项内容

官方 demo custom-content.ts，在<nz-option>内直接放置自定义内容：

<nz-select nzShowSearch nzAllowClear nzPlaceHolder="Select OS"> <nz-option nzCustomContent nzLabel="Windows" nzValue="windows"> <nz-icon nzType="windows" /> Windows </nz-option> <nz-option nzCustomContent nzLabel="Mac" nzValue="mac"> <nz-icon nzType="apple" /> Mac </nz-option> </nz-select>

开启nzCustomContent后，下拉中的选项内容用投影的 ng-content 替换纯文本nzLabel；而顶部已选区域仍使用nzLabel文本。注意：nzCustomContent模式下<nz-option>内容默认处于惰性<ng-template>中，仅在下拉渲染时实例化。

7.3 nzDropdownRender：扩展下拉菜单底部

官方 demo custom-dropdown-menu.ts，在下拉底部追加"新增选项"入口：

<nz-select nzShowSearch nzAllowClear [nzDropdownRender]="renderTemplate" nzPlaceHolder="custom dropdown render"> @for (item of listOfItem(); track item) { <nz-option [nzLabel]="item" [nzValue]="item" /> } </nz-select> <ng-template #renderTemplate> <nz-divider /> <div class="container"> <input type="text" nz-input #inputElement /> <a class="add-item" (click)="addItem(inputElement)"> <nz-icon nzType="plus" /> Add item </a> </div> </ng-template>

组件侧将nzDropdownRender模板透传给nz-option-container的dropdownRender输入（select.component.ts）。注意nzDropdownRender未出现在文档表格中，但它与nzDropdownClassName、nzDropdownMatchSelectWidth、nzDropdownStyle、nzPlacement一样属于源码中实际支持的输入（select.component.ts），可放心使用。

7.4 无匹配结果占位

[nzNotFoundContent]接受字符串或模板，默认显示'Not Found'。与之配合的经典场景是"隐藏已选项"：官方 demo hide-selected.ts 通过[nzHide]="isSelected(option)"让已选项从列表中消失（源码中updateListOfContainerItem第一步即过滤nzHide项，见 select.component.ts）。

八、数据驱动：nzOptions 与默认值技巧

8.1 用 nzOptions 替代子选项

组件允许完全以数据驱动方式传参（官方 demo tags.ts 等大量使用）：

readonly options = [ { label: 'Jack', value: 'jack' }, { label: 'Lucy', value: 'lucy' }, { label: 'Disabled', value: 'disabled', disabled: true } ];

<nz-select [nzOptions]="options" [(ngModel)]="value" />

当检测到nzOptions输入变化时，组件进入"响应式驱动"分支（isReactiveDriven = true），把数组逐项归一化为内部项结构（select.component.ts），支持label（可为TemplateRef）、value、key、disabled、hide、groupLabel等字段，字段类型定义见 select.types.ts。label为TemplateRef时自动映射为自定义渲染模板。

8.2 保留不在候选中的默认值

官方 demo default-value.ts：当默认值对应的选项不在候选列表中时，用nzHide的隐藏选项"挂载"默认值，使其既能在选中区显示、又不进入下拉列表：

<nz-select nzMode="multiple" nzPlaceHolder="Inserted are removed" [(ngModel)]="listOfSelectedValue"> @for (option of listOfOption; track option) { <nz-option [nzLabel]="option" [nzValue]="option" /> } @for (option of defaultOption; track option) { <nz-option [nzLabel]="option" [nzValue]="option" nzHide /> } </nz-select>

8.3 级联联动

官方 demo coordinate.ts：省份-城市二级联动，核心是监听第一个 select 的(ngModelChange)重置第二个 select 的值，纯数据驱动即可实现，无需引入状态管理。

九、大数据场景：虚拟渲染与滚动加载

9.1 万级选项的虚拟列表

官方 demo big-data.ts 演示了 10,000 条选项的渲染：

readonly options = alphabet(10000).map(item => ({ label: item, value: item }));

<nz-select nzMode="multiple" nzPlaceHolder="Please select" [nzOptions]="options" [(ngModel)]="value" />

其性能基础是nzOptionHeightPx与nzOptionOverflowSize两个参数（均可在 select.component.ts 找到定义）：

• nzOptionHeightPx（默认32）：每个选项的固定高度，是虚拟滚动计算可视窗口的依据；
• nzOptionOverflowSize（默认8）：可视区域外上下各保留渲染的缓冲条数，超出部分不进入 DOM。

它们与nzDropdownMatchSelectWidth、nzNotFoundContent等一起透传给nz-option-container（select.component.ts），由内部基于固定高度 + 缓冲区的窗口化策略实现大列表流畅滚动。

9.2 滚动到底部分页加载

官方 demo scroll-load.ts，配合(nzScrollToBottom)事件做增量加载：

<nz-select [nzOptions]="options()" (nzScrollToBottom)="loadMore()" nzPlaceHolder="Select users" nzAllowClear [nzDropdownRender]="renderTemplate" /> <ng-template #renderTemplate> @if (loading()) { <nz-spin /> } </ng-template>

nzScrollToBottom事件在 select.component.ts 由nz-option-container的scrollToBottom输出直连触发，配合nzDropdownRender注入的<nz-spin />即可实现"滚动到底 → 加载更多 → 更新选项"的完整闭环。

十、表单集成与键盘交互

10.1 ControlValueAccessor 实现

NzSelectComponent实现了ControlValueAccessor，并通过NG_VALUE_ACCESSOR注册（select.component.ts），因此可无缝用于模板驱动表单（[(ngModel)]）与响应式表单（formControlName/formControl）。关键实现点：

• writeValue：外部值写入时按模式归一化——单选转数组、多选保持数组、null/undefined转空数组（select.component.ts）；
• updateListOfValue：内部值变更时反向转换并调用onChange（单选取数组首个元素，否则返回整个数组）（select.component.ts）；
• setDisabledState：支持表单驱动的禁用状态同步（select.component.ts）。

10.2 键盘操作

内置完整键盘导航（onKeyDown，见 select.component.ts）：

10.3 视觉变体与尺寸

• nzVariant（20.0.0 起）：outlined（默认，带边框）、filled（填充背景）、borderless（无边框）、underlined（下划线式），宿主类名映射见 select.component.ts；官方 demo variant.ts 展示了四种变体在单选/多选下的效果。finalVariant计算逻辑为组件自身设置优先，其次表单级NZ_FORM_VARIANT，最后回退'outlined'（select.component.ts）。
• nzSize：large/default/small，官方 demo size.ts 演示了三种尺寸 × 四种形态的组合；finalSize依次回退formSize→compactSize→ 自身nzSize（select.component.ts），这意味着放入nz-form或nz-space-compact时尺寸可被父级统一接管。
• nzStatus：error/warning校验状态（官方 demo status.ts），由setStatusStyles写入宿主 class（select.component.ts）。
• nzPrefix/nzSuffixIcon：前后缀自定义（官方 demo prefix-and-suffix.ts），后缀图标同时支持TemplateRef与图标名字符串；前缀在nz-select-top-control模板中通过nzStringTemplateOutlet渲染（select-top-control.component.ts）。

十一、常见问题（FAQ）

Q：滚动时 overlay 浮层不跟随滚动位置？

这是下拉面板与滚动容器关系的问题。默认情况下，overlay 浮层以body作为滚动容器；如果你的 select 位于某个自定义滚动容器内，需要给该容器元素加上 CDK 的CdkScrollable指令，overlay 才能感知其滚动并跟随定位。同时必须从@angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块。ng-zorro-antd 的 select 正是基于 Angular CDK 的CdkConnectedOverlay实现定位（模板中的cdkConnectedOverlay相关绑定见 select.component.ts），因此对滚动容器的要求与 CDK overlay 体系完全一致。

Q：下拉宽度与 select 不一致？

默认nzDropdownMatchSelectWidth为true，下拉与触发器等宽。该值由updateCdkConnectedOverlayStatus在每次展开时通过getBoundingClientRect()测量触发宽度后通过requestAnimationFrame同步到 overlay（select.component.ts）。设为false时可让下拉按内容自适应。

Q：为什么推荐为对象值传入 nzKey？

对象作为nzValue时，默认以对象引用作为 track 键；若选项对象在数据刷新后重建，会导致不必要的重渲染与比较失效。传入稳定的nzKey（如 id）后，组件会以nzKey作为键参与track与去重（select.component.ts），配合自定义compareWith（如按o1.value === o2.value比较，见官方 demo label-in-value.ts）即可稳妥地让"label-in-value"（整个对象作为选中值）的方案正常工作。

十二、源码地图：快速定位实现

组件的内部结构由一组子组件协作完成：nz-select-top-control（选中区）、nz-select-arrow（箭头/加载/校验反馈图标）、nz-select-clear（清除按钮）、nz-option-container（下拉面板）共同拼装，全部通过模板在 select.component.ts 中按条件渲染；选择值模型统一以内部数组listOfValue管理，再按模式转换为表单模型输出，这正是三种模式行为统一、代码复用度高的原因。结合本文的 API 手册与官方 demo，你可以在不阅读全部源码的情况下快速落地绝大多数实际场景；遇到边界行为时，顺着上面的源码地图即可直达对应实现。

• UI组件
• 前端