企业官网建设流程全解析

• UI组件
• 前端

导读

在 ng-zorro-antd（Angular UI 组件库，基于 Ant Design 设计体系）中，nz-select的nz-option提供nzHide属性，用于把某个选项从下拉列表中隐藏。本文以官方示例 hide-selected.md 为主干，讲解多选模式下“已选即隐藏”的经典实现、nzHide的底层原理（option.component.ts、select.component.ts），并结合nzOptions对象数组与“默认值不在选项列表中”等场景给出完整可运行的写法。读完你可以掌握nzHide的三种典型用法，并理解其与nzDisabled、过滤搜索的差异。

1. 场景与核心思路

nzHide的中文文档描述极为简洁：通过nzHide隐藏下拉列表中已选择的选项（见 hide-selected.md）。

它要解决的问题非常具体：当nz-select处于multiple（多选）或tags（标签）模式时，用户每选中一个选项，该选项仍然停留在下拉列表中；在选项数量较多的场景下，这会增加视觉噪音、干扰后续选择。通过把“已经被选中”的选项动态标记为隐藏，下拉列表就只呈现尚未被选择的候选，让选择过程更聚焦。

这一特性的本质是“由数据驱动的可见性控制”：选项是否可见不再写死在模板里，而是由组件的选择状态实时计算得出。最典型的实现方式是定义一个isSelected(value)判断函数，把它绑定到每个nz-option的[nzHide]上。

2. 官方示例逐步拆解

官方示例文件为 hide-selected.ts，完整代码如下：

import { Component, signal } from '@angular/core'; import { FormsModule } from '@angular/forms'; import { NzSelectModule } from 'ng-zorro-antd/select'; @Component({ selector: 'nz-demo-select-hide-selected', imports: [FormsModule, NzSelectModule], template: ` <nz-select nzMode="multiple" nzPlaceHolder="Inserted are removed" [(ngModel)]="listOfSelected"> @for (option of listOfOption; track option) { <nz-option [nzLabel]="option" [nzValue]="option" [nzHide]="isSelected(option)" /> } </nz-select> `, styles: ` nz-select { width: 100%; } ` }) export class NzDemoSelectHideSelectedComponent { readonly listOfOption = ['Apples', 'Nails', 'Bananas', 'Helicopters']; readonly listOfSelected = signal<string[]>([]); isSelected(value: string): boolean { return this.listOfSelected().indexOf(value) !== -1; } }

2.1 模板层：三个关键绑定

• nzMode="multiple"：开启多选模式。隐藏已选选项只在多选/标签等“可同时选中多个值”的场景下才有意义，单选模式下用户每次只能选中一个，已选项被隐藏反而会让人困惑。
• [(ngModel)]="listOfSelected"：双向绑定当前已选中的值集合（字符串数组）。
• [nzHide]="isSelected(option)"：对每一个渲染出来的nz-option，动态计算“它是否已被选中”。选中即隐藏。

2.2 组件类：用 signal 管理状态

示例使用 Angular 16+ 的signal存放选中集合：readonly listOfSelected = signal<string[]>([])，isSelected()通过indexOf判断传入值是否已存在于选中集合中。当用户勾选或取消某个选项时，ngModel更新 signal 的值，模板中的[nzHide]绑定随之重新求值，下拉列表即时刷新——无需手动订阅事件或调用刷新方法。

注意：isSelected每次变更检测都会重新执行（这里数据集很小，开销可忽略）；若选项数以万计，可考虑用Set或记忆化函数优化判断性能（这也呼应了官方文档中big-data场景对渲染性能的重视，可参考 big-data.md）。

3. 底层原理：nzHide是如何让选项“消失”的

3.1 属性定义与布尔转换

nzHide定义在 option.component.ts 的NzOptionComponent上：

@Input() nzLabel: string | number | null = null; @Input() nzValue: NzSafeAny | null = null; @Input() nzKey?: string | number; @Input({ transform: booleanAttribute }) nzDisabled = false; @Input({ transform: booleanAttribute }) nzHide = false; @Input({ transform: booleanAttribute }) nzCustomContent = false;

关键点：

• 默认值为false，即默认所有选项都可见；
• 通过booleanAttribute做输入转换，因此模板中既可以写[nzHide]="isSelected(option)"这种表达式绑定，也可以直接写裸属性nzHide（等价于传true，官方 default-value.ts 中即使用了<nz-option ... nzHide />的写法）；
• 每当nzHide变化，ngOnChanges会触发this.changes.next()（option.component.ts），通知 select 组件重新计算选项列表。

3.2 组件树：nzHide在哪里被消费

NzOptionComponent自身不渲染可见的 DOM（其模板仅是一个<ng-template>容器），真正的下拉列表由 select 组件内部的option-container/option-item等子组件渲染。nzHide的消费路径如下：

