ng-zorro-antd Select 组件完全指南：从基础用法到源码级原理

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读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官方文档给出了三个明确的使用场景判断标准下拉菜单展示选项当需要在一个紧凑控件中展示一组可选值时nz-select是比原生select更优雅的选择支持搜索、标签化多选、自定义渲染等能力。选项少于 5 个时优先考虑 Radio 组件选项极少时单选按钮组的信息密度与可扫视性更好。需要既可输入又可选择时改用 AutoComplete 组件nz-select的搜索只是对已有选项的过滤而 AutoComplete 面向的是自由输入 联想候选的场景。二、快速开始最小可用示例先看官方 demobasic.ts中提炼出的最小结构nz-select ngModellucy nz-option nzValuejack nzLabelJack / nz-option nzValuelucy nzLabelLucy / nz-option nzValuedisabled nzLabelDisabled nzDisabled / /nz-select要点使用前需在模块中导入NzSelectModule见 select.module.ts并在组件imports中同时引入FormsModule配合模板驱动表单或ReactiveFormsModule。子选项通过nz-option声明核心属性是nzValue实际绑定到ngModel的值与nzLabel界面展示的文本。更多基础状态组合禁用、加载、可清除、占位符参考官方 demo basic.mdnz-select ngModellucy nzDisabled nz-option nzValuelucy nzLabelLucy / /nz-select nz-select ngModellucy nzLoading nz-option nzValuelucy nzLabelLucy / /nz-select nz-select ngModellucy nzAllowClear nzPlaceHolderChoose nz-option nzValuelucy nzLabelLucy / /nz-select三、nz-select 完整 API 手册以下属性表完整继承自官方文档并结合源码select.component.ts中的实际Input/Output声明做了补充注释。默认值列标记 ✅ 表示支持通过NZ_CONFIG全局配置覆盖源码中该属性使用WithConfig()装饰器模块名称为select。3.1 输入属性nz-selectProperty说明类型默认值全局配置版本[nzId]组件内部 input 的 id 属性string-[ngModel]当前选中的 nz-option 值支持双向绑定any \| any[]-[compareWith]与 SelectControlValueAccessor 相同自定义值比较函数(o1: any, o2: any) boolean(o1, o2) o1 o2[nzAutoClearSearchValue]选中某项后是否清空当前搜索词仅multiple/tags模式生效booleantrue[nzAllowClear]是否显示清除按钮booleanfalse[nzBackdrop]下拉 overlay 是否附带 backdropbooleanfalse[nzVariant]Select 视觉变体outlined \| borderless \| filled \| underlinedoutlined✅20.0.0[nzOpen]下拉展开状态支持双向绑定booleanfalse[nzAutoFocus]默认自动获得焦点booleanfalse[nzDisabled]是否禁用booleanfalse[nzDropdownClassName]下拉菜单的 classNamestring \| string[]-[nzDropdownMatchSelectWidth]下拉宽度是否与 select 等宽booleantrue[nzDropdownStyle]下拉菜单的内联样式object-[nzCustomTemplate]已选中项的渲染模板TemplateRef{ $implicit: NzOptionComponent }-[nzServerSearch]设为true时不对 nz-option 做本地过滤交给服务端搜索booleanfalse[nzFilterOption]自定义过滤函数接收inputValue与option两个参数返回true则保留该选项(input?: string, option?: NzOptionComponent) boolean内置label.toString().toLowerCase().includes(search.toLowerCase())[nzMaxMultipleCount]多选模式下最多可选中个数numberInfinity[nzMode]选择模式multiple \| tags \| defaultdefault[nzNotFoundContent]无匹配结果时的提示内容string \| TemplateRefvoidNot Found[nzPlaceHolder]占位符string-[nzShowArrow]是否显示下拉箭头boolean单选true多选false[nzShowSearch]单选模式是否显示搜索输入框booleanfalse[nzSize]尺寸large \| small \| defaultdefault[nzStatus]校验状态error \| warning-[nzPrefix]自定义前缀TemplateRefany \| string-[nzSuffixIcon]自定义后缀图标TemplateRefany \| string-✅[nzRemoveIcon]自定义移除图标TemplateRefany-[nzClearIcon]自定义清除图标TemplateRefany-[nzMenuItemSelectedIcon]自定义选中项图标TemplateRefany-[nzTokenSeparators]tags / multiple 模式下的分词分隔符string[][][nzLoading]加载中状态booleanfalse[nzMaxTagCount]最多显示多少个标签number-[nzOptions]以数据驱动方式传入选项与nz-option二选一Array{ label: string \| number \| TemplateRefany; value: any; key?: string \| number; disabled?: boolean; hide?: boolean; groupLabel?: string \| TemplateRefany }-[nzMaxTagPlaceholder]超出nzMaxTagCount部分的占位模板TemplateRef{ $implicit: any[] }-[nzOptionHeightPx]下拉中每个选项的高度pxnumber32✅[nzOptionOverflowSize]下拉中最多渲染的选项数超出部分滚动number8[nzSelectOnTab]允许使用 Tab 键选中当前高亮项booleanfalse源码补充上述属性中带booleanAttribute变换的如nzAllowClear、nzShowSearch、nzLoading、nzAutoFocus、nzAutoClearSearchValue、nzServerSearch、nzDisabled、nzOpen、nzSelectOnTab、nzBackdrop、nzShowArrow在模板中可以省略[ ]直接写布尔属性名如nzDisabled。nzMaxMultipleCount使用numberAttributeWithInfinityFallback变换未设置时回退为Infinity见 select.component.ts。3.2 输出事件nz-selectEvent说明类型(ngModelChange)选中值变化回调EventEmitterany[](nzOpenChange)下拉展开状态变化回调EventEmitterboolean(nzScrollToBottom)下拉滚动到底部时触发常配合分页加载EventEmitterany(nzOnSearch)输入框内容变化回调EventEmitterstring(nzOnClear)清除已选项回调EventEmitterany版本 20.0.0(nzFocus)获得焦点回调EventEmitterany(nzBlur)失去焦点回调EventEmitterany源码中事件在 select.component.ts 声明其中nzOnClear使用 Angular 新的output()函数式声明其余为EventEmitter。焦点事件通过 CDK 的FocusMonitor监控宿主元素触发见 select.component.ts失焦时还会调用onTouched()完成表单 touched 状态上报。3.3 实例方法方法说明focus()使 select 获得焦点blur()移除焦点方法在源码中委托给内部nz-select-top-control组件实现select.component.ts通过模板引用变量调用nz-select #select /后select.focus()。四、nz-option 与 nz-option-group API4.1 nz-option声明式选项组件源码见 option.component.ts其模板仅是一个ng-template包裹的ng-content /意味着选项内容本质是可投影的内容。Property说明类型默认值[nzDisabled]禁用该选项booleanfalse[nzTitle]选项的原生 title 提示string \| number-[nzLabel]显示在 nz-select 与下拉菜单中的文本string \| number-[nzValue]传给 nz-select 的 ngModel 的值any-[nzKey]当nzValue是对象时必须传入用于性能优化作为 track 键string \| number-[nzHide]是否在选项列表中隐藏该项常用于保留已选但不在候选项中的默认值booleanfalse[nzCustomContent]设为true时nz-option 的 ng-content 内容将替换 nzLabel 显示在下拉菜单中booleanfalsenzKey 的源码依据在 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。Property说明类型默认值[nzLabel]分组标题string \| number \| TemplateRefvoid-组合用法官方 demo optgroup.tsnz-select ngModellucy nzAllowClear nzPlaceHolderChoose nzShowSearch nz-option-group nzLabelManager nz-option nzValuejack nzLabelJack / nz-option nzValuelucy nzLabelLucy / /nz-option-group nz-option-group nzLabelEngineer nz-option nzValuetom nzLabelTom / /nz-option-group /nz-select分组渲染原理nz-option-group内部也维护一个changes主题option-group.component.tsnz-option在ngOnInit时订阅其父级分组的nzLabel并同步到自身groupLabel字段option.component.ts随后 select 组件把同一groupLabel的选项组织成带分组头type: group的容器项序列select.component.ts。五、三种模式详解default / multiple / tagsnzMode支持三种取值类型定义见 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 nzModemultiple nzAllowClear nzPlaceHolderPlease select [(ngModel)]value / ng-template #tagPlaceHolder let-selectedListand {{ selectedList.length }} more selected/ng-templatenzMaxTagPlaceholder模板的$implicit上下文是超出部分的已选值数组。多选模式与nzMaxMultipleCount组合可限制最大选择数官方 demo max-count.ts[nzMaxMultipleCount]3。源码中当已达上限时isMaxMultipleCountReached为trueonItemClick中listOfValue.length this.nzMaxMultipleCount的条件会阻止继续添加select.component.tsonTokenSeparate中也会通过limitWithinMaxCount对分词批量添加做截断select.component.ts。5.3 标签模式tags与 multiple 的区别允许输入任意文本创建新选项。官方 demo tags.tsnz-select [nzOptions]options nzModetags nzPlaceHolderTag Mode /源码实现位于updateListOfContainerItemselect.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.tsnz-select [nzOptions]options nzShowSearch nzAllowClear nzPlaceHolderSelect a person /过滤由默认的defaultFilterOption实现select.component.ts将选项nzLabel转为小写后判断是否包含搜索词。可用[nzFilterOption]替换为自定义过滤函数函数签名为(input: string, option: NzSelectItemInterface) booleanselect.types.ts。6.2 远程搜索nzServerSearch nzOnSearch当数据量很大或需服务端检索时设置nzServerSearch关闭本地过滤配合(nzOnSearch)发起请求官方 demo search-box.tsnz-select [nzOptions]options() nzShowSearch nzServerSearch nzPlaceHolderinput search text [nzShowArrow]false [nzFilterOption]filterFn (nzOnSearch)search($event) /组件侧的过滤条件判断位于updateListOfContainerItemselect.component.tsif (!this.nzServerSearch this.searchValue)才执行本地过滤因此服务端模式下只需让nzFilterOption恒返回truedemo 中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 nzPlaceHolderSelect OS [nzCustomTemplate]defaultTemplate nz-option nzLabelWindows nzValuewindows / nz-option nzLabelApple nzValueapple / nz-option nzLabelAndroid nzValueandroid / /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 nzPlaceHolderSelect OS nz-option nzCustomContent nzLabelWindows nzValuewindows nz-icon nzTypewindows / Windows /nz-option nz-option nzCustomContent nzLabelMac nzValuemac nz-icon nzTypeapple / 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 nzPlaceHoldercustom dropdown render for (item of listOfItem(); track item) { nz-option [nzLabel]item [nzValue]item / } /nz-select ng-template #renderTemplate nz-divider / div classcontainer input typetext nz-input #inputElement / a classadd-item (click)addItem(inputElement) nz-icon nzTypeplus / 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 nzModemultiple nzPlaceHolderInserted 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-select8.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 nzModemultiple nzPlaceHolderPlease select [nzOptions]options [(ngModel)]value /其性能基础是nzOptionHeightPx与nzOptionOverflowSize两个参数均可在 select.component.ts 找到定义nzOptionHeightPx默认32每个选项的固定高度是虚拟滚动计算可视窗口的依据nzOptionOverflowSize默认8可视区域外上下各保留渲染的缓冲条数超出部分不进入 DOM。它们与nzDropdownMatchSelectWidth、nzNotFoundContent等一起透传给nz-option-containerselect.component.ts由内部基于固定高度 缓冲区的窗口化策略实现大列表流畅滚动。9.2 滚动到底部分页加载官方 demo scroll-load.ts配合(nzScrollToBottom)事件做增量加载nz-select [nzOptions]options() (nzScrollToBottom)loadMore() nzPlaceHolderSelect users nzAllowClear [nzDropdownRender]renderTemplate / ng-template #renderTemplate if (loading()) { nz-spin / } /ng-templatenzScrollToBottom事件在 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.tsupdateListOfValue内部值变更时反向转换并调用onChange单选取数组首个元素否则返回整个数组select.component.tssetDisabledState支持表单驱动的禁用状态同步select.component.ts。10.2 键盘操作内置完整键盘导航onKeyDown见 select.component.ts按键行为↑/↓在未禁用选项间移动高亮activatedValueEnter选中当前高亮项未展开时先展开Space展开下拉Tab默认关闭下拉nzSelectOnTab为true时改为选中当前高亮项Esc关闭下拉由 overlay 键盘事件处理select.component.ts10.3 视觉变体与尺寸nzVariant20.0.0 起outlined默认带边框、filled填充背景、borderless无边框、underlined下划线式宿主类名映射见 select.component.ts官方 demo variant.ts 展示了四种变体在单选/多选下的效果。finalVariant计算逻辑为组件自身设置优先其次表单级NZ_FORM_VARIANT最后回退outlinedselect.component.ts。nzSizelarge/default/small官方 demo size.ts 演示了三种尺寸 × 四种形态的组合finalSize依次回退formSize→compactSize→ 自身nzSizeselect.component.ts这意味着放入nz-form或nz-space-compact时尺寸可被父级统一接管。nzStatuserror/warning校验状态官方 demo status.ts由setStatusStyles写入宿主 classselect.component.ts。nzPrefix/nzSuffixIcon前后缀自定义官方 demo prefix-and-suffix.ts后缀图标同时支持TemplateRef与图标名字符串前缀在nz-select-top-control模板中通过nzStringTemplateOutlet渲染select-top-control.component.ts。十一、常见问题FAQQ滚动时 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同步到 overlayselect.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整个对象作为选中值的方案正常工作。十二、源码地图快速定位实现关注点文件主组件全部输入输出、模式逻辑、键盘、表单接入select.component.ts选项项 / 选项分组组件option.component.ts、option-group.component.ts顶部控件选中项、搜索框、前缀、分词select-top-control.component.ts下拉容器虚拟滚动、分组、Not Foundoption-container.component.ts类型定义模式、过滤函数、选项接口select.types.ts模块导出select.module.ts、public-api.ts全部 21 个可运行示例demo 目录basic.ts、multiple.ts、tags.ts、search-box.ts、big-data.ts等组件的内部结构由一组子组件协作完成nz-select-top-control选中区、nz-select-arrow箭头/加载/校验反馈图标、nz-select-clear清除按钮、nz-option-container下拉面板共同拼装全部通过模板在 select.component.ts 中按条件渲染选择值模型统一以内部数组listOfValue管理再按模式转换为表单模型输出这正是三种模式行为统一、代码复用度高的原因。结合本文的 API 手册与官方 demo你可以在不阅读全部源码的情况下快速落地绝大多数实际场景遇到边界行为时顺着上面的源码地图即可直达对应实现。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐塞尔达传说存档管理器如何实现WiiU与Switch存档的无缝互转塞尔达传说存档管理器如何实现WiiU与Switch存档的无缝互转 BotW Save Manager是一个专门为《塞尔达传说旷野之息》玩家设计的跨平台存档转UI组件前端cool-retro-term直播与录屏完整指南5个技巧让终端成为镜头下的视觉焦点cool retro term直播与录屏完整指南5个技巧让终端成为镜头下的视觉焦点 cool retro term 是一款模拟老式阴极射线管CRT显示效果UI组件前端ng-zorro-antd Pagination 分页组件完整指南从基础用法到源码级原理解析ng zorro antd Pagination 分页组件完整指南从基础用法到源码级原理解析 分页器Pagination是 ng zorro antd 中UI组件前端上一篇PraisonAI Agent Handoffs 完全指南多智能体任务委派、结构化交接与安全边界实战下一篇Faster-LIO终极指南轻量级激光雷达惯性里程计快速上手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考