前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载级联选择框Cascader是 ant-design-vue 中用于处理多级关联数据选择的核心组件常用于省市区、组织层级、商品分类等具有父子层级关系的场景。本文将基于 components/cascader/index.en-US.md 官方文档结合 components/cascader/index.tsx 源码实现与 components/cascader/demo 目录下的 14 个真实示例系统讲解 Cascader 的全部配置项、事件、方法与高级用法帮助你快速掌握该组件的完整能力。When To Use什么场景适合使用级联选择官方文档给出了三个典型的适用场景需要从一组相互关联的数据集中进行选择例如省/市/区、公司层级、事物分类等树状结构数据数据量大且具有多级分类通过逐级分类拆分降低单次选择的复杂度希望在一个浮层中完成级联选择提供更好的用户体验。简单来说只要你的选择数据天然存在父子层级关系如 components/cascader/demo/basic.vue 中的省份 → 城市 → 景区数据级联选择框就是比普通下拉框更合适的交互方案。基础用法最简可运行的 Cascader官方文档开篇给出了最基础的使用示例a-cascader :optionsoptions v-model:valuevalue /对应 components/cascader/demo/basic.vue 中的完整实现template a-cascader v-model:valuevalue :optionsoptions placeholderPlease select / /template script langts setup import { ref } from vue; import type { CascaderProps } from ant-design-vue; const options: CascaderProps[options] [ { value: zhejiang, label: Zhejiang, children: [ { value: hangzhou, label: Hangzhou, children: [{ value: xihu, label: West Lake }], }, ], }, { value: jiangsu, label: Jiangsu, children: [ { value: nanjing, label: Nanjing, children: [{ value: zhonghuamen, label: Zhong Hua Men }], }, ], }, ]; const value refstring[]([]); /script需要注意两个关键点options是树形嵌套结构每个节点可包含value、label与childrenvalue是路径数组如[zhejiang, hangzhou, xihu]v-model:value双向绑定选中路径而非单个叶子值。组件底层基于vc-cascader实现见 components/vc-cascader 目录外层 components/cascader/index.tsx 负责与 ant-design-vue 的主题、表单、尺寸体系对接并将内部 Select 的视觉样式复用到 Cascader 上。API 总览完整参数表以下参数表完整继承自官方文档并补充了参数的作用说明。默认引入方式为全局注册后的a-cascader标签。PropertyDescriptionTypeDefaultVersionallowClear是否允许清除booleantrueautofocus组件挂载时是否自动获取焦点booleanfalsebordered是否有边框样式booleantrue3.2clearIcon自定义清除图标slot-3.2changeOnSelect单选时生效设为 true 后每次选中都触发 change允许只选父级booleanfalsedisabled是否禁用选择booleanfalsedisplayRender展示已选项的渲染函数可使用#displayRender{labels, selectedOptions}({labels, selectedOptions}) VNodelabels labels.join( / )popupClassName弹出浮层额外的 classNamestring-4.0dropdownStyle弹出浮层额外的样式CSSProperties{}3.0expandIcon自定义当前项展开图标slot-3.0expandTrigger展开当前项的方式点击或悬停click|hoverclickfieldNames自定义 label、value、children 的字段名object{ label: label, value: value, children: children }getPopupContainer选择器浮层渲染到的父节点默认渲染到body。出现定位问题时可改为可滚动内容并设置相对定位Function(triggerNode)() document.bodyloadData动态加载选项注意不能与showSearch同时使用(selectedOptions) void-maxTagCount最多显示的 tag 数量responsive模式会消耗渲染性能number |responsive-3.0maxTagPlaceholder未展示 tag 的占位内容v-slot | function(omittedValues)-3.0multiple是否支持多选boolean-3.0notFoundContent无匹配结果时展示的内容string | slotNot Foundopen控制级联浮层的显隐boolean-3.0options级联数据源Option[]-placeholder输入框占位符stringPlease selectplacement使用内置浮层对齐配置bottomLeft|bottomRight|topLeft|topRightbottomLeft3.0removeIcon自定义移除图标slot-3.2searchValue设置搜索值需配合showSearch使用string-3.0showSearch单选模式下是否显示搜索框boolean | objectfalsesize输入框尺寸large|default|smalldefaultstatus校验状态error | warning-3.3.0suffixIcon自定义后缀图标string | VNode | slot-showCheckedStrategy多选时选中项的展示方式Cascader.SHOW_CHILD只显示子节点Cascader.SHOW_PARENT仅当父节点下所有子节点都被选中时才显示父节点Cascader.SHOW_PARENT|Cascader.SHOW_CHILDCascader.SHOW_PARENT3.3.0tagRendermultiple模式下自定义 tag 渲染slot-3.0value(v-model)选中的值string[] | number[]-与 Select 体系的继承关系从源码看components/cascader/index.tsx 中的cascaderProps()通过...omit(vcCascaderProps(), [customSlots, checkable, options])继承了vc-cascader的全部属性仅排除掉内部使用的customSlots、checkable与options再补充声明multiple、size、bordered、placement、suffixIcon、status、popupClassName以及已废弃的dropdownClassName等属性。同时组件在setup中调用useConfigInject(cascader, props)注入 ConfigProvider 配置并使用useSelectStyle与useStyle分别应用 Select 与 Cascader 的样式components/cascader/style/index.ts因此它在外观、尺寸、状态上与 Select 保持完全一致的设计语言。注意dropdownClassName已被标记为deprecated源码会在非生产环境通过devWarning提示改用popupClassName见 components/cascader/index.tsx。数据源 Option结构、字段与叶子节点官方文档定义的Option接口如下interface Option { value: string | number; label?: VNode; disabled?: boolean; children?: Option[]; // 指定该节点是否为叶子节点当设置了 loadData 时生效。 // false 会强制将该树节点视为父节点。 // 即使当前节点没有 children也会显示展开图标。 isLeaf?: boolean; }各字段含义value必填节点值最终会以路径数组形式出现在v-model:value中label节点展示文案也支持 VNode 以便渲染复杂内容disabled禁用该节点参考 components/cascader/demo/disabled-option.vuechildren子节点数组形成级联层级isLeaf与loadData配合使用。当某节点isLeaf: false且无 children 时会展示展开图标并触发加载回调默认情况下无 children 的节点会被视为叶子节点。自定义字段名 fieldNames当后端返回的数据字段不叫label/value/children时可通过fieldNames重映射如 components/cascader/demo/fields-name.vue 所示a-cascader v-model:valuevalue :field-names{ label: name, value: code, children: items } :optionsoptions placeholderPlease select /此时数据需写成const options [ { code: zhejiang, name: Zhejiang, items: [ { code: hangzhou, name: Hangzhou, items: [{ code: xihu, name: West Lake }] }, ], }, ];changeOnSelect允许只选父级默认情况下Cascader 要求必须选中叶子节点才触发 change。当希望选择到某一级就立即提交例如只选到省份时开启changeOnSelect即可见 components/cascader/demo/change-on-select.vuea-cascader v-model:valuevalue :optionsoptions placeholderPlease select change-on-select /官方文档特别注明该属性仅对单选模式生效。expandTrigger 与 expandIcon展开交互与图标定制移入展开通过expand-triggerhover可改为鼠标移入即展开下级菜单、点击完成选择见 components/cascader/demo/hover.vuea-cascader v-model:valuevalue :optionsoptions expand-triggerhover placeholderPlease select /默认值为click即点击展开。自定义展开图标expandIcon是一个 slot可完全替换默认的展开箭头。从源码看未提供该 slot 时组件会根据directionRTL 与否自动选择RightOutlined或LeftOutlined作为展开图标components/cascader/index.tsx并在节点处于加载态时渲染带spin的LoadingOutlined加载图标。搜索 showSearch在级联中直接搜选项单选模式下通过showSearch开启搜索。官方文档的用法示例为a-cascader v-model:valuevalue :optionsoptions :show-search{ filter } placeholderPlease select /对应的自定义filter函数见 components/cascader/demo/search.vueimport type { ShowSearchType } from ant-design-vue/es/cascader; const filter: ShowSearchType[filter] (inputValue, path) { return path.some(option option.label.toLowerCase().indexOf(inputValue.toLowerCase()) -1); };filter接收(inputValue, path)两个参数path是从根到当前节点的完整路径数组返回true表示该选项进入过滤结果集。上面的实现表示路径上任一节点的 label 包含输入值即命中。showSearch 对象配置项当showSearch传对象时支持以下字段PropertyDescriptionTypeDefaultfilter过滤函数接收 inputValue 和 path返回 true 则包含该选项否则排除function(inputValue, path): booleanlimit过滤结果的数量上限number | false50matchInputWidth结果列表宽度是否等于输入框宽度booleanrender渲染过滤结果可使用#showSearchRender{inputValue, path}function({inputValue, path}): VNodesort对过滤结果排序function(a, b, inputValue)从源码看components/cascader/index.tsx当showSearch为真值时组件会将其与内置的defaultSearchRender合并默认渲染逻辑会对命中的关键词做高亮用-menu-item-keyword样式包裹匹配片段见 components/cascader/index.tsx并将路径各级 label 用/连接展示。注意showSearch暂不支持服务端搜索官方 demo 中引用了 ant-design/ant-design 的 issue #5547 说明此限制搜索在客户端完成同时官方文档强调loadData与showSearch无法一起使用。多选 multiple批量选择与展示策略multiple模式自 3.0 起支持见 components/cascader/demo/multiple.vueh4Cascader.SHOW_PARENT/h4 a-cascader v-model:valuevalue stylewidth: 100% multiple max-tag-countresponsive :optionsoptions placeholderPlease select / h4Cascader.SHOW_CHILD/h4 a-cascader v-model:valuevalue stylewidth: 100% multiple max-tag-countresponsive :optionsoptions placeholderPlease select :show-checked-strategyCascader.SHOW_CHILD /多选模式下需要理解两个核心概念showCheckedStrategy控制已选项的展示方式。默认Cascader.SHOW_PARENT——当父节点下所有子节点都被选中时只展示父节点Cascader.SHOW_CHILD则始终展示叶子节点。这两个常量通过Cascader.SHOW_PARENT/Cascader.SHOW_CHILD静态属性访问在源码中由Object.assign(Cascader, { SHOW_CHILD, SHOW_PARENT })挂载components/cascader/index.tsx底层实现在 components/vc-cascader 中。maxTagCount限制 tag 展示数量responsive会根据宽度自适应折叠。与多选相关的补充说明displayRender在multiple模式下不生效源码会在非生产环境抛出警告提示改用tagRendercomponents/cascader/index.tsxtagRenderslot 可自定义每个已选项 tag 的内容与样式如 components/cascader/demo/tagRender.vue 中将其渲染为蓝色a-taga-cascader v-model:valuevalue multiple :optionsoptions placeholderPlease select template #tagRenderdata a-tag :keydata.value colorblue{{ data.label }}/a-tag /template /a-cascaderloadData大数据量下的动态加载当级联数据量很大、子节点需要按需请求时使用loadData懒加载子选项。参考 components/cascader/demo/lazy.vuea-cascader v-model:valuevalue :optionsoptions :load-dataloadData placeholderPlease select change-on-select /const options refCascaderProps[options]([ { value: zhejiang, label: Zhejiang, isLeaf: false }, { value: jiangsu, label: Jiangsu, isLeaf: false }, ]); const loadData: CascaderProps[loadData] selectedOptions { const targetOption selectedOptions[selectedOptions.length - 1]; targetOption.loading true; // 模拟异步请求子选项 setTimeout(() { targetOption.loading false; targetOption.children [ { label: ${targetOption.label} Dynamic 1, value: dynamic1 }, { label: ${targetOption.label} Dynamic 2, value: dynamic2 }, ]; options.value [...options.value]; }, 1000); };使用要点顶层选项需要设置isLeaf: false否则组件会把无 children 的节点当作叶子节点不触发加载加载过程中给节点设置loading true组件会展示旋转加载图标加载完成后将children写入目标节点并用展开运算符创建新数组触发响应式更新官方文档明确loadData不能与showSearch同时使用。自定义渲染displayRender 与自定义触发器自定义已选项展示displayRender接收{ labels, selectedOptions }可用于在输入框内定制已选项的展示例如 components/cascader/demo/custom-render.vue 为最后一项附加可点击的邮编链接a-cascader v-model:valuevalue placeholderPlease select :optionsoptions stylewidth: 100% template #displayRender{ labels, selectedOptions } span v-for(label, index) in labels :keyselectedOptions[index].value span v-ifindex labels.length - 1 {{ label }} ( a clicke handleAreaClick(e, label, selectedOptions[index]) {{ selectedOptions[index].code }} /a ) /span span v-else{{ label }} //span /span /template /a-cascader默认展示为各级 label 用/连接默认值labels labels.join( / )。源码将displayRender同时兼容函数与 slot 两种传法displayRender{props.displayRender || slots.displayRender}components/cascader/index.tsx。自定义触发器Cascader 选择框默认是一个带前缀图标的下拉触发区域可通过 slot 完全替换触发 UI实现自定义触发器参考 components/cascader/demo/custom-trigger.vue适合把级联面板嵌入按钮、文本等任意交互元素中。事件、v-model 与实例方法事件Events NameDescriptionArgumentsversionchange完成级联选择时触发(value, selectedOptions) void-dropdownVisibleChange浮层显示/隐藏时触发(value) void-3.0search输入值变化时触发(value) void-1.5.4其中change事件在源码中通过handleChange转发依次触发update:value驱动v-model:value、change并调用表单上下文的onFieldChange通知 FormItem 校验components/cascader/index.tsx因此组件在 Form 中能自动参与校验与字段状态同步。实例方法NameDescriptionblur()移除焦点focus()获取焦点组件通过expose({ focus, blur })暴露这两个方法components/cascader/index.tsx可配合模板 ref 调用例如a-cascader refcascaderRef /后执行cascaderRef.value?.focus()。测试文件 components/cascader/tests/index.test.js 中通过共享的focusTest工具验证了焦点行为的正确性。外观与状态尺寸、边框、校验与浮层sizelarge/default/small三档尺寸源码会为large、small分别添加-lg、-sm修饰类components/cascader/index.tsx并优先读取 ConfigProvider 与 Space Compact 注入的尺寸bordered3.2 起支持设为false得到无边框样式对应类名-borderlessstatus3.3.0 起支持error/warning校验状态源码通过getMergedStatus合并 FormItem 上下文状态与自身状态并应用getStatusClassNames生成状态类名components/cascader/index.tsx在 Form 中可自动继承校验状态placementbottomLeft/bottomRight/topLeft/topRight默认bottomLeft在 RTL 环境下默认自动切换为bottomRightcomponents/cascader/index.tsxpopupClassName / dropdownStyle分别设置浮层的额外类名与内联样式用于浮层定制getPopupContainer浮层默认渲染到document.body当父容器发生滚动或定位如overflow: hidden导致浮层位置异常时可传入函数将其渲染到可滚动容器内allowClear / clearIcon / removeIcon / suffixIcon清除能力与图标定制图标相关处理复用 Select 的getIcons工具components/cascader/index.tsx且clearIcon、removeIcon均支持 slot 形式3.2 起notFoundContent无匹配结果时显示的内容默认Not Found源码中未提供时会回退到 ConfigProvider 的renderEmpty(Cascader)空状态components/cascader/index.tsx。源码架构小结从整体架构看Cascader 采用外层组件 vc-cascader 内核的分层设计components/vc-cascader 是组件内核包含Cascader.tsx主文件、OptionList面板渲染、useSearchConfig/useSearchOptions搜索逻辑、useEntities节点实体管理、useDisplayValues已选项展示值计算等 hooks以及commonUtil/treeUtil树工具components/cascader/index.tsx 是面向用户的外层封装负责合并 vc 属性并补充 Vue 化声明、注入 ConfigProvider / Form / DisabledContext 上下文、计算前缀类名与 SSR 样式、组装展开/清除/后缀/加载图标、转发事件并暴露 focus/blur 方法components/cascader/demo 提供 14 个覆盖基本用法、搜索、多选、懒加载、字段映射、hover、自定义渲染、tag 定制等场景的完整示例components/cascader/tests/index.test.js 覆盖面板显隐、搜索过滤、焦点行为等核心逻辑是验证组件行为可靠性的直接依据。总结ant-design-vue 的 Cascader 组件以路径数组作为数据模型通过丰富的配置项覆盖了从最基础的省市区选择到多选、搜索、懒加载、自定义渲染等全部实际场景。掌握options树结构、fieldNames字段映射、changeOnSelect父级选择、showCheckedStrategy多选展示策略、loadData动态加载与showSearch搜索配置这六个核心能力即可在项目中游刃有余地处理一切层级关联数据的选择需求。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Hugo Theme Zzo画廊功能详解创建令人惊艳的图片展示页面Hugo Theme Zzo画廊功能详解创建令人惊艳的图片展示页面 想要为你的Hugo博客添加专业的图片展示功能吗 Hugo Theme Zzo提供了强前端UI组件设计系统ant-design Cascader 级联选择组件完全指南API、数据源结构与实战用法ant design Cascader 级联选择组件完全指南API、数据源结构与实战用法 级联选择框Cascader是 ant design 中处理省市区UI组件前端设计系统别再被环境配置劝退零基础也能跑起第一个 AI 模型的两种路径别再被环境配置劝退零基础也能跑起第一个 AI 模型的两种路径 实习生小林入职第一天leader 丢给他一个任务跑通一个情感分析模型。他兴冲冲复制了一段代码前端UI组件设计系统上一篇从乱码到完美OCRmyPDF自定义字体全攻略下一篇Sniffnet网络协议解析HTTP/HTTPS流量识别方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考