仅桌面端保证样式
TreeSelect 树形选择
下拉树选择器:Tree 与选择器的组合,支持单选 / 多选(复选框)、过滤、懒加载;层级数据用 props 字段映射。关闭态触发器支持键盘展开(Enter / Space / ↓)。
基础用法
选择部门
多选(复选框)
multiple + show-checkbox 多选回显为标签;check-strictly 让父子选中互不联动:
选择多个区域
回传值策略
多选复选默认按 checked-strategy: child 只回传叶子 key;改为 parent 时只回传「子级全选中」的最上层父节点(勾满一个大区只记大区,取消任一子级回退到仍全选中的最上层节点),all 则连同父级一起回传:
勾满大区只记大区
对象值形态
label-in-value 让绑定值形如 { value, label }(multiple 时为对象数组),业务侧免于二次反查文案;与 checked-strategy 组合时 label 取归约后 key 的文案:
值形如 { value, label }
过滤
filterable 按节点文案过滤;自定义过滤逻辑用 filter-method:
输入关键词过滤
任意层级选择
单选默认只能选中叶子;加 check-strictly 后点击任意层级节点即可选中,展开/收起改由节点前箭头控制,常用于「选择部门或其上级」场景:
大区或团队均可选择
懒加载
lazy + load 按需拉取子级,展开时才请求;宿主侧把已加载子级合并进 data,保证选中回显始终有 label 可查:
懒加载选择团队
禁用与事件
disabled 整体禁用(也可由 Form 注入);change / remove-tag / clear / visible-change 覆盖值变更、删标签、清空与下拉开合:
禁用选择器
多选团队并观察事件
试试勾选团队、删除标签或清空
TreeSelect Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 绑定值;multiple 时为数组,label-in-value 下形如 { value, label } | string | number | boolean | array | object | — |
| data | 树形数据(字段可用 props 映射) | array | [] |
| props | 字段映射 { value, label, children, disabled, isLeaf } | object | {} |
| node-key | 唯一键字段,缺省取 props.value | string | — |
| multiple | 多选(回显为标签) | boolean | false |
| label-in-value | 绑定值形如 { value, label }(multiple 为对象数组);与 checked-strategy 组合时 label 取归约后 key 的文案,清空仍为 undefined / 空数组 | boolean | false |
| size | 尺寸:large / small | string | — |
| placeholder | 占位文案 | string | 请选择 |
| show-checkbox | 节点前显示复选框 | boolean | false |
| check-strictly | 父子选中互不联动;单选时可选中任意层级节点 | boolean | false |
| checked-strategy | 多选复选回传值归约策略:child 只存叶子 key(默认),parent 只存子级全选中的最上层父 key,all 全存勾选 key;三种形态回显均支持 | string | child |
| filterable | 可搜索 | boolean | false |
| filter-method | 自定义过滤 (query, data) => boolean | function | null |
| collapse-tags / max-collapse-tags | 多选标签折叠 | boolean / number | false / 1 |
| default-expand-all | 默认展开全部 | boolean | false |
| default-expanded-keys | 默认展开节点;选中值回显时自动追加其祖先链 | array | [] |
| expand-on-click-node | 点击节点展开(check-strictly 下自动关闭,改由箭头展开) | boolean | true |
| check-on-click-node | 点击节点切换勾选(需开启复选框) | boolean | false |
| accordion | 手风琴模式(同层互斥展开) | boolean | false |
| indent / empty-text | 层级缩进像素与空数据文案 | number / string | 16 / 暂无数据 |
| clearable | 可清空 | boolean | false |
| disabled | 禁用 | boolean | false |
| lazy / load | 懒加载开关与加载函数 load(node, resolve) | boolean / function | false / null |
| ripple | 激活涟漪动效开关:聚焦时实体色影向内收拢消散;也可在 Form 上批量关闭或全局 setRipple(false) | boolean | true |
TreeSelect Events
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| change | 值变更 | (value) => void | — |
| clear | 清空 | () => void | — |
| remove-tag | 移除多选标签 | (value) => void | — |
| visible-change | 下拉展开 / 收起 | (visible: boolean) => void | — |
| node-click | 节点被点击 | (data, node) => void | — |
| check | 复选勾选变化,携带勾选与半选明细 | (data, { checkedKeys, checkedNodes, halfCheckedKeys, halfCheckedNodes }) => void | — |
| node-expand | 节点展开 | (data, node) => void | — |
| focus / blur | 下拉展开 / 收起时触发 | () => void | — |
TreeSelect Methods(defineExpose)
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| focus / blur | 聚焦(展开下拉)/ 收起下拉 | () => void | — |
| filter | 按关键词过滤下拉树,配合 filterable 使用 | (value) => void | — |
| getCheckedKeys / getCheckedNodes | 获取选中 key / 原始数据,getCheckedKeys(leafOnly) 可只取叶子 | (leafOnly?) => array | — |
| setCheckedKeys / setChecked | 批量 / 单个设置勾选 | (keys) / (key, checked) => void | — |
| getHalfCheckedKeys / getHalfCheckedNodes | 获取半选节点 key / 原始数据 | () => array | — |
| getNode / setCurrentKey | 按 key 取内部节点 / 程序化选中 | (key) => node | — |
| getCurrentKey / getCurrentNode | 读取当前选中 key / 原始数据 | () => key | data | — |