TreeSelect 树选择器

何时使用

• 类似 Select 的选择控件，当可选择的数据结构为树形结构时使用 TreeSelect，例如公司层级、学科系统、分类目录等层级数据。

基础用法

多选

可搜索

禁用与清空

尺寸

自定义字段映射

当你的数据字段不是 label/key/children 时，可通过 label-field/key-field/children-field 指定：

严格选择与路径显示

• check-strictly：开启后允许选择任意节点；关闭时仅允许选择叶子节点。
• show-path：单选时在输入框显示完整层级路径（如 “研发 / 前端”）。

默认展开/折叠

可通过 default-expand-all 或 default-expanded-keys 控制初始展开。

## API

属性名	说明	类型	可选值	默认值
modelValue	绑定值，支持单选与多选	string | number | (string | number)[]	—	''
data	树形数据	TreeOption[]	—	[]
labelField	自定义标签字段名	string	—	'label'
keyField	自定义唯一键字段名	string	—	'key'
childrenField	自定义子节点字段名	string	—	'children'
multiple	是否多选	boolean	—	false
filterable	是否可搜索	boolean	—	false
clearable	是否可清空	boolean	—	false
placeholder	占位符	string	—	'请选择'
size	输入框尺寸	'large' | 'default' | 'small'	large / default / small	default
noMatchText	搜索无匹配项时的提示文案	string	—	'无匹配数据'
noDataText	无数据时的提示文案	string	—	'无数据'
popperClass	下拉弹层额外类名	string	—	''
checkStrictly	是否允许选择任意节点（默认仅叶子可选）	boolean	—	false
showPath	单选时是否显示完整路径	boolean	—	false
defaultExpandAll	是否默认展开所有有子节点的节点	boolean	—	false
defaultExpandedKeys	默认展开的节点 key 集合	(string | number)[]	—	[]

事件

事件名	说明	参数类型
update:modelValue	v-model 更新	string | number | (string | number)[]
change	选中值变化	string | number | (string | number)[]
clear	点击清空时触发	—
focus	输入框获得焦点	(evt: FocusEvent)
blur	输入框失去焦点	(evt: FocusEvent)
visibleChange	下拉显示状态变化	(visible: boolean)

TreeOption

组件使用的树节点数据结构（默认字段）：

export interface TreeOption {
  label?: string | number;
  key?: string | number;
  children?: TreeOption[];
  isLeaf: boolean;
  [key: string]: unknown;
}

使用建议

• 数据量适中（< 2000 节点）场景下可直接使用当前实现；如需大数据虚拟滚动或半选联动，可在后续版本中扩展。
• 建议在多选模式下开启 filterable，便于快速定位节点。
• 选择项以 key 作为绑定值（modelValue），确保唯一性。