前端UI组件设计系统【免费下载链接】ant-design-blazor基于 Ant Design 与 Blazor 的前端组件库。让开发者解放生产力实现更大价值。项目地址https://gitcode.com/ant-design-blazor/ant-design-blazor点击查看免费下载Cascader级联选择是 Ant Design Blazor 中用于从一组具有层级关联的数据集如省市区、公司层级、事物分类中进行逐级选择的组件。本文以仓库中的 basic.md 演示文档为骨架完整讲解数据模型、全部 API 参数、双向绑定与事件回调并结合 Cascader.razor.cs 与 CascaderNode.cs 的源码实现剖析其内部的层级初始化、选中状态管理与搜索匹配原理让你既能直接上手也能理解其底层工作机制。组件定位与适用场景级联选择框适合以下场景见 index.zh-CN.md需要从一组相关联的数据集合进行选择例如省市区、公司层级、事物分类等需要从较大的数据集合中进行选择此时用多级分类进行分隔可显著降低单层选项的数量方便定位比起 Select 组件Cascader 可以在同一个浮层中完成逐级选择交互路径更短、体验更好。组件本体在 Cascader.razor 与 Cascader.razor.cs 中实现继承自SelectBasestring, string因此它天然复用 Select 家族的选择浮层、键盘交互与表单集成能力同时在其上叠加了多级菜单的数据结构。五分钟上手省市区级联示例basic.md对应的演示组件为 Basic.razor它演示了最常见的省市区三级级联用法核心代码如下div Cascader Optionsoptions bind-Valuevalue SelectedNodesChangedOnChange/Cascader /div code { string value ; void OnChange(CascaderNode[] selectedNodes) { Console.WriteLine($value: {value} selected: {string.Join(,, selectedNodes.Select(x x.Value))}); } ListCascaderNode options new ListCascaderNode() { new() { Value zhejiang, Label Zhejiang, Children new CascaderNode[] { new() { Value hangzhou, Label Hangzhou, Children new CascaderNode[] { new() { Value xihu, Label West Lake, }, } }, }, }, new() { Value jiangsu, Label Jiangsu, Children new CascaderNode[] { new() { Value nanjing, Label Nanjing, Children new CascaderNode[] { new() { Value zhonghuamen, Label Zhong Hua Men, }, } }, }, } }; }这个示例包含三个关键要素Options参数传入ListCascaderNode作为级联数据源每一层的节点通过Children属性挂接下一级子节点bind-Value双向绑定组件选择完成后string value会保存最终选中节点的Value例如选中 West Lake 后value xihuSelectedNodesChanged事件每次值变化时回调参数为CascaderNode[]数组中包含从根节点到当前选中节点的完整路径可直接Join后拼接出 zhejiang / hangzhou / xihu 这样的完整路径文本。数据模型 CascaderNode 详解级联的数据源由 CascaderNode.cs 定义的CascaderNode类构成。公开可用的属性如下参数说明类型默认值Label节点名称string-Value节点值选中后回写到 Value 的值string-Disabled节点是否禁用boolfalseHasChildren是否存在子节点只读bool-Children子节点集合IEnumerableCascaderNode-值得注意的实现细节HasChildren是只读计算属性实现为Children?.Any() true即只要Children非空即认为存在子节点Level层级与ParentNode父节点引用是internal成员不面向使用者开放由组件在初始化时自动填充源码中还有内部枚举SelectedTypeEnum { Click, Hover }用于区分点击选中与悬停展开两种交互路径对应ExpandTrigger参数的两种取值。因此构建数据源时只需要关心Label、Value、Disabled、Children四个字段层级关系由树形嵌套自然表达正如 Basic 示例中 Zhejiang → Hangzhou → West Lake 的三级结构。Cascader 全部参数 API结合 index.zh-CN.md 的 API 表与源码确认Cascader组件的主要参数如下参数说明类型默认值AllowClear是否支持一键清除已选项booltrueBoundaryAdjustMode浮层边界自动调整的模式默认在可视范围内调整TriggerBoundaryAdjustModeTriggerBoundaryAdjustMode.InViewChangeOnSelect为 true 时点选每一级菜单选项都会立即改变值boolfalseStyle自定义 CSS 类名string-DefaultValue默认选中的项对应节点 Value 的字符串string-ExpandTrigger次级菜单的展开方式可选click与hoverstringclickOptions可选项数据源IEnumerableCascaderNode-Placeholder输入框占位文本string按当前语言环境中文请选择英文Please SelectPlacement浮层预设位置BottomLeft|BottomRight|TopLeft|TopRight-Size输入框大小可选large、middle、smallstring无OnChange选择完成后的回调(ListCascaderNode, string, string) void--SelectedNodesChanged选中节点数组变化回调EventCallbackCascaderNode[]--几点补充说明源码级确认Options的类型在组件定义中是IEnumerableCascaderNodeCascader.razor.cs文档表格中写成IListAntCheckbox是历史遗留笔误实际赋值ListCascaderNode即可OnChange参数在源码中已被标记为[Obsolete(Instead use SelectedNodesChanged.)]Cascader.razor.cs新代码请使用SelectedNodesChangedExpandTrigger直接决定浮层使用的触发器集合当取值为hover时注册Trigger.Hover否则注册Trigger.Click见OpenTriggers属性Cascader.razor.csAllowClear为 true 时组件会渲染清除图标点击后执行ClearSelected()清空选中节点、显示文本与值并关闭浮层、重新聚焦输入框Cascader.razor.cs。双向绑定与事件回调Cascader 的选中值绑定是字符串值绑定泛型基类SelectBasestring, string的第一个类型参数即值类型bind-Value绑定的正是最终选中叶子节点或ChangeOnSelect模式下的当前节点的Value。值发生变化时SetValue方法Cascader.razor.cs依次完成RefreshDisplayText()——按节点Level升序排序后用 / 拼接各级Label生成输入框显示文本若新值与旧值不同则写入CurrentValueAsString从而同步到bind-Value在已初始化_initialized的前提下若注册了SelectedNodesChanged则调用InvokeAsync(_selectedNodes.ToArray())把完整选中路径作为CascaderNode[]抛出兼容调用已过时的OnChange?.Invoke(_selectedNodes, value, _displayText)。因此 Basic 示例中OnChange打印的selected:是zhejiang / hangzhou / xihu这样的完整路径数组而value则是叶子节点的值xihu。默认值通过字符串指定默认值演示见 default.md 与 Default.razor其核心只有一行差异Cascader Optionsoptions bind-Valuevalue/Cascaderstring value xihu; // 默认选中 West Lake源码中SetDefaultValueCascader.razor.cs的处理逻辑是初始化时取Value ?? DefaultValue若该字符串非空则通过RefreshNodeValue递归地在整棵树中查找该值对应的节点GetNodeByValue深度优先遍历见 Cascader.razor.cs并把从根到该节点的完整路径放入_selectedNodes最终渲染为选中的显示文本。所以只需给value或DefaultValue赋值叶子节点的Value父级路径会被自动回溯补齐。ChangeOnSelect允许只选中父级选项默认情况下ChangeOnSelectfalse只有点选到叶子节点时才会提交值、关闭浮层而将ChangeOnSelecttrue后见 change.md 与 Change.razor点选每一级节点都会立即改变值因此可以只选中父级选项例如只选 Zhejiang 而不必深入 West Lake。源码中这一分支位于SetSelectedNodeCascader.razor.csif (ChangeOnSelect || !cascaderNode.HasChildren) { SetValue(cascaderNode.Value); }即只要ChangeOnSelect为 true或者当前节点没有子节点就立即提交值同时CloseAsync()只在!cascaderNode.HasChildren时执行保证点击父级时浮层继续展开下一级。Change 示例中把初始值设置为112一个不存在于数据源中的值也不会报错这只是用于演示绑定值的初始状态。展开方式click 与 hoverExpandTrigger控制次级菜单的展开方式。默认click即点选展开设为hover后对应仓库中的 hover.md 演示鼠标移入带有子节点的选项即可展开下一级。悬停路径由NodeOnMouseOver处理Cascader.razor.cs其约束是仅当ExpandTrigger hover、节点未被禁用、且node.HasChildren为 true 时才触发悬停选择的节点记录在独立的_hoverSelectedNodes列表中与点击路径_selectedNodes互不干扰避免两种交互状态混乱。浮层打开期间输入框失去焦点或点击组件外区域时会调用CascaderOnBlur将渲染节点重置回最终选中路径并清空搜索关键字。搜索、尺寸、禁用与自定义触发除 Basic 示例外仓库同目录还提供了多个衍生场景的演示均可作为实操参考搜索search.md开启ShowSearch后可在输入框直接键入关键字。源码中_searchList只收录叶子节点且每个节点的Label在初始化时被拼接为完整路径string.Join( / , pathList.Select(x x.Label))搜索时执行Label.Contains(_searchValue, StringComparison.OrdinalIgnoreCase)的大小写不敏感模糊匹配Cascader.razor.cs因此输入 hangzhou 或 HANGZHOU 都能命中尺寸size.md通过Size参数设置large/middle/small源码中映射为lg/sm前缀的 CSS 类禁用disabled.md可设置整个组件禁用Disabled或通过CascaderNode.Disabled禁用单个节点NodeOnClick与NodeOnMouseOver均会跳过Disabled节点自定义触发内容custom-trigger.md通过ChildContent渲染自定义的触发区域源码中TriggerContent ChildContent使其完全替代默认输入框Cascader.razor.cs。源码级原理层级初始化与键盘导航理解组件内部的三个关键机制有助于排查数据与状态问题层级初始化Options的 setter 在数据变化时调用ProcessParentAndDefault()其内部InitCascaderNodeState递归为每个节点填充Level从 0 递增与ParentNode引用同时把叶子节点收集进搜索列表Cascader.razor.cs。这意味着无论你的数据嵌套多深组件都能在赋值 Options 的那一刻自动建立完整的父子索引后续的路径回溯、显示文本拼接都依赖这份索引选中路径管理点击节点时SetSelectedNode会先移除同值或层级不小于当前节点的旧记录再追加新节点保证_selectedNodes始终是从根到当前节点的有序路径之后按Level升序排序确保显示文本与回调参数顺序稳定键盘导航OnKeyUpAsync内置了完整的键盘操作Cascader.razor.csArrowDown/ArrowUp在同级兄弟节点间移动ActiveNextNode/ActivePrevNodeArrowLeft/ArrowRight分别回到父级或进入子级ActiveParentNode/ActiveChildNode浮层未打开时按方向键还会自动展开浮层为无障碍与纯键盘操作提供了支持。小结Ant Design Blazor 的 Cascader 组件以CascaderNode树形数据模型为输入通过bind-Value完成字符串值的双向绑定用SelectedNodesChanged提供完整选中路径回调并以ChangeOnSelect、ExpandTrigger、ShowSearch、AllowClear、Size等参数覆盖了从选择即改变、悬停展开到搜索筛选、尺寸定制的全部常见交互形态。若要深入了解或扩展可以继续阅读 Cascader.razor.cs 的选中路径管理、CascaderNode.cs 的数据模型以及 Basic.razor 等全套演示源码从最小示例逐步演进到业务级复杂级联表单。赞分享前端UI组件设计系统【免费下载链接】ant-design-blazor基于 Ant Design 与 Blazor 的前端组件库。让开发者解放生产力实现更大价值。项目地址https://gitcode.com/ant-design-blazor/ant-design-blazor点击查看免费下载相关推荐Ant Design Blazor Cascader 级联选择组件完全指南从 API 到源码原理Ant Design Blazor Cascader 级联选择组件完全指南从 API 到源码原理 Cascader级联选择器是 Ant Design BlUI组件前端Ant Design Cascader 级联选择组件入门实战从基本用法到省市区联动Ant Design Cascader 级联选择组件入门实战从基本用法到省市区联动 Ant Design 是面向企业级应用的 React UI 组件库其中UI组件前端设计系统OpenCut 0.3.0 深度解析遮罩系统、曲线动画编辑器与 Rust/wgpu 合成器重构OpenCut 0.3.0 深度解析遮罩系统、曲线动画编辑器与 Rust/wgpu 合成器重构 版本0.3.0 发布日期2026 04 15 发布UI组件前端上一篇Fli快速上手5分钟从pip安装到完成第一次Google Flights机票搜索下一篇不止RESTchinese-poetry-api GraphQL接口与Playground完全教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考