1. 模板模式下，nz-option的输入（含nzHide）被收集进NzSelectItemInterface结构，存入列表；
2. 响应式模式下，nzOptions对象数组中的hide字段被映射为nzHide，见 select.component.ts 中的nzHide: item.hide || false；
3. 下拉容器在计算“当前应显示的选项”时，第一道过滤就是剔除nzHide为真的条目，见 select.component.ts：

updateListOfContainerItem(): void { let listOfContainerItem = this.listOfTagAndTemplateItem .filter(item => !item.nzHide) // 已隐藏的选项直接出局 .filter(item => { // 有搜索词时再按 nzFilterOption 过滤 ... }); ... }

可以推断，nzHide的过滤发生在搜索过滤之前：一个选项只要被标记隐藏，无论搜索词是什么都不会再出现；后续的激活项计算（activatedValue等）也全部基于这个过滤后的列表进行，因此隐藏选项既不会出现在下拉菜单中，也不会成为键盘导航的候选目标。

3.3 类型定义

在 select.types.ts 中，NzSelectOptionInterface定义了hide?: boolean可选字段，与组件输入的nzHide一一对应。这意味着nzHide同时存在于模板驱动（nz-option标签）与响应式/对象驱动（[nzOptions]）两条使用路径中。

4. 三种典型用法

4.1 用法一：多选模式下隐藏已选选项（官方示例）

即第 2 节给出的完整写法，适合选项多、需要连续多次选择的场景（例如批量标签筛选）。

4.2 用法二：默认值不在选项列表中（官方 default-value 示例）

官方 default-value.md 明确说明：当需要显示默认值，同时默认值又不在选项列表中时，可以使用nzHide在nz-option中将默认选项隐藏。对应源码 default-value.ts：

<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> <nz-select [(ngModel)]="value"> @for (option of listOfOption; track option) { <nz-option [nzLabel]="option" [nzValue]="option" /> } <nz-option nzLabel="Default Value" nzValue="Default" nzHide /> </nz-select>

这里的nzHide（裸属性写法）用于注册一个“看得见结果、但不在候选列表里”的合法值：选中后它出现在顶部标签/选择框中，却不会污染下拉列表。这是“隐藏已选”思路的镜像用法——隐藏的是候选，而非已选结果。

4.3 用法三：[nzOptions]对象数组驱动的响应式写法

不使用nz-option标签，而是通过[nzOptions]传入对象数组时，在对象上设置hide: true即可，见 select.component.ts 的映射逻辑nzHide: item.hide || false：

const options = [ { label: 'Apples', value: 'Apples' }, { label: 'Nails', value: 'Nails', hide: true } // 已选后置为 true，即从下拉列表消失 ];

适合数据由服务端或表单状态集中管理的场景，可以把“选中即隐藏”的逻辑直接放进数据层计算。

5. 与其他选项属性的边界

官方 API 文档 index.en-US.md 对nz-option各属性定义如下（节选与本主题相关者）：

需要特别区分的是nzDisabled与nzHide：

• nzDisabled只是禁用：选项仍显示在下拉列表中，只是不可点击、不可选中；
• nzHide是彻底隐藏：选项直接从下拉列表中消失，既不显示也不可交互。

此外，nzHide的过滤先于nzFilterOption搜索过滤执行（见第 3.2 节），因此它比“用搜索过滤把已选项剔除”的自定义方案更彻底——隐藏项连键盘导航都进不去。而这两者并不冲突，也可以组合使用。

6. 测试与质量保障

仓库的组件测试 select.spec.ts 在多个模板测试组件中把[nzHide]与nzValue、nzLabel、nzDisabled等输入并列渲染（见 select.spec.ts），覆盖了模板模式、多选模式（TestSelectTemplateMultipleComponent）与 tags 模式（TestSelectTemplateTagsComponent）等场景，验证了nzHide在@for循环渲染nz-option时的数据传递与变更检测链路（ngOnChanges→changes.next()→updateListOfContainerItem重算列表）。这些测试表明nzHide是 select 组件稳定、受保障的公共 API，而非示例代码中的临时技巧。

7. 小结

nzHide是 ng-zorro-antdnz-select中一个轻量但实用度极高的选项控制属性：

• 用法简单：模板中一个布尔绑定或裸属性即可生效；
• 实现可靠：源码中booleanAttribute转换、changes通知、updateListOfContainerItem首道过滤构成了完整的“隐藏”链路（option.component.ts、select.component.ts）；
• 场景明确：多选“已选即隐藏”、默认值不在选项列表、[nzOptions]对象驱动的数据层隐藏，三种用法覆盖了绝大多数实际需求。

若要快速体验，可直接参照 hide-selected.ts 编写一个nzMode="multiple"的 select，并配合isSelected()判断函数运行；更多 select 相关能力（如搜索过滤、大数据量渲染、标签模式）可在 select 官方文档 中继续查阅。

• UI组件
• 前端