前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载TreeSelect是 ant-design-vue 中用于在树形结构数据中进行选择的控件它融合了Select的搜索、多选、下拉能力与Tree的层级展示能力适合组织架构、目录结构等具备天然层级关系的数据选择场景。本文以官方文档 components/tree-select/index.en-US.md 为骨架结合组件源码 components/tree-select/index.tsx 与官方示例源码系统讲解其全部 API、核心勾选策略的实现原理并给出可直接复用的实战代码。读完本文你将掌握 TreeSelect 的基本用法、勾选策略取舍、异步加载、字段映射等完整技能。When To Use什么时候选择 TreeSelectTreeSelect与Select非常相似但它的可选项value以树形结构提供。凡是数据本身具有层级归属关系的场景都适合使用它典型例子包括企业组织架构部门 → 子部门 → 员工目录/文件结构文件夹 → 子文件夹 → 文件商品分类一级分类 → 二级分类 → SKU权限树、地区级联等一切父子从属的数据。与级联选择器Cascader相比TreeSelect 更强调在树中任意位置选择含父节点且支持 checkbox 勾选、多选、搜索过滤、异步加载等能力。基本用法从一份 treeData 开始TreeSelect 最推荐的用法是直接传入treeData数组而非手动构造TreeNode节点。参考官方示例 components/tree-select/demo/basic.vue一个最简用法如下template a-tree-select v-model:valuevalue show-search stylewidth: 100% :dropdown-style{ maxHeight: 400px, overflow: auto } placeholderPlease select allow-clear tree-default-expand-all :tree-datatreeData tree-node-filter-proplabel template #title{ value: val, label } b v-ifval parent 1-1 stylecolor: #08csss/b template v-else{{ label }}/template /template /a-tree-select /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; const value refstring(); const treeData refTreeSelectProps[treeData]([ { label: root 1, value: root 1, children: [ { label: parent 1, value: parent 1, children: [ { label: parent 1-0, value: parent 1-0, children: [ { label: my leaf, value: leaf1 }, { label: your leaf, value: leaf2 }, ], }, { label: parent 1-1, value: parent 1-1 }, ], }, { label: parent 2, value: parent 2 }, ], }, ]); /script几个关键点v-model:value双向绑定当前选中值单选用字符串多选用字符串数组show-search开启下拉面板内的搜索输入框tree-default-expand-all默认展开全部节点也可用treeDefaultExpandedKeys精确指定tree-node-filter-prop指定搜索过滤时按哪个字段匹配默认为value这里改为label#title插槽可自定义节点标题渲染插槽参数包含value、label、title等字段。从源码 components/tree-select/index.tsx 可以看到组件在创建时通过initDefaultProps设置了listHeight: 256、treeIcon: false、listItemHeight: 26、bordered: true等默认值并在setup中对废弃用法children传节点、replaceFields、dropdownClassName给出开发期警告引导用户使用treeData与fieldNames。TreeSelect 完整 API 参考Tree props核心属性下表为官方文档的完整属性清单并补充了源码层面的说明列中源码说明为本文基于 components/tree-select/index.tsx 与 components/vc-tree-select 的补充属性说明类型默认值版本allowClear是否允许清空booleanfalsedefaultValue设置初始选中的 treeNodestring | string[]-disabled是否禁用booleanfalsepopupClassName下拉菜单的 classNamestring-4.0dropdownMatchSelectWidth下拉菜单是否与选择框同宽。默认设置与输入框相同min-width当值小于选择框宽度时被忽略false时会禁用虚拟滚动boolean | numbertruedropdownStyle下拉菜单的样式object-fieldNames用 treeData 中对应的字段替换 treeNode 中的 label、value、children 字段object{ children: children, label: title, value: value }3.0.0filterTreeNode是否按输入值过滤节点默认使用treeNodeFilterProp指定的字段也可传函数(inputValue: string, treeNode: TreeNode) booleanboolean | FunctionFunctiongetPopupContainer设置下拉菜单的挂载容器默认在body中创建div可重置为滚动区域并做相对定位Function(triggerNode)() document.bodylabelInValue是否将 label 嵌入 value使 value 从string变为{ value: string, label: VNode, halfChecked: string[] }booleanfalselistHeight下拉面板高度配合虚拟滚动number256loadData异步加载数据function(node)-maxTagCount多选时最多显示的标签数量number-maxTagPlaceholder超出 maxTagCount 的占位内容slot / function(omittedValues)-multiple是否多选启用treeCheckable时会被强制为truebooleanfalsenotFoundContent无匹配结果时显示的内容slotNot Foundplaceholder选择框占位文本string | slot-placement弹出位置bottomLeftbottomRighttopLefttopRightbottomLeft3.3.0replaceFields替换 treeNode 的 label、value、key、children 字段已废弃请改用 fieldNamesobject{ children: children, label: title, value: value }1.6.13.0.0 废弃searchPlaceholder搜索输入框占位文本string | slot-searchValue(v-model)配合search事件做受控搜索值string-showCheckedStrategy勾选后在输入框中展示已选项的方式。TreeSelect.SHOW_ALL展示全部勾选项含父节点TreeSelect.SHOW_PARENT只展示父节点TreeSelect.SHOW_CHILD只展示子节点enum { SHOW_ALL, SHOW_PARENT, SHOW_CHILD }TreeSelect.SHOW_CHILDshowSearch是否在下拉菜单中显示搜索框仅单选模式生效booleanfalsesize选择框尺寸large/small/defaultstringdefaultstatus校验状态error | warning-3.3.0suffixIcon自定义后缀图标VNode | slot-tagRender多选模式下自定义标签渲染(props) slot-3.0title自定义标题slot-3.0.0treeCheckable是否在节点前显示 checkboxbooleanfalsetreeCheckStrictly是否严格勾选父子不再关联该模式会强制labelInValue为 truebooleanfalsetreeData节点数据设置后无需手工构造节点需保证每个 value 唯一array{ value, title, children, [disabled, disableCheckbox, selectable] }[]treeDataSimpleMode扁平数据简单模式schema 变为[{ id, pId, value, title, ... }]pId 为父节点 id可传对象{ id, pId, rootPId }自定义字段名false | objectfalsetreeDefaultExpandAll是否默认展开全部节点booleanfalsetreeDefaultExpandedKeys默认展开的节点 key 数组string[] | number[]-treeExpandedKeys(v-model)受控展开 keystring[] | number[]-treeIcon是否在节点标题前显示图标无默认样式需自行设置booleanfalsetreeLoadedKeys受控的已加载节点 key仅配合loadData使用string[][]3.3.0treeLine是否显示连接线参考 Tree - showLineboolean | objectfalse3.0treeNodeFilterProp当filterTreeNode返回 true 时用于过滤的字段stringvaluetreeNodeLabelProp作为选择框内容的渲染字段stringtitlevalue(v-model)当前选中的 treeNode 值string | string[]-virtual设为 false 时禁用虚拟滚动booleantrue3.0源码补充说明在 components/tree-select/index.tsx 中treeSelectProps()从底层vc-tree-select的属性中过滤了showTreeIcon、treeMotion、inputIcon、getInputElement、treeLine、customSlots等内部能力再对外暴露suffixIcon、size、bordered、treeLine、replaceFields、placement、status、popupClassName等属性同时保留onUpdate:value、onUpdate:treeExpandedKeys、onUpdate:searchValue三个update:事件以支持v-model语法。Events事件事件名说明参数版本change选中节点或输入值变化时触发function(value, label, extra)dropdownVisibleChange下拉面板打开/关闭时触发function(open)3.0search搜索输入变化时触发function(value: string)select选中某个节点时触发function(value, node, extra)treeExpand节点展开时触发function(expandedKeys)源码补充说明在 components/tree-select/index.tsx 中可以看到事件与v-model的联动实现——handleChange会依次触发update:value、change并通知 Form 的onFieldChangehandleTreeExpand会触发update:treeExpandedKeys与treeExpandhandleSearch会触发update:searchValue与search。因此searchValue、treeExpandedKeys都可以通过v-model:search-value、v-model:tree-expanded-keys做受控绑定。Tree Methods实例方法名称说明blur()移除焦点focus()获取焦点方法通过组件 ref 调用。源码 components/tree-select/index.tsx 使用expose暴露focus与blur内部委托给底层VcTreeSelect的 ref 实现。TreeNode props节点属性官方建议优先使用treeData而非手工构造TreeNode以避免手动维护的麻烦。属性说明类型默认值版本checkable在 checkable 模式下该节点是否显示 checkboxboolean-disableCheckbox禁用该节点的 checkboxbooleanfalsedisabled是否禁用booleanfalseisLeaf是否为叶子节点booleanfalsekey必填属性树内唯一string | number-selectable是否可选中booleantruetitle节点显示内容string---value默认作为treeNodeFilterProp使用树内唯一string-勾选模式与 showCheckedStrategy源码级原理勾选模式treeCheckable是 TreeSelect 最常用的能力之一官方示例见 components/tree-select/demo/checkable.vuetemplate a-tree-select v-model:valuevalue stylewidth: 100% :tree-datatreeData tree-checkable allow-clear :show-checked-strategySHOW_PARENT placeholderPlease select tree-node-filter-proplabel / /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; import { TreeSelect } from ant-design-vue; const SHOW_PARENT TreeSelect.SHOW_PARENT; const treeData: TreeSelectProps[treeData] [ { label: Node1, value: 0-0, children: [{ label: Child Node1, value: 0-0-0 }], }, { label: Node2, value: 0-1, children: [ { label: Child Node3, value: 0-1-0, disabled: true }, { label: Child Node4, value: 0-1-1 }, { label: Child Node5, value: 0-1-2 }, ], }, ]; const value refstring[]([0-0-0]); /script几个要点tree-checkable开启勾选后multiple会被强制为true源码中isMultiple computed(() !!(props.treeCheckable || props.multiple))见 components/tree-select/index.tsx默认showCheckedStrategy为TreeSelect.SHOW_CHILD即输入框中只展示勾选的叶子/子节点如需回显父节点请改用SHOW_PARENT常量从TreeSelect.SHOW_ALL / SHOW_PARENT / SHOW_CHILD静态导出见 components/tree-select/index.tsx。三种策略的过滤算法三种策略的差异由底层formatStrategyValues实现源码位于 components/vc-tree-select/utils/strategyUtil.tsSHOW_CHILD遍历勾选值若某节点存在子节点、且其子节点全部被勾选或为禁用节点则说明该父节点已被子节点代表从结果中剔除该父节点最终只留下必要的子节点集合SHOW_PARENT遍历勾选值若某节点存在父节点、且父节点已被勾选则剔除该子节点最终只保留最上层的父节点SHOW_ALL不过滤原样返回全部勾选值父子同时展示。理解该算法有助于预判勾选了父节点 部分子节点时输入框的展示结果避免前后端参数对不上。多选、标签与自定义渲染多选模式参考 components/tree-select/demo/multiple.vue在节点上添加multiple即可a-tree-select v-model:valuevalue !-- value 为 string[] -- multiple allow-clear :tree-datatreeData tree-default-expand-all show-search tree-node-filter-proplabel template #title{ value: val, label } b v-ifval parent 1-1 stylecolor: #08c{{ val }}/b template v-else{{ label }}/template /template /a-tree-select多选场景常用的配套属性maxTagCount限制标签显示数量超出部分折叠maxTagPlaceholder折叠占位可传插槽(omittedValues)显示已选 n 项等tagRender3.0完全自定义标签渲染labelInValue将 value 变为{ value, label, halfChecked }对象结构halfChecked用于表达半选的父节点状态。异步加载loadData treeDataSimpleMode当树节点需要按需从后端拉取时使用loadData配合treeDataSimpleMode扁平数据模式最为方便。官方示例见 components/tree-select/demo/async.vuetemplate a-tree-select v-model:valuevalue tree-data-simple-mode stylewidth: 100% :dropdown-style{ maxHeight: 400px, overflow: auto } :tree-datatreeData placeholderPlease select :load-dataonLoadData / /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; const value refstring(); const treeData refTreeSelectProps[treeData]([ { id: 1, pId: 0, value: 1, title: Expand to load }, { id: 2, pId: 0, value: 2, title: Expand to load }, { id: 3, pId: 0, value: 3, title: Tree Node, isLeaf: true }, ]); const genTreeNode (parentId: number, isLeaf false): TreeSelectProps[treeData][number] { const random Math.random().toString(36).substring(2, 6); return { id: random, pId: parentId, value: random, title: isLeaf ? Tree Node : Expand to load, isLeaf }; }; const onLoadData (treeNode: TreeSelectProps[treeData][number]) { return new Promise(resolve { const { id } treeNode.dataRef; setTimeout(() { treeData.value treeData.value.concat([ genTreeNode(id, false), genTreeNode(id, true), genTreeNode(id, true), ]); resolve(true); }, 300); }); }; /script要点tree-data-simple-mode把嵌套树拍平为[{ id, pId, value, title, isLeaf, ... }]列表pId指向父节点 id根节点pId: 0通过传对象{ id: ID, pId: parentId, rootPId: null }可自定义字段名loadData接收当前展开的节点必须返回 Promise在 Promise 中把新节点concat进treeData并resolve(true)叶子节点需标记isLeaf: true否则会被认为可继续展开而反复触发加载配合treeLoadedKeys3.3.0可受控管理已加载节点。字段映射fieldNames 与 replaceFields后端接口返回的字段名往往不是title/value/children。fieldNames3.0.0就是用来做字段映射的官方示例 components/tree-select/demo/replaceFields.vuea-tree-select v-model:valuevalue :tree-datatreeData :field-names{ children: children, label: name, value: value, } tree-node-filter-propname allow-clear show-search tree-default-expand-all /const treeData ref([ { name: parent 1, value: parent 1, children: [ { name: parent 1-0, value: parent 1-0, children: [{ name: my leaf, value: leaf1 }] }, ], }, ]);此时 treeData 中不再需要title字段而是用name作为显示标签因此搜索过滤字段也需同步改为tree-node-filter-propname。版本注意replaceFields是 1.6.1 引入、3.0.0 起废弃的旧 APIfieldNames为其替代。源码 components/tree-select/index.tsx 会在使用replaceFields时输出 deprecation 警告并在渲染时将fieldNames回退为props.replaceFields见 components/tree-select/index.tsx保证老代码平滑过渡。高级外观与交互配置弹出位置 placement3.3.0通过placement指定弹出方向官方示例 components/tree-select/demo/placement.vue 展示了topLeft / topRight / bottomLeft / bottomRight四种取值配合dropdown-match-select-widthfalse可自由控制下拉宽度。源码中未显式设置placement时会依据directionRTL 配置自动回退到bottomRight或bottomLeft见 components/tree-select/index.tsx。校验状态 status3.3.0status支持error/warning用于表单校验反馈官方示例见 components/tree-select/demo/status.vuea-tree-select statuserror stylewidth: 100% placeholderError / a-tree-select statuswarning stylewidth: 100% multiple placeholderWarning multiple /源码中status会与 FormItem 的上下文状态合并getMergedStatus并叠加反馈图标等样式类见 components/tree-select/index.tsx。连接线 treeLine 与节点图标tree-line为 boolean 或对象可传{ showLeafIcon }控制叶子节点图标官方示例 components/tree-select/demo/tree-line.vue 中用两个a-switch动态切换treeLine与showLeafIcon。此外treeIcon可开启节点前图标位需自行提供样式switcherIcon、leafIcon插槽可定制展开箭头与叶子图标。虚拟滚动virtual默认 true启用虚拟滚动listHeight默认 256控制面板高度listItemHeight默认 26控制行高。官方示例 components/tree-select/demo/virtual-scroll.vue 通过:height233配合tree-checkable展示了万级节点数据的流畅滚动。注意当dropdownMatchSelectWidth为false时会禁用虚拟滚动见官方属性表说明。FAQ如何在 onChange 中拿到父节点官方 FAQ 明确回答出于性能考虑TreeSelect 不提供在onChange中直接获取父节点的能力。如需父节点信息常见替代方案在业务侧维护一份Mapvalue, parentValue或在 treeData 中冗余父级字段change回调中用选中值自行查表使用onSelect事件参数含 node 节点对象在选中瞬间获取上下文使用treeCheckStrictly严格模式配合labelInValuehalfChecked字段会携带半选父节点信息再自行推导父子关系。小结TreeSelect 在 ant-design-vue 中由 components/tree-select/index.tsx 基于底层 components/vc-tree-select 封装而成通过treeData或treeDataSimpleMode驱动数据、fieldNames完成字段映射、showCheckedStrategy控制回显粒度并支持搜索、异步加载、虚拟滚动、状态反馈与插槽定制。掌握其 API 与勾选策略算法后绝大多数层级选择需求组织架构、目录树、分类级联等都能以最小的代码量高质量落地。更多可运行的完整示例可直接查看仓库 components/tree-select/demo 目录下的 13 个官方 demo以及对应的单元测试 components/tree-select/tests/index.test.js。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Ant Design TreeSelect 多选与树勾选treeCheckable实战指南Ant Design TreeSelect 多选与树勾选treeCheckable实战指南 TreeSelect树选择是 Ant Design 中用于在UI组件前端设计系统ant-design-vue TreeSelect 树选择组件完全指南API 详解、源码实现与实战示例ant design vue TreeSelect 树选择组件完全指南API 详解、源码实现与实战示例 TreeSelect 是 ant design vue前端UI组件设计系统Ant Design TreeSelect 树选择组件完全指南API、源码实现与实战示例Ant Design TreeSelect 树选择组件完全指南API、源码实现与实战示例 TreeSelect树型选择控件是 Ant Design 中面向UI组件前端设计系统上一篇PrimeVue-Tailwind组件设计原理深入理解Unstyled模式与Tailwind CSS结合之道下一篇Portkey Novita AI完整接入指南与配置教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ant-design-vue TreeSelect 树选择器完全指南：API、勾选策略与源码级实战解析
前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载TreeSelect是 ant-design-vue 中用于在树形结构数据中进行选择的控件它融合了Select的搜索、多选、下拉能力与Tree的层级展示能力适合组织架构、目录结构等具备天然层级关系的数据选择场景。本文以官方文档 components/tree-select/index.en-US.md 为骨架结合组件源码 components/tree-select/index.tsx 与官方示例源码系统讲解其全部 API、核心勾选策略的实现原理并给出可直接复用的实战代码。读完本文你将掌握 TreeSelect 的基本用法、勾选策略取舍、异步加载、字段映射等完整技能。When To Use什么时候选择 TreeSelectTreeSelect与Select非常相似但它的可选项value以树形结构提供。凡是数据本身具有层级归属关系的场景都适合使用它典型例子包括企业组织架构部门 → 子部门 → 员工目录/文件结构文件夹 → 子文件夹 → 文件商品分类一级分类 → 二级分类 → SKU权限树、地区级联等一切父子从属的数据。与级联选择器Cascader相比TreeSelect 更强调在树中任意位置选择含父节点且支持 checkbox 勾选、多选、搜索过滤、异步加载等能力。基本用法从一份 treeData 开始TreeSelect 最推荐的用法是直接传入treeData数组而非手动构造TreeNode节点。参考官方示例 components/tree-select/demo/basic.vue一个最简用法如下template a-tree-select v-model:valuevalue show-search stylewidth: 100% :dropdown-style{ maxHeight: 400px, overflow: auto } placeholderPlease select allow-clear tree-default-expand-all :tree-datatreeData tree-node-filter-proplabel template #title{ value: val, label } b v-ifval parent 1-1 stylecolor: #08csss/b template v-else{{ label }}/template /template /a-tree-select /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; const value refstring(); const treeData refTreeSelectProps[treeData]([ { label: root 1, value: root 1, children: [ { label: parent 1, value: parent 1, children: [ { label: parent 1-0, value: parent 1-0, children: [ { label: my leaf, value: leaf1 }, { label: your leaf, value: leaf2 }, ], }, { label: parent 1-1, value: parent 1-1 }, ], }, { label: parent 2, value: parent 2 }, ], }, ]); /script几个关键点v-model:value双向绑定当前选中值单选用字符串多选用字符串数组show-search开启下拉面板内的搜索输入框tree-default-expand-all默认展开全部节点也可用treeDefaultExpandedKeys精确指定tree-node-filter-prop指定搜索过滤时按哪个字段匹配默认为value这里改为label#title插槽可自定义节点标题渲染插槽参数包含value、label、title等字段。从源码 components/tree-select/index.tsx 可以看到组件在创建时通过initDefaultProps设置了listHeight: 256、treeIcon: false、listItemHeight: 26、bordered: true等默认值并在setup中对废弃用法children传节点、replaceFields、dropdownClassName给出开发期警告引导用户使用treeData与fieldNames。TreeSelect 完整 API 参考Tree props核心属性下表为官方文档的完整属性清单并补充了源码层面的说明列中源码说明为本文基于 components/tree-select/index.tsx 与 components/vc-tree-select 的补充属性说明类型默认值版本allowClear是否允许清空booleanfalsedefaultValue设置初始选中的 treeNodestring | string[]-disabled是否禁用booleanfalsepopupClassName下拉菜单的 classNamestring-4.0dropdownMatchSelectWidth下拉菜单是否与选择框同宽。默认设置与输入框相同min-width当值小于选择框宽度时被忽略false时会禁用虚拟滚动boolean | numbertruedropdownStyle下拉菜单的样式object-fieldNames用 treeData 中对应的字段替换 treeNode 中的 label、value、children 字段object{ children: children, label: title, value: value }3.0.0filterTreeNode是否按输入值过滤节点默认使用treeNodeFilterProp指定的字段也可传函数(inputValue: string, treeNode: TreeNode) booleanboolean | FunctionFunctiongetPopupContainer设置下拉菜单的挂载容器默认在body中创建div可重置为滚动区域并做相对定位Function(triggerNode)() document.bodylabelInValue是否将 label 嵌入 value使 value 从string变为{ value: string, label: VNode, halfChecked: string[] }booleanfalselistHeight下拉面板高度配合虚拟滚动number256loadData异步加载数据function(node)-maxTagCount多选时最多显示的标签数量number-maxTagPlaceholder超出 maxTagCount 的占位内容slot / function(omittedValues)-multiple是否多选启用treeCheckable时会被强制为truebooleanfalsenotFoundContent无匹配结果时显示的内容slotNot Foundplaceholder选择框占位文本string | slot-placement弹出位置bottomLeftbottomRighttopLefttopRightbottomLeft3.3.0replaceFields替换 treeNode 的 label、value、key、children 字段已废弃请改用 fieldNamesobject{ children: children, label: title, value: value }1.6.13.0.0 废弃searchPlaceholder搜索输入框占位文本string | slot-searchValue(v-model)配合search事件做受控搜索值string-showCheckedStrategy勾选后在输入框中展示已选项的方式。TreeSelect.SHOW_ALL展示全部勾选项含父节点TreeSelect.SHOW_PARENT只展示父节点TreeSelect.SHOW_CHILD只展示子节点enum { SHOW_ALL, SHOW_PARENT, SHOW_CHILD }TreeSelect.SHOW_CHILDshowSearch是否在下拉菜单中显示搜索框仅单选模式生效booleanfalsesize选择框尺寸large/small/defaultstringdefaultstatus校验状态error | warning-3.3.0suffixIcon自定义后缀图标VNode | slot-tagRender多选模式下自定义标签渲染(props) slot-3.0title自定义标题slot-3.0.0treeCheckable是否在节点前显示 checkboxbooleanfalsetreeCheckStrictly是否严格勾选父子不再关联该模式会强制labelInValue为 truebooleanfalsetreeData节点数据设置后无需手工构造节点需保证每个 value 唯一array{ value, title, children, [disabled, disableCheckbox, selectable] }[]treeDataSimpleMode扁平数据简单模式schema 变为[{ id, pId, value, title, ... }]pId 为父节点 id可传对象{ id, pId, rootPId }自定义字段名false | objectfalsetreeDefaultExpandAll是否默认展开全部节点booleanfalsetreeDefaultExpandedKeys默认展开的节点 key 数组string[] | number[]-treeExpandedKeys(v-model)受控展开 keystring[] | number[]-treeIcon是否在节点标题前显示图标无默认样式需自行设置booleanfalsetreeLoadedKeys受控的已加载节点 key仅配合loadData使用string[][]3.3.0treeLine是否显示连接线参考 Tree - showLineboolean | objectfalse3.0treeNodeFilterProp当filterTreeNode返回 true 时用于过滤的字段stringvaluetreeNodeLabelProp作为选择框内容的渲染字段stringtitlevalue(v-model)当前选中的 treeNode 值string | string[]-virtual设为 false 时禁用虚拟滚动booleantrue3.0源码补充说明在 components/tree-select/index.tsx 中treeSelectProps()从底层vc-tree-select的属性中过滤了showTreeIcon、treeMotion、inputIcon、getInputElement、treeLine、customSlots等内部能力再对外暴露suffixIcon、size、bordered、treeLine、replaceFields、placement、status、popupClassName等属性同时保留onUpdate:value、onUpdate:treeExpandedKeys、onUpdate:searchValue三个update:事件以支持v-model语法。Events事件事件名说明参数版本change选中节点或输入值变化时触发function(value, label, extra)dropdownVisibleChange下拉面板打开/关闭时触发function(open)3.0search搜索输入变化时触发function(value: string)select选中某个节点时触发function(value, node, extra)treeExpand节点展开时触发function(expandedKeys)源码补充说明在 components/tree-select/index.tsx 中可以看到事件与v-model的联动实现——handleChange会依次触发update:value、change并通知 Form 的onFieldChangehandleTreeExpand会触发update:treeExpandedKeys与treeExpandhandleSearch会触发update:searchValue与search。因此searchValue、treeExpandedKeys都可以通过v-model:search-value、v-model:tree-expanded-keys做受控绑定。Tree Methods实例方法名称说明blur()移除焦点focus()获取焦点方法通过组件 ref 调用。源码 components/tree-select/index.tsx 使用expose暴露focus与blur内部委托给底层VcTreeSelect的 ref 实现。TreeNode props节点属性官方建议优先使用treeData而非手工构造TreeNode以避免手动维护的麻烦。属性说明类型默认值版本checkable在 checkable 模式下该节点是否显示 checkboxboolean-disableCheckbox禁用该节点的 checkboxbooleanfalsedisabled是否禁用booleanfalseisLeaf是否为叶子节点booleanfalsekey必填属性树内唯一string | number-selectable是否可选中booleantruetitle节点显示内容string---value默认作为treeNodeFilterProp使用树内唯一string-勾选模式与 showCheckedStrategy源码级原理勾选模式treeCheckable是 TreeSelect 最常用的能力之一官方示例见 components/tree-select/demo/checkable.vuetemplate a-tree-select v-model:valuevalue stylewidth: 100% :tree-datatreeData tree-checkable allow-clear :show-checked-strategySHOW_PARENT placeholderPlease select tree-node-filter-proplabel / /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; import { TreeSelect } from ant-design-vue; const SHOW_PARENT TreeSelect.SHOW_PARENT; const treeData: TreeSelectProps[treeData] [ { label: Node1, value: 0-0, children: [{ label: Child Node1, value: 0-0-0 }], }, { label: Node2, value: 0-1, children: [ { label: Child Node3, value: 0-1-0, disabled: true }, { label: Child Node4, value: 0-1-1 }, { label: Child Node5, value: 0-1-2 }, ], }, ]; const value refstring[]([0-0-0]); /script几个要点tree-checkable开启勾选后multiple会被强制为true源码中isMultiple computed(() !!(props.treeCheckable || props.multiple))见 components/tree-select/index.tsx默认showCheckedStrategy为TreeSelect.SHOW_CHILD即输入框中只展示勾选的叶子/子节点如需回显父节点请改用SHOW_PARENT常量从TreeSelect.SHOW_ALL / SHOW_PARENT / SHOW_CHILD静态导出见 components/tree-select/index.tsx。三种策略的过滤算法三种策略的差异由底层formatStrategyValues实现源码位于 components/vc-tree-select/utils/strategyUtil.tsSHOW_CHILD遍历勾选值若某节点存在子节点、且其子节点全部被勾选或为禁用节点则说明该父节点已被子节点代表从结果中剔除该父节点最终只留下必要的子节点集合SHOW_PARENT遍历勾选值若某节点存在父节点、且父节点已被勾选则剔除该子节点最终只保留最上层的父节点SHOW_ALL不过滤原样返回全部勾选值父子同时展示。理解该算法有助于预判勾选了父节点 部分子节点时输入框的展示结果避免前后端参数对不上。多选、标签与自定义渲染多选模式参考 components/tree-select/demo/multiple.vue在节点上添加multiple即可a-tree-select v-model:valuevalue !-- value 为 string[] -- multiple allow-clear :tree-datatreeData tree-default-expand-all show-search tree-node-filter-proplabel template #title{ value: val, label } b v-ifval parent 1-1 stylecolor: #08c{{ val }}/b template v-else{{ label }}/template /template /a-tree-select多选场景常用的配套属性maxTagCount限制标签显示数量超出部分折叠maxTagPlaceholder折叠占位可传插槽(omittedValues)显示已选 n 项等tagRender3.0完全自定义标签渲染labelInValue将 value 变为{ value, label, halfChecked }对象结构halfChecked用于表达半选的父节点状态。异步加载loadData treeDataSimpleMode当树节点需要按需从后端拉取时使用loadData配合treeDataSimpleMode扁平数据模式最为方便。官方示例见 components/tree-select/demo/async.vuetemplate a-tree-select v-model:valuevalue tree-data-simple-mode stylewidth: 100% :dropdown-style{ maxHeight: 400px, overflow: auto } :tree-datatreeData placeholderPlease select :load-dataonLoadData / /template script langts setup import { ref } from vue; import type { TreeSelectProps } from ant-design-vue; const value refstring(); const treeData refTreeSelectProps[treeData]([ { id: 1, pId: 0, value: 1, title: Expand to load }, { id: 2, pId: 0, value: 2, title: Expand to load }, { id: 3, pId: 0, value: 3, title: Tree Node, isLeaf: true }, ]); const genTreeNode (parentId: number, isLeaf false): TreeSelectProps[treeData][number] { const random Math.random().toString(36).substring(2, 6); return { id: random, pId: parentId, value: random, title: isLeaf ? Tree Node : Expand to load, isLeaf }; }; const onLoadData (treeNode: TreeSelectProps[treeData][number]) { return new Promise(resolve { const { id } treeNode.dataRef; setTimeout(() { treeData.value treeData.value.concat([ genTreeNode(id, false), genTreeNode(id, true), genTreeNode(id, true), ]); resolve(true); }, 300); }); }; /script要点tree-data-simple-mode把嵌套树拍平为[{ id, pId, value, title, isLeaf, ... }]列表pId指向父节点 id根节点pId: 0通过传对象{ id: ID, pId: parentId, rootPId: null }可自定义字段名loadData接收当前展开的节点必须返回 Promise在 Promise 中把新节点concat进treeData并resolve(true)叶子节点需标记isLeaf: true否则会被认为可继续展开而反复触发加载配合treeLoadedKeys3.3.0可受控管理已加载节点。字段映射fieldNames 与 replaceFields后端接口返回的字段名往往不是title/value/children。fieldNames3.0.0就是用来做字段映射的官方示例 components/tree-select/demo/replaceFields.vuea-tree-select v-model:valuevalue :tree-datatreeData :field-names{ children: children, label: name, value: value, } tree-node-filter-propname allow-clear show-search tree-default-expand-all /const treeData ref([ { name: parent 1, value: parent 1, children: [ { name: parent 1-0, value: parent 1-0, children: [{ name: my leaf, value: leaf1 }] }, ], }, ]);此时 treeData 中不再需要title字段而是用name作为显示标签因此搜索过滤字段也需同步改为tree-node-filter-propname。版本注意replaceFields是 1.6.1 引入、3.0.0 起废弃的旧 APIfieldNames为其替代。源码 components/tree-select/index.tsx 会在使用replaceFields时输出 deprecation 警告并在渲染时将fieldNames回退为props.replaceFields见 components/tree-select/index.tsx保证老代码平滑过渡。高级外观与交互配置弹出位置 placement3.3.0通过placement指定弹出方向官方示例 components/tree-select/demo/placement.vue 展示了topLeft / topRight / bottomLeft / bottomRight四种取值配合dropdown-match-select-widthfalse可自由控制下拉宽度。源码中未显式设置placement时会依据directionRTL 配置自动回退到bottomRight或bottomLeft见 components/tree-select/index.tsx。校验状态 status3.3.0status支持error/warning用于表单校验反馈官方示例见 components/tree-select/demo/status.vuea-tree-select statuserror stylewidth: 100% placeholderError / a-tree-select statuswarning stylewidth: 100% multiple placeholderWarning multiple /源码中status会与 FormItem 的上下文状态合并getMergedStatus并叠加反馈图标等样式类见 components/tree-select/index.tsx。连接线 treeLine 与节点图标tree-line为 boolean 或对象可传{ showLeafIcon }控制叶子节点图标官方示例 components/tree-select/demo/tree-line.vue 中用两个a-switch动态切换treeLine与showLeafIcon。此外treeIcon可开启节点前图标位需自行提供样式switcherIcon、leafIcon插槽可定制展开箭头与叶子图标。虚拟滚动virtual默认 true启用虚拟滚动listHeight默认 256控制面板高度listItemHeight默认 26控制行高。官方示例 components/tree-select/demo/virtual-scroll.vue 通过:height233配合tree-checkable展示了万级节点数据的流畅滚动。注意当dropdownMatchSelectWidth为false时会禁用虚拟滚动见官方属性表说明。FAQ如何在 onChange 中拿到父节点官方 FAQ 明确回答出于性能考虑TreeSelect 不提供在onChange中直接获取父节点的能力。如需父节点信息常见替代方案在业务侧维护一份Mapvalue, parentValue或在 treeData 中冗余父级字段change回调中用选中值自行查表使用onSelect事件参数含 node 节点对象在选中瞬间获取上下文使用treeCheckStrictly严格模式配合labelInValuehalfChecked字段会携带半选父节点信息再自行推导父子关系。小结TreeSelect 在 ant-design-vue 中由 components/tree-select/index.tsx 基于底层 components/vc-tree-select 封装而成通过treeData或treeDataSimpleMode驱动数据、fieldNames完成字段映射、showCheckedStrategy控制回显粒度并支持搜索、异步加载、虚拟滚动、状态反馈与插槽定制。掌握其 API 与勾选策略算法后绝大多数层级选择需求组织架构、目录树、分类级联等都能以最小的代码量高质量落地。更多可运行的完整示例可直接查看仓库 components/tree-select/demo 目录下的 13 个官方 demo以及对应的单元测试 components/tree-select/tests/index.test.js。赞分享前端UI组件设计系统【免费下载链接】ant-design-vue An enterprise-class UI components based on Ant Design and Vue. 项目地址https://gitcode.com/gh_mirrors/an/ant-design-vue点击查看免费下载相关推荐Ant Design TreeSelect 多选与树勾选treeCheckable实战指南Ant Design TreeSelect 多选与树勾选treeCheckable实战指南 TreeSelect树选择是 Ant Design 中用于在UI组件前端设计系统ant-design-vue TreeSelect 树选择组件完全指南API 详解、源码实现与实战示例ant design vue TreeSelect 树选择组件完全指南API 详解、源码实现与实战示例 TreeSelect 是 ant design vue前端UI组件设计系统Ant Design TreeSelect 树选择组件完全指南API、源码实现与实战示例Ant Design TreeSelect 树选择组件完全指南API、源码实现与实战示例 TreeSelect树型选择控件是 Ant Design 中面向UI组件前端设计系统上一篇PrimeVue-Tailwind组件设计原理深入理解Unstyled模式与Tailwind CSS结合之道下一篇Portkey Novita AI完整接入指南与配置教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考