UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本指南以 NG-ZORROng-zorro-antdcomponents/select模块的官方文档为主体系统讲解nz-select选择器的全部 API 参数、三种模式默认/多选/标签的使用方法、数据驱动与声明式选项的两种写法并结合仓库源码如 select.component.ts、option-container.component.ts、select-top-control.component.ts深入剖析其过滤、分词、虚拟滚动与键盘交互的实现原理。读完本文你将能够熟练地在表单中使用 Select 完成单选、多选、标签输入、搜索过滤与滚动加载等常见场景。何时使用 Selectnz-select是一个弹出下拉菜单供用户选择操作的选择器用来代替原生select元素或者作为更优雅的多选器使用。结合仓库内的 demo 示例选择器适用的典型场景包括弹出一个下拉菜单给用户选择操作用于代替原生的选择器或者需要一个更优雅的多选器时当选项少时少于 5 项建议直接将选项平铺使用 Radio 单选框 是更好的选择如果你在寻找一个可输可选的输入框那你可能需要 AutoComplete 自动完成。基本用法与 API 概览Select 最基本的用法是将nz-option作为内容投影进nz-select通过nzValue指定值、nzLabel指定显示文字nz-select nz-option nzValuelucy nzLabelLucy / /nz-select结合 basic demo 可以看到完整的可运行形态包括禁用nzDisabled、加载中nzLoading、允许清除nzAllowClear和占位符nzPlaceHoldernz-select ngModellucy nz-option nzValuejack nzLabelJack / nz-option nzValuelucy nzLabelLucy / nz-option nzValuedisabled nzLabelDisabled nzDisabled / /nz-select nz-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-selectSelect 组件实现了ControlValueAccessor见 select.component.ts 中的NG_VALUE_ACCESSORprovider因此可以直接与ngModel或响应式表单Reactive Forms无缝集成。nz-select 全部参数详解下表完整列出nz-select支持的所有输入与输出参数含默认值、是否支持全局配置及引入版本随后对关键参数逐一深入说明。参数说明类型默认值全局配置版本[nzId]组件内部 input 的 id 值string-[ngModel]当前选中的 nz-option 的 nzValue 值可双向绑定当nzMode为multiple或tags时ngModel 为数组any \| any[]-[compareWith]与 Angular 表单 SelectControlValueAccessor 相同(o1: any, o2: any) boolean(o1: any, o2: any) o1o2[nzAutoClearSearchValue]是否在选中项后清空搜索框只在mode为multiple或tags时有效booleantrue[nzAllowClear]支持清除booleanfalse[nzBackdrop]浮层是否应带有背景板booleanfalse[nzVariant]形态变体outlined \| borderless \| filled \| underlinedoutlined✅20.0.0[nzOpen]下拉菜单是否打开可双向绑定booleanfalse[nzAutoFocus]默认获取焦点booleanfalse[nzDisabled]是否禁用booleanfalse[nzDropdownClassName]下拉菜单的 className 属性string \| string[]-[nzDropdownMatchSelectWidth]下拉菜单和选择器同宽booleantrue[nzDropdownStyle]下拉菜单的 style 属性object-[nzCustomTemplate]自定义选择框的 Template 内容TemplateRef{ $implicit: NzOptionComponent }-[nzServerSearch]是否使用服务端搜索当为 true 时将不再在前端对 nz-option 进行过滤booleanfalse[nzFilterOption]是否根据输入项进行筛选。当其为一个函数时会接收inputValue、option两个参数当option符合筛选条件时应返回true反之则返回false(input?: string, option?: NzOptionComponent) boolean;-[nzMaxMultipleCount]最多选中多少个标签numberInfinity[nzMode]设置 nz-select 的模式multiple \| tags \| defaultdefault[nzNotFoundContent]当下拉列表为空时显示的内容string \| TemplateRefvoid-[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]最多显示多少个 tagnumber-[nzMaxTagPlaceholder]隐藏 tag 时显示的内容TemplateRef{ $implicit: any[] }-[nzOptions]option 列表可以取代 nz-optionArray{ label: string \| number \| TemplateRefany; value: any; key?: string \| number; disabled?: boolean; hide?: boolean; groupLabel?: string \| TemplateRefany; }-[nzOptionHeightPx]下拉菜单中每个 Option 的高度number32✅[nzOptionOverflowSize]下拉菜单中最多展示的 Option 个数超出部分滚动number8[nzSelectOnTab]允许使用 TAB 键选择项目booleanfalse(ngModelChange)选中的 nz-option 发生变化时调用此函数EventEmitterany[]-(nzOpenChange)下拉菜单打开状态变化回调EventEmitterboolean-(nzScrollToBottom)下拉列表滚动到底部的回调EventEmitterany-(nzOnSearch)文本框值变化时回调EventEmitterstring-(nzOnClear)清空已选项时触发的回调函数EventEmitterany--20.0.0(nzFocus)focus 时回调EventEmitterany-(nzBlur)blur 时回调EventEmitterany-注原文档表格中[nzPreix]为笔误正确属性名为[nzPrefix]源码 select.component.ts 中定义为Input() nzPrefix。模式default / multiple / tagsnzMode决定 Select 的行为模式类型定义见 select.types.ts 中的NzSelectModeType default | multiple | tagsdefault默认单选模式ngModel绑定的是单个值multiple多选模式选中项以标签tag形式展示ngModel绑定为数组tags标签输入模式除可从预置选项中点选外还允许用户直接输入文本创建新标签ngModel同样为数组。从 tags demo 可以看到多选/标签模式配合数据驱动的nzOptions是最简洁的写法nz-select [nzOptions]options nzModetags nzPlaceHolderTag Mode /readonly options alphabet().map(item ({ label: item, value: item }));当nzMode为multiple或tags时下拉浮层右侧的箭头默认隐藏nzShowArrow默认值取决于模式选中项之间可通过 Backspace 删除最后一个标签——该交互实现在 select-top-control.component.ts当输入框为空且按下 Backspace 时会触发删除最末位已选项。搜索与过滤nzShowSearch / nzServerSearch / nzFilterOptionnzShowSearch使单选模式也可搜索搜索框输入时触发(nzOnSearch)回调EventEmitterstring参数为当前输入值nzFilterOption自定义过滤函数接收(inputValue, option)两个参数返回true表示该选项保留nzServerSearch开启服务端搜索后前端将不再对nz-option做过滤你需要自行监听(nzOnSearch)请求服务端数据并更新nzOptions。即使不设置nzFilterOption组件也内置了默认过滤逻辑。源码 select.component.ts 中的defaultFilterOption实现为对每个选项的nzLabel转小写后用indexOf判断是否包含搜索词从而实现不区分大小写的包含匹配const defaultFilterOption: NzFilterOptionType (searchValue: string, item: NzSelectItemInterface): boolean { if (item item.nzLabel) { return item.nzLabel.toString().toLowerCase().indexOf(searchValue.toLowerCase()) -1; } else { return false; } };过滤发生在updateListOfContainerItem()select.component.ts中当nzServerSearch为 false 且存在搜索词时依次用nzFilterOption过滤并把命中项重新插入分组标签group item。多选上限nzMaxMultipleCountnzMaxMultipleCount用于限制最多可选中多少个标签默认值为Infinity。在源码中该输入经过numberAttributeWithInfinityFallback转换select.component.ts并配套两个派生状态isMaxMultipleCountSet多选模式下且上限非Infinity时为真此时会在箭头区域展示计数反馈isMaxMultipleCountReached已选数量恰好达到上限此时未选中的选项在下拉列表中被标记为 disabled见 option-container.component.ts。同时select.component.ts 中的onItemClick会检查listOfValue.length nzMaxMultipleCount才允许继续添加分词场景同样通过limitWithinMaxCount做截断select.component.ts。标签截断显示nzMaxTagCount / nzMaxTagPlaceholder多选模式下当选中项很多时可用nzMaxTagCount限制同时显示的标签数量。源码 select-top-control.component.ts 会截取前nzMaxTagCount个标签渲染并将超出部分汇总为一个不可点击的占位标签其文案默认为 N ...N 为超出的数量nzMaxTagPlaceholder则允许你传入TemplateRef{ $implicit: any[] }完全自定义该占位标签的内容上下文中的$implicit为被隐藏标签的值数组。形态变体与尺寸nzVariant / nzSize / nzStatusnzVariant20.0.0 引入支持全局配置可选outlined默认描边、borderless无边框、filled填充底色、underlined下划线四种形态。从源码 host 绑定select.component.ts可以看到这四种变体分别映射为ant-select-outlined、ant-select-borderless、ant-select-filled、ant-select-underlined四个 CSS 类且支持从表单容器NZ_FORM_VARIANT或全局配置继承nzSizelarge | small | default映射为ant-select-lg/ant-select-sm类并可继承表单与紧凑布局nz-space-compact的尺寸nzStatuserror | warning校验状态与表单nz-form-item的反馈图标联动hasFeedback具体样式类通过getStatusClassNames计算并动态添加到宿主元素select.component.ts。下拉浮层定制nzDropdownClassName / nzDropdownStyle / nzDropdownMatchSelectWidth / nzBackdropnzDropdownClassName下拉菜单的 className可传字符串或字符串数组nzDropdownStyle下拉菜单内联 style 对象nzDropdownMatchSelectWidth默认true下拉菜单与选择器同宽。关闭后浮层宽度由内容撑开从模板select.component.ts可见其通过 CDK Overlay 的cdkConnectedOverlayWidth/MinWidth动态切换实现nzBackdrop是否给浮层加背景板backdrop点击背景可关闭浮层。图标自定义nzPrefix / nzSuffixIcon / nzRemoveIcon / nzClearIcon / nzMenuItemSelectedIconnzPrefix/nzSuffixIcon选择框的前缀、后缀内容可传TemplateRef或字符串。nzSuffixIcon支持全局配置且只要设置了后缀图标箭头arrow区域就会被渲染源码get showArrow()见 select.component.tsnzRemoveIcon多选标签上的“移除”图标nzClearIcon清空按钮图标nzMenuItemSelectedIcon下拉列表中当前选中条目的图标。键盘与焦点行为nzAutoFocus / nzSelectOnTab / focus / blurnzAutoFocus组件挂载后默认获取焦点nzSelectOnTab允许用 TAB 键直接选中当前高亮项。键盘交互在onKeyDownselect.component.ts中实现方向键上下移动高亮activatedValue、Enter确认选中、Space展开下拉、Escape关闭浮层、默认按键字符输入自动展开浮层。nz-option 参数详解nz-option声明式地定义一个选项对应源码 option.component.ts 中的NzOptionComponent。它本身不渲染可见 DOM只是把ng-content包进一个ng-template供下拉列表按需投影。参数说明类型默认值[nzDisabled]是否禁用booleanfalse[nzTitle]选项上的原生 title 提示string \| number-[nzLabel]选中该 nz-option 后nz-select 中显示的文字string \| number-[nzValue]nz-select 中 ngModel 的值any-[nzKey]nz-select 中 ngModel 的值当nzValue为对象时应传入用于性能优化与trackBystring \| number-[nzHide]是否在选项列表中隐藏该选项booleanfalse[nzCustomContent]是否自定义在下拉菜单中的 Template 内容为 true 时 nz-option 包裹的内容将直接渲染在下拉菜单中booleanfalse说明nzKey的英文原文档描述为 “Should be passed when typeof nzValue - Object. Key will be used for performance optimizations”即当nzValue是对象时应传入nzKey它会被用作虚拟滚动trackBy的 key见 option-container.component.ts 的trackValue。nz-option-group 分组nz-option-group用于对选项分组对应源码 option-group.component.ts参数说明类型默认值[nzLabel]组名string \| number \| TemplateRefvoid-用法示例配合nz-optionnz-select ngModellucy 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分组信息在 select.component.ts 的updateListOfContainerItem()中处理组件会收集各 option 的groupLabel去重后把类型为group的分组条目插到对应选项之前下拉列表据此渲染nz-option-item-group。数据驱动用 nzOptions 取代 nz-option当选项来自异步接口或需要动态更新时推荐使用nzOptions输入它接收一个数组每个元素包含label、value以及可选的key、disabled、hide、groupLabelnz-select ngModellucy [nzOptions]listOfOption / nz-select ngModellucy nzAllowClear nzPlaceHolderChoose [nzOptions]listOfGroupOption /readonly listOfOption [ { label: Jack, value: jack }, { label: Lucy, value: lucy }, { label: disabled, value: disabled, disabled: true } ]; readonly listOfGroupOption [ { label: Jack, value: jack, groupLabel: Manager }, { label: Lucy, value: lucy, groupLabel: Manager }, { label: Tom, value: tom, groupLabel: Engineer } ];如上 options demo 所示groupLabel字段可以直接在数据驱动模式下完成分组无需再写nz-option-group。从源码角度看传入nzOptions后组件会切换到“响应式驱动”isReactiveDriven true见 select.component.ts将数组转换为内部统一的NzSelectItemInterface结构此时若label是TemplateRef则自动启用自定义内容渲染。滚动加载与大数据量nzScrollToBottom / nzOptionHeightPx / nzOptionOverflowSizenzScrollToBottom在浮层滚动到底部时触发常用于分页加载更多数据。参考 scroll-load demo 的完整实现nz-select [nzOptions]options() (nzScrollToBottom)loadMore() nzPlaceHolderSelect users nzAllowClear [nzDropdownRender]renderTemplate / ng-template #renderTemplate if (loading()) { nz-spin / } /ng-templateloadMore(): void { this.loading.set(true); this.getRandomNameList().subscribe(data { this.loading.set(false); this.options.update(options [...options, ...data.map(item ({ label: item, value: item }))]); }); }这里的nzDropdownRender是一个补充性的模板出口可往下拉列表末尾追加自定义内容例如加载动画它在 option-container.component.ts 中通过ngTemplateOutlet渲染。底层支撑是下拉列表的虚拟滚动浮层使用cdk-virtual-scroll-viewportoption-container.component.ts每个选项高度由nzOptionHeightPx决定默认32支持全局配置最多同时渲染/展示的条数由nzOptionOverflowSize控制默认8超出部分通过滚动查看列表总高度与最大高度均按这两个参数计算。(nzScrollToBottom)的触发逻辑在onScrolledIndexChange中实现option-container.component.ts对比滚动前后的索引仅在下一次跨越底部阈值剩余条数 maxItemLength 1时发射一次事件避免快速滚动时重复触发。自动分词nzTokenSeparators在tags或multiple模式下可通过nzTokenSeparators指定分隔符让用户粘贴/输入包含分隔符的文本时自动切成多个标签。参考 automatic-tokenization demonz-select nzModetags nzPlaceHolderautomatic tokenization [nzOptions]options [nzTokenSeparators][,] /分词的核心逻辑在 select-top-control.component.ts输入值变化时如果存在分隔符且输入内容包含该分隔符lastIndexOf 0就按正则[${separators.join()}]切分、去重后通过tokenize事件交给 Select 主组件主组件onTokenSeparateselect.component.ts再区分模式处理multiple模式只把已匹配到预置选项的值加入选中集tags模式未匹配到的输入片段会作为新标签直接加入选中集两种模式都会用nzMaxMultipleCount对结果截断。方法与实例 APInz-select暴露两个实例方法通过模板引用变量或ViewChild调用名称说明blur()取消焦点focus()获取焦点源码中这两个方法委托给内部NzSelectTopControlComponentselect.component.ts最终落到搜索输入框的原生focus()/blur()见 select-top-control.component.ts。表单集成与双向绑定因为NzSelectComponent实现了ControlValueAccessorwriteValue、registerOnChange、registerOnTouched、setDisabledState见 select.component.ts它可以与模板驱动表单的ngModel/(ngModelChange)双向绑定在响应式表单中使用formControlName/formControl通过setDisabledState与表单的禁用状态保持同步通过compareWith自定义“值相等”的判断逻辑这在nzValue为对象时尤其有用——默认实现为严格相等o1 o2select.component.ts。单选模式下模型与内部列表的转换逻辑covertListToModel/covertModelToListselect.component.ts保证了default模式写入ngModel的是单个值空选为nullmultiple/tags模式写入的是数组。FAQ浮层不跟随自定义滚动容器滚动Q滚动时浮层元素没有跟随滚动位置。默认情况下浮层元素使用body作为滚动容器。如果使用了其他滚动容器请在自定义滚动容器元素上添加 CDK 的CdkScrollable指令使 CDK Overlay 能够感知该容器的滚动事件并同步浮层位置。注意你需要从angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块nz-select的浮层本身基于CdkConnectedOverlay实现参见 select.component.ts 的模板绑定。结语Select 的内部工作方式速览把全文涉及的源码脉络串起来nz-selectselect.component.ts作为门面组件负责状态聚合——合并nzOptions或nz-option内容投影为统一的NzSelectItemInterface列表、执行过滤与分组、维护选中值并通过NG_VALUE_ACCESSOR与表单桥接nz-select-top-controlselect-top-control.component.ts渲染选中标签、输入框、占位符与分词nz-option-containeroption-container.component.ts基于 CDK 虚拟滚动渲染下拉列表、空态与滚动到底事件nz-option/nz-option-groupoption.component.ts、option-group.component.ts则是声明式的数据声明单元。类型契约集中在 select.types.ts单测覆盖可参考 select.spec.ts。理解这条链路之后无论是调试过滤、分词还是滚动加载问题都能快速定位到对应源码。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Shoelace sl-select 下拉选择组件完全指南API、多选、自定义标签与懒加载Shoelace sl select 下拉选择组件完全指南API、多选、自定义标签与懒加载 sl select 是 ShoelaceWeb AwesomUI组件前端NG-ZORRO Cascader 级联选择组件完全指南API、动态加载与搜索过滤实战NG ZORRO Cascader 级联选择组件完全指南API、动态加载与搜索过滤实战 导读 级联选择Cascader是 NG ZORRO 中处理“多级关UI组件前端vue-select选择器模式详解如何选择单选、多选与标签化功能vue select选择器模式详解如何选择单选、多选与标签化功能 vue select是一个功能强大的Vue.js选择器组件它提供了三种主要的选择模式 单前端UI组件上一篇Precedent.dev代码分割优化提升应用加载速度和用户体验下一篇终极Android系统瘦身指南Universal Android Debloater让你的手机焕发新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
NG-ZORRO Select 选择器组件完整指南：API 详解、多选/标签模式与滚动加载实战
UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本指南以 NG-ZORROng-zorro-antdcomponents/select模块的官方文档为主体系统讲解nz-select选择器的全部 API 参数、三种模式默认/多选/标签的使用方法、数据驱动与声明式选项的两种写法并结合仓库源码如 select.component.ts、option-container.component.ts、select-top-control.component.ts深入剖析其过滤、分词、虚拟滚动与键盘交互的实现原理。读完本文你将能够熟练地在表单中使用 Select 完成单选、多选、标签输入、搜索过滤与滚动加载等常见场景。何时使用 Selectnz-select是一个弹出下拉菜单供用户选择操作的选择器用来代替原生select元素或者作为更优雅的多选器使用。结合仓库内的 demo 示例选择器适用的典型场景包括弹出一个下拉菜单给用户选择操作用于代替原生的选择器或者需要一个更优雅的多选器时当选项少时少于 5 项建议直接将选项平铺使用 Radio 单选框 是更好的选择如果你在寻找一个可输可选的输入框那你可能需要 AutoComplete 自动完成。基本用法与 API 概览Select 最基本的用法是将nz-option作为内容投影进nz-select通过nzValue指定值、nzLabel指定显示文字nz-select nz-option nzValuelucy nzLabelLucy / /nz-select结合 basic demo 可以看到完整的可运行形态包括禁用nzDisabled、加载中nzLoading、允许清除nzAllowClear和占位符nzPlaceHoldernz-select ngModellucy nz-option nzValuejack nzLabelJack / nz-option nzValuelucy nzLabelLucy / nz-option nzValuedisabled nzLabelDisabled nzDisabled / /nz-select nz-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-selectSelect 组件实现了ControlValueAccessor见 select.component.ts 中的NG_VALUE_ACCESSORprovider因此可以直接与ngModel或响应式表单Reactive Forms无缝集成。nz-select 全部参数详解下表完整列出nz-select支持的所有输入与输出参数含默认值、是否支持全局配置及引入版本随后对关键参数逐一深入说明。参数说明类型默认值全局配置版本[nzId]组件内部 input 的 id 值string-[ngModel]当前选中的 nz-option 的 nzValue 值可双向绑定当nzMode为multiple或tags时ngModel 为数组any \| any[]-[compareWith]与 Angular 表单 SelectControlValueAccessor 相同(o1: any, o2: any) boolean(o1: any, o2: any) o1o2[nzAutoClearSearchValue]是否在选中项后清空搜索框只在mode为multiple或tags时有效booleantrue[nzAllowClear]支持清除booleanfalse[nzBackdrop]浮层是否应带有背景板booleanfalse[nzVariant]形态变体outlined \| borderless \| filled \| underlinedoutlined✅20.0.0[nzOpen]下拉菜单是否打开可双向绑定booleanfalse[nzAutoFocus]默认获取焦点booleanfalse[nzDisabled]是否禁用booleanfalse[nzDropdownClassName]下拉菜单的 className 属性string \| string[]-[nzDropdownMatchSelectWidth]下拉菜单和选择器同宽booleantrue[nzDropdownStyle]下拉菜单的 style 属性object-[nzCustomTemplate]自定义选择框的 Template 内容TemplateRef{ $implicit: NzOptionComponent }-[nzServerSearch]是否使用服务端搜索当为 true 时将不再在前端对 nz-option 进行过滤booleanfalse[nzFilterOption]是否根据输入项进行筛选。当其为一个函数时会接收inputValue、option两个参数当option符合筛选条件时应返回true反之则返回false(input?: string, option?: NzOptionComponent) boolean;-[nzMaxMultipleCount]最多选中多少个标签numberInfinity[nzMode]设置 nz-select 的模式multiple \| tags \| defaultdefault[nzNotFoundContent]当下拉列表为空时显示的内容string \| TemplateRefvoid-[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]最多显示多少个 tagnumber-[nzMaxTagPlaceholder]隐藏 tag 时显示的内容TemplateRef{ $implicit: any[] }-[nzOptions]option 列表可以取代 nz-optionArray{ label: string \| number \| TemplateRefany; value: any; key?: string \| number; disabled?: boolean; hide?: boolean; groupLabel?: string \| TemplateRefany; }-[nzOptionHeightPx]下拉菜单中每个 Option 的高度number32✅[nzOptionOverflowSize]下拉菜单中最多展示的 Option 个数超出部分滚动number8[nzSelectOnTab]允许使用 TAB 键选择项目booleanfalse(ngModelChange)选中的 nz-option 发生变化时调用此函数EventEmitterany[]-(nzOpenChange)下拉菜单打开状态变化回调EventEmitterboolean-(nzScrollToBottom)下拉列表滚动到底部的回调EventEmitterany-(nzOnSearch)文本框值变化时回调EventEmitterstring-(nzOnClear)清空已选项时触发的回调函数EventEmitterany--20.0.0(nzFocus)focus 时回调EventEmitterany-(nzBlur)blur 时回调EventEmitterany-注原文档表格中[nzPreix]为笔误正确属性名为[nzPrefix]源码 select.component.ts 中定义为Input() nzPrefix。模式default / multiple / tagsnzMode决定 Select 的行为模式类型定义见 select.types.ts 中的NzSelectModeType default | multiple | tagsdefault默认单选模式ngModel绑定的是单个值multiple多选模式选中项以标签tag形式展示ngModel绑定为数组tags标签输入模式除可从预置选项中点选外还允许用户直接输入文本创建新标签ngModel同样为数组。从 tags demo 可以看到多选/标签模式配合数据驱动的nzOptions是最简洁的写法nz-select [nzOptions]options nzModetags nzPlaceHolderTag Mode /readonly options alphabet().map(item ({ label: item, value: item }));当nzMode为multiple或tags时下拉浮层右侧的箭头默认隐藏nzShowArrow默认值取决于模式选中项之间可通过 Backspace 删除最后一个标签——该交互实现在 select-top-control.component.ts当输入框为空且按下 Backspace 时会触发删除最末位已选项。搜索与过滤nzShowSearch / nzServerSearch / nzFilterOptionnzShowSearch使单选模式也可搜索搜索框输入时触发(nzOnSearch)回调EventEmitterstring参数为当前输入值nzFilterOption自定义过滤函数接收(inputValue, option)两个参数返回true表示该选项保留nzServerSearch开启服务端搜索后前端将不再对nz-option做过滤你需要自行监听(nzOnSearch)请求服务端数据并更新nzOptions。即使不设置nzFilterOption组件也内置了默认过滤逻辑。源码 select.component.ts 中的defaultFilterOption实现为对每个选项的nzLabel转小写后用indexOf判断是否包含搜索词从而实现不区分大小写的包含匹配const defaultFilterOption: NzFilterOptionType (searchValue: string, item: NzSelectItemInterface): boolean { if (item item.nzLabel) { return item.nzLabel.toString().toLowerCase().indexOf(searchValue.toLowerCase()) -1; } else { return false; } };过滤发生在updateListOfContainerItem()select.component.ts中当nzServerSearch为 false 且存在搜索词时依次用nzFilterOption过滤并把命中项重新插入分组标签group item。多选上限nzMaxMultipleCountnzMaxMultipleCount用于限制最多可选中多少个标签默认值为Infinity。在源码中该输入经过numberAttributeWithInfinityFallback转换select.component.ts并配套两个派生状态isMaxMultipleCountSet多选模式下且上限非Infinity时为真此时会在箭头区域展示计数反馈isMaxMultipleCountReached已选数量恰好达到上限此时未选中的选项在下拉列表中被标记为 disabled见 option-container.component.ts。同时select.component.ts 中的onItemClick会检查listOfValue.length nzMaxMultipleCount才允许继续添加分词场景同样通过limitWithinMaxCount做截断select.component.ts。标签截断显示nzMaxTagCount / nzMaxTagPlaceholder多选模式下当选中项很多时可用nzMaxTagCount限制同时显示的标签数量。源码 select-top-control.component.ts 会截取前nzMaxTagCount个标签渲染并将超出部分汇总为一个不可点击的占位标签其文案默认为 N ...N 为超出的数量nzMaxTagPlaceholder则允许你传入TemplateRef{ $implicit: any[] }完全自定义该占位标签的内容上下文中的$implicit为被隐藏标签的值数组。形态变体与尺寸nzVariant / nzSize / nzStatusnzVariant20.0.0 引入支持全局配置可选outlined默认描边、borderless无边框、filled填充底色、underlined下划线四种形态。从源码 host 绑定select.component.ts可以看到这四种变体分别映射为ant-select-outlined、ant-select-borderless、ant-select-filled、ant-select-underlined四个 CSS 类且支持从表单容器NZ_FORM_VARIANT或全局配置继承nzSizelarge | small | default映射为ant-select-lg/ant-select-sm类并可继承表单与紧凑布局nz-space-compact的尺寸nzStatuserror | warning校验状态与表单nz-form-item的反馈图标联动hasFeedback具体样式类通过getStatusClassNames计算并动态添加到宿主元素select.component.ts。下拉浮层定制nzDropdownClassName / nzDropdownStyle / nzDropdownMatchSelectWidth / nzBackdropnzDropdownClassName下拉菜单的 className可传字符串或字符串数组nzDropdownStyle下拉菜单内联 style 对象nzDropdownMatchSelectWidth默认true下拉菜单与选择器同宽。关闭后浮层宽度由内容撑开从模板select.component.ts可见其通过 CDK Overlay 的cdkConnectedOverlayWidth/MinWidth动态切换实现nzBackdrop是否给浮层加背景板backdrop点击背景可关闭浮层。图标自定义nzPrefix / nzSuffixIcon / nzRemoveIcon / nzClearIcon / nzMenuItemSelectedIconnzPrefix/nzSuffixIcon选择框的前缀、后缀内容可传TemplateRef或字符串。nzSuffixIcon支持全局配置且只要设置了后缀图标箭头arrow区域就会被渲染源码get showArrow()见 select.component.tsnzRemoveIcon多选标签上的“移除”图标nzClearIcon清空按钮图标nzMenuItemSelectedIcon下拉列表中当前选中条目的图标。键盘与焦点行为nzAutoFocus / nzSelectOnTab / focus / blurnzAutoFocus组件挂载后默认获取焦点nzSelectOnTab允许用 TAB 键直接选中当前高亮项。键盘交互在onKeyDownselect.component.ts中实现方向键上下移动高亮activatedValue、Enter确认选中、Space展开下拉、Escape关闭浮层、默认按键字符输入自动展开浮层。nz-option 参数详解nz-option声明式地定义一个选项对应源码 option.component.ts 中的NzOptionComponent。它本身不渲染可见 DOM只是把ng-content包进一个ng-template供下拉列表按需投影。参数说明类型默认值[nzDisabled]是否禁用booleanfalse[nzTitle]选项上的原生 title 提示string \| number-[nzLabel]选中该 nz-option 后nz-select 中显示的文字string \| number-[nzValue]nz-select 中 ngModel 的值any-[nzKey]nz-select 中 ngModel 的值当nzValue为对象时应传入用于性能优化与trackBystring \| number-[nzHide]是否在选项列表中隐藏该选项booleanfalse[nzCustomContent]是否自定义在下拉菜单中的 Template 内容为 true 时 nz-option 包裹的内容将直接渲染在下拉菜单中booleanfalse说明nzKey的英文原文档描述为 “Should be passed when typeof nzValue - Object. Key will be used for performance optimizations”即当nzValue是对象时应传入nzKey它会被用作虚拟滚动trackBy的 key见 option-container.component.ts 的trackValue。nz-option-group 分组nz-option-group用于对选项分组对应源码 option-group.component.ts参数说明类型默认值[nzLabel]组名string \| number \| TemplateRefvoid-用法示例配合nz-optionnz-select ngModellucy 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分组信息在 select.component.ts 的updateListOfContainerItem()中处理组件会收集各 option 的groupLabel去重后把类型为group的分组条目插到对应选项之前下拉列表据此渲染nz-option-item-group。数据驱动用 nzOptions 取代 nz-option当选项来自异步接口或需要动态更新时推荐使用nzOptions输入它接收一个数组每个元素包含label、value以及可选的key、disabled、hide、groupLabelnz-select ngModellucy [nzOptions]listOfOption / nz-select ngModellucy nzAllowClear nzPlaceHolderChoose [nzOptions]listOfGroupOption /readonly listOfOption [ { label: Jack, value: jack }, { label: Lucy, value: lucy }, { label: disabled, value: disabled, disabled: true } ]; readonly listOfGroupOption [ { label: Jack, value: jack, groupLabel: Manager }, { label: Lucy, value: lucy, groupLabel: Manager }, { label: Tom, value: tom, groupLabel: Engineer } ];如上 options demo 所示groupLabel字段可以直接在数据驱动模式下完成分组无需再写nz-option-group。从源码角度看传入nzOptions后组件会切换到“响应式驱动”isReactiveDriven true见 select.component.ts将数组转换为内部统一的NzSelectItemInterface结构此时若label是TemplateRef则自动启用自定义内容渲染。滚动加载与大数据量nzScrollToBottom / nzOptionHeightPx / nzOptionOverflowSizenzScrollToBottom在浮层滚动到底部时触发常用于分页加载更多数据。参考 scroll-load demo 的完整实现nz-select [nzOptions]options() (nzScrollToBottom)loadMore() nzPlaceHolderSelect users nzAllowClear [nzDropdownRender]renderTemplate / ng-template #renderTemplate if (loading()) { nz-spin / } /ng-templateloadMore(): void { this.loading.set(true); this.getRandomNameList().subscribe(data { this.loading.set(false); this.options.update(options [...options, ...data.map(item ({ label: item, value: item }))]); }); }这里的nzDropdownRender是一个补充性的模板出口可往下拉列表末尾追加自定义内容例如加载动画它在 option-container.component.ts 中通过ngTemplateOutlet渲染。底层支撑是下拉列表的虚拟滚动浮层使用cdk-virtual-scroll-viewportoption-container.component.ts每个选项高度由nzOptionHeightPx决定默认32支持全局配置最多同时渲染/展示的条数由nzOptionOverflowSize控制默认8超出部分通过滚动查看列表总高度与最大高度均按这两个参数计算。(nzScrollToBottom)的触发逻辑在onScrolledIndexChange中实现option-container.component.ts对比滚动前后的索引仅在下一次跨越底部阈值剩余条数 maxItemLength 1时发射一次事件避免快速滚动时重复触发。自动分词nzTokenSeparators在tags或multiple模式下可通过nzTokenSeparators指定分隔符让用户粘贴/输入包含分隔符的文本时自动切成多个标签。参考 automatic-tokenization demonz-select nzModetags nzPlaceHolderautomatic tokenization [nzOptions]options [nzTokenSeparators][,] /分词的核心逻辑在 select-top-control.component.ts输入值变化时如果存在分隔符且输入内容包含该分隔符lastIndexOf 0就按正则[${separators.join()}]切分、去重后通过tokenize事件交给 Select 主组件主组件onTokenSeparateselect.component.ts再区分模式处理multiple模式只把已匹配到预置选项的值加入选中集tags模式未匹配到的输入片段会作为新标签直接加入选中集两种模式都会用nzMaxMultipleCount对结果截断。方法与实例 APInz-select暴露两个实例方法通过模板引用变量或ViewChild调用名称说明blur()取消焦点focus()获取焦点源码中这两个方法委托给内部NzSelectTopControlComponentselect.component.ts最终落到搜索输入框的原生focus()/blur()见 select-top-control.component.ts。表单集成与双向绑定因为NzSelectComponent实现了ControlValueAccessorwriteValue、registerOnChange、registerOnTouched、setDisabledState见 select.component.ts它可以与模板驱动表单的ngModel/(ngModelChange)双向绑定在响应式表单中使用formControlName/formControl通过setDisabledState与表单的禁用状态保持同步通过compareWith自定义“值相等”的判断逻辑这在nzValue为对象时尤其有用——默认实现为严格相等o1 o2select.component.ts。单选模式下模型与内部列表的转换逻辑covertListToModel/covertModelToListselect.component.ts保证了default模式写入ngModel的是单个值空选为nullmultiple/tags模式写入的是数组。FAQ浮层不跟随自定义滚动容器滚动Q滚动时浮层元素没有跟随滚动位置。默认情况下浮层元素使用body作为滚动容器。如果使用了其他滚动容器请在自定义滚动容器元素上添加 CDK 的CdkScrollable指令使 CDK Overlay 能够感知该容器的滚动事件并同步浮层位置。注意你需要从angular/cdk/scrolling导入CdkScrollable指令或ScrollingModule模块nz-select的浮层本身基于CdkConnectedOverlay实现参见 select.component.ts 的模板绑定。结语Select 的内部工作方式速览把全文涉及的源码脉络串起来nz-selectselect.component.ts作为门面组件负责状态聚合——合并nzOptions或nz-option内容投影为统一的NzSelectItemInterface列表、执行过滤与分组、维护选中值并通过NG_VALUE_ACCESSOR与表单桥接nz-select-top-controlselect-top-control.component.ts渲染选中标签、输入框、占位符与分词nz-option-containeroption-container.component.ts基于 CDK 虚拟滚动渲染下拉列表、空态与滚动到底事件nz-option/nz-option-groupoption.component.ts、option-group.component.ts则是声明式的数据声明单元。类型契约集中在 select.types.ts单测覆盖可参考 select.spec.ts。理解这条链路之后无论是调试过滤、分词还是滚动加载问题都能快速定位到对应源码。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐Shoelace sl-select 下拉选择组件完全指南API、多选、自定义标签与懒加载Shoelace sl select 下拉选择组件完全指南API、多选、自定义标签与懒加载 sl select 是 ShoelaceWeb AwesomUI组件前端NG-ZORRO Cascader 级联选择组件完全指南API、动态加载与搜索过滤实战NG ZORRO Cascader 级联选择组件完全指南API、动态加载与搜索过滤实战 导读 级联选择Cascader是 NG ZORRO 中处理“多级关UI组件前端vue-select选择器模式详解如何选择单选、多选与标签化功能vue select选择器模式详解如何选择单选、多选与标签化功能 vue select是一个功能强大的Vue.js选择器组件它提供了三种主要的选择模式 单前端UI组件上一篇Precedent.dev代码分割优化提升应用加载速度和用户体验下一篇终极Android系统瘦身指南Universal Android Debloater让你的手机焕发新生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
