UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读本文围绕 ng-zorro-antd 级联选择组件Cascader的搜索能力展开讲解如何通过nzShowSearch一行配置开启输入即搜、直接选中的搜索模式并结合仓库源码剖析搜索模式下的过滤、排序、高亮与选中闭环。读完本文你将掌握 Cascader 搜索的基本用法、自定义过滤与排序函数NzShowSearchOptions的完整写法以及搜索模式在底层是如何切换数据列columns的。一、功能概述为什么需要给 Cascader 加搜索Cascader 适用于从一组相关联的数据集合中进行选择的场景如省市区、公司层级、事物分类见 组件文档。当层级较深、选项较多时逐级点开菜单查找目标选项成本很高。搜索模式允许用户直接在输入框中键入关键字命中的叶子节点路径会被扁平化展示在单列结果中点选即可完成整条路径的选择。对应的演示文档 search.md 描述即为可以直接搜索选项并选择 / Search and select an option directly。完整示例代码位于 search.ts。二、最小可用示例开启搜索并选中在nz-cascader上增加[nzShowSearch]true即可开启搜索import { Component } from angular/core; import { FormsModule } from angular/forms; import { NzCascaderModule, NzCascaderOption } from ng-zorro-antd/cascader; const options: NzCascaderOption[] [ { value: zhejiang, label: Zhejiang, children: [ { value: hangzhou, label: Hangzhou, children: [ { value: xihu, label: West Lake, isLeaf: true } ] }, { value: ningbo, label: Ningbo, isLeaf: true, disabled: true } ] }, { value: jiangsu, label: Jiangsu, children: [ { value: nanjing, label: Nanjing, children: [ { value: zhonghuamen, label: Zhong Hua Men, isLeaf: true } ] } ] } ]; Component({ selector: nz-demo-cascader-search, imports: [FormsModule, NzCascaderModule], template: nz-cascader [nzOptions]nzOptions [(ngModel)]values [nzShowSearch]true (ngModelChange)onChanges($event) / }) export class NzDemoCascaderSearchComponent { readonly nzOptions: NzCascaderOption[] options; values: string[] | null null; onChanges(values: string[]): void { console.log(values, this.values); } }要点说明数据源使用NzCascaderOption[]叶子节点通过isLeaf: true标记非叶子节点通过children展开下一级类型定义见 typings.ts。values的类型为string[]即一条完整路径的值数组例如选择West Lake后得到[zhejiang, hangzhou, xihu]。示例中Ningbo被标记为disabled: true在普通浏览与搜索结果中均不可选——搜索模式下禁用状态会被继承传递见下文源码分析。事件绑定使用[(ngModel)](ngModelChange)与表单双向绑定体系完全兼容。三、核心 APInzShowSearch 的三种形态组件中nzShowSearch的输入定义位于 cascader.component.tsInput() nzShowSearch: boolean | NzShowSearchOptions false;默认值为false不显示搜索输入框。它接受布尔值或对象两种形态取值说明false关闭搜索默认true开启搜索使用默认的过滤与排序逻辑NzShowSearchOptions对象开启搜索并自定义filter/sorter函数对象形态的接口定义如下见 typings.tsexport type NzCascaderFilter (searchValue: string, path: NzCascaderOption[]) boolean; export type NzCascaderSorter (a: NzCascaderOption[], b: NzCascaderOption[], inputValue: string) number; export interface NzShowSearchOptions { filter?: NzCascaderFilter; sorter?: NzCascaderSorter; }对应组件文档中的参数表doc/index.zh-CN.md为参数说明类型默认值filter可选选择是否保留选项的过滤函数每级菜单的选项都会被匹配(inputValue: string, path: NzCascaderOption[]): boolean-sorter可选按照到每个最终选项的路径进行排序默认按照原始数据的顺序(a: NzCascaderOption[], b: NzCascaderOption[], inputValue: string): number-注意文档中明确说明nzShowSearch不能和nzLoadData同时使用——动态加载异步数据源与本地全量搜索在数据获取方式上冲突。默认 filter对整条路径做包含匹配当nzShowSearch为true时使用的是内置默认过滤函数。其实现位于 cascader.service.tsconst defaultFilter: NzCascaderFilter (i, p) p.some(o { const label this.getOptionLabel(o); return !!label label.indexOf(i) ! -1; });这里的p是从根到当前候选节点的完整路径数组因此默认行为是对路径上每一级的 label 做子串匹配——只要某一级的 label 包含搜索词该叶子节点就会作为结果保留。这也是文档所述每级菜单的选项都会被匹配的具体含义。getOptionLabel会读取nzLabelProperty指定的属性默认label因此自定义字段名时搜索同样生效。自定义 filter忽略大小写如果希望搜索时忽略大小写可传入自定义filter示例同样来自组件文档const filter: NzCascaderFilter (i, p) { return p.some(o { const label o.label; return !!label label.toLowerCase().indexOf(i.toLowerCase()) ! -1; }); };用法nz-cascader [nzOptions]nzOptions [(ngModel)]values [nzShowSearch]{ filter: filter } /filter返回true表示保留该选项返回false则过滤掉。由于它是纯函数你可以自由扩展例如按value匹配、支持模糊匹配、首字母匹配等。自定义 sorter控制结果排序搜索命中后默认按原始数据顺序展示结果。若希望按路径相关度排序传入sorterimport { NzCascaderOption, NzCascaderSorter } from ng-zorro-antd/cascader; const sorter: NzCascaderSorter (a, b, inputValue) { // a、b 为两条命中路径inputValue 为当前搜索词 const scoreA a.some(o o.label?.startsWith(inputValue)) ? 0 : 1; const scoreB b.some(o o.label?.startsWith(inputValue)) ? 0 : 1; return scoreA - scoreB; // 前缀命中的路径排在前面 };sorter的返回值遵循Array.prototype.sort的语义负数表示a在前正数表示b在前。可以从搜索结果中提取输入关键字inputValue参数来设计加权策略例如前缀命中 中间命中 路径层级更浅。四、源码级原理搜索模式的完整闭环4.1 从输入到搜索模式的切换搜索模式由组件与服务共同维护。用户在输入框键入内容时inputValue的 setter 会触发toggleSearchingModecascader.component.tsset inputValue(inputValue: string) { this.inputString inputValue; this.toggleSearchingMode(!!inputValue); } private toggleSearchingMode(toSearching: boolean): void { if (this.inSearchingMode ! toSearching) { this.cascaderService.setSearchingMode(toSearching); } if (this.inSearchingMode) { this.cascaderService.prepareSearchOptions(this.inputValue); } }输入为空 → 退出搜索模式恢复级联列输入非空 → 进入搜索模式并即时调用prepareSearchOptions重新过滤。输入框本身复用 Select 组件的NzSelectSearchComponent模板见 cascader.component.ts支持 IME 组合输入isComposing与自动聚焦。4.2 列快照搜索不破坏原始级联状态进入搜索模式前服务会把当前级联列保存为快照cascader.service.tssetSearchingMode(toSearching: boolean): void { this.inSearchingMode toSearching; if (toSearching) { this.clearSearchOptions(); // 若搜索期间重置 nzOptions先清理缓存 this.columnSnapshot [...this.columns]; // 保存多列快照 this.activatedNodes []; } else { // 退出搜索恢复快照列并重建已选中路径的激活状态 ... } }这意味着搜索结果的展示是临时的搜索结束后组件会恢复原来的多列级联视图并重新激活已选中节点所在路径trackAncestorColumnData/trackAncestorActivatedNodes。4.3 过滤与单列结果prepareSearchOptionscascader.service.ts完成核心过滤逻辑递归遍历第一列的全部根节点loopParent处理非叶子、loopChild处理叶子对每个候选节点用filter(searchValue, path)判断是否命中命中则记录其路径命中节点的title会被临时改写为路径串如Zhejiang / Hangzhou / West Lake用于结果展示若有sorter按路径数组排序最后把结果压平为单列this.columns [results]并触发重绘。同时路径上任意节点的disabled状态会沿路径传递forceDisabled保证搜索结果中禁用路径的叶子同样不可选——这正是示例中Ningbo即使被搜索到也无法选中的原因。4.4 选中与退出搜索搜索模式下点击命中项时组件判断inSearchingMode后走搜索专用选中路径cascader.component.tsonOptionClick(node, columnIndex, event) { ... this.inSearchingMode ? this.cascaderService.setSearchOptionSelected(node, this.nzMultiple) : this.cascaderService.setNodeActivated(node, columnIndex, !this.nzMultiple); }setSearchOptionSelectedcascader.service.ts在完成选中后通过$quitSearching通知组件清空输入框、恢复下拉宽度样式并触发重绘——用户看到的直观效果是点选搜索结果后输入框立即清空、级联视图还原。另外两点与搜索强相关的实现细节空结果展示搜索无命中时下拉展示空态。setDropdownStylescascader.component.ts会依据搜索模式且无结果判断shouldShowEmpty并将下拉宽度对齐输入框宽度内容由nzNotFoundContent或nzEmbedEmpty兜底。搜索模式下的高亮渲染选项时NzCascaderOptionComponent接收[highlightText]inSearchingMode ? inputValue : cascader.component.ts即仅在搜索模式下对命中关键字做高亮展示普通级联浏览时不做高亮。键盘支持搜索模式下BACKSPACE、LEFT/RIGHT_ARROW保留输入框原生编辑能力cascader.component.tsENTER选中当前高亮结果UP/DOWN在结果间移动保证纯键盘可用。五、与其他选项的联动及注意事项场景结论多选模式nzMultiple与搜索可同时开启搜索命中项会进入多选标签列表选中后菜单保持展开源码中$nodeSelected订阅按!this.nzMultiple决定是否关闭菜单动态加载nzLoadData与nzShowSearch不可同时使用组件文档明确说明如需搜索大型远程数据可自行实现搜索接口 nzOptions重建自定义字段默认 filter 通过nzLabelProperty读取 label自定义字段名后搜索依然按真实 label 匹配表单状态搜索框外观与禁用nzDisabled、校验状态nzStatus、形态变体nzVariant完全继承 Cascader 主组件样式体系选中回调无论普通选中还是搜索选中都会统一走ngModelChange/nzSelectionChange业务无需区分来源六、小结Cascader 的搜索功能是级联浏览 扁平搜索两种交互的融合nzShowSearch一行开启内置 filter 对路径逐级匹配需要更精细的控制时NzShowSearchOptions的filter与sorter提供完全自定义的空间。底层实现上cascader.service.ts 通过列快照、路径映射与$quitSearching事件保证了搜索态与级联态的无缝切换且不破坏已选值与禁用规则。配合键盘导航、关键字高亮与空态兜底搜索模式让深层级联数据的选取体验大幅提升。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐PPT Master SVG图表模板指南33种图表3步做出可编辑PPTPPT Master SVG图表模板指南33种图表3步做出可编辑PPT PPT Master是一个AI驱动的演示文稿工具把文档变成可编辑的PPT。它自带3UI组件前端ng-zorro-antd Cascader 自定义校验状态nzStatus实战指南ng zorro antd Cascader 自定义校验状态nzStatus实战指南 nzStatus 是 ng zorro antd Cascader级UI组件前端ng-zorro-antd Cascader 响应式表单实战从表单绑定到 Reset 重置清空ng zorro antd Cascader 响应式表单实战从表单绑定到 Reset 重置清空 导读 本文以 ng zorro antd 组件库中 cascaUI组件前端上一篇gh_mirrors/exam/examples优化技术模型层融合策略下一篇揭秘gh_mirrors/v41/v4GatsbyReactMarkdown静态网站终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考