树选择 TreeSelect
最简单的用法。
可以通过设置 treeCheckable 属性开启复选框勾选。
定制回填方式
Section titled “定制回填方式”可以通过treeCheckStrategy属性定制回填方式。
选中值支持双向绑定。
下拉框的页头和页脚
Section titled “下拉框的页头和页脚”自定义树选择下拉框的页头和页脚
使用 fallback-option 自定义找不到选项的值的显示效果，默认找不到选项就展示值本身。用户可以将其设定为 false 来隐藏那些没有匹配到节点数据的值。
自定义 TreeData 的字段名称
Section titled “自定义 TreeData 的字段名称”通过 fieldNames 字段可以自定义 TreeData 的字段名。
设置 value 格式
Section titled “设置 value 格式”labelInValue 为 true 时，value 格式为： { label: string, value: string }。
可以通过 loadMore 进行动态加载。此时可设置 isLeaf 来标示叶子节点。
多选
控制下拉框的展开收起
Section titled “控制下拉框的展开收起”通过 popupVisible (支持 v-model) 控制下拉框的展开和收起。
监听 search 事件，在事件处理函数中获取数据并更新 treeData。 自定义搜索逻辑时，建议关闭内部过滤逻辑（:disable-filter="true"），以免影响自定义结果。
设置 :allow-search="true" 启用搜索功能。动态加载时候只能在已加载数据中进行搜索。默认的关键字搜索是从value字段匹配。也可以传入 filterTreeNode自定义过滤方式。
设置 size 可以使用四种尺寸（small, default, large, huge）的选择器。高度分别对应 24px、28px、32px、36px。
自定义触发元素
Section titled “自定义触发元素”自定义触发元素。插槽直接提供 value、displayValue、inputValue、selectedOptions、 popupVisible、disabled、loading 和 multiple。
选项文本省略
Section titled “选项文本省略”默认情况下，每个树节点都会使用 Ellipsis 处理溢出文本。大数据量或虚拟滚动场景可以设置 ellipsis="performant-ellipsis"；设置 :ellipsis="false" 可关闭内置省略。使用 #tree-slot-title 插槽后，节点标题完全由插槽控制。
TreeSelect 默认不启用虚拟滚动。当前示例对比未配置虚拟滚动、设置 virtual-scroll="true" 和传入 virtual-list-props 三种写法，所有虚拟滚动行为都需要用户显式开启。
设置 virtual-scroll="true" 会使用组件内置的虚拟列表默认配置；传入 virtual-list-props 可以继续设置 height、itemSize 和 buffer。树节点固定行高会随 mini / small / medium / large 尺寸分别使用 24 / 28 / 32 / 36。设置 virtual-scroll="false" 会强制关闭包括 virtual-list-props 和 tree-props.virtualListProps 在内的虚拟列表配置。完整参数可参考 LLMs.txt。
<tree-select> Props
Section titled “<tree-select> Props”| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| disabled | 是否禁用 | boolean |
false |
|
| loading | 是否为加载中状态 | boolean |
false |
|
| spin-props | 传递给加载中 Spin 的属性 | SpinProps |
- |
|
| error | 是否为错误状态 | boolean |
false |
|
| size | 选择框的大小 | 'mini' | 'small' | 'medium' | 'large' |
'medium' |
|
| border | 是否显示边框 | boolean |
true |
|
| ellipsis | 是否使用 Ellipsis 渲染默认节点；performant-ellipsis 使用高性能实现，false 关闭 |
boolean | 'performant-ellipsis' |
true |
|
| allow-search | 是否允许搜索，兼容 filterable 别名 |
boolean | { retainInputValue?: boolean } |
false (single) | true (multiple) |
|
| filterable | allow-search 的兼容别名 |
boolean |
- |
|
| allow-clear | 是否允许清除，兼容 clearable 别名 |
boolean |
false |
|
| clearable | allow-clear 的兼容别名 |
boolean |
- |
|
| placeholder | 提示文案 | string |
- |
|
| fit-width | 宽度是否适应文字内容 | boolean |
false |
|
| max-w-full | 最大宽度是否限制为父容器宽度 | boolean |
true |
|
| max-tag-count | 最多显示的标签数量，仅在多选模式有效，支持响应式折叠 | number | 'responsive' |
- |
|
| multiple | 是否支持多选 | boolean |
false |
|
| default-value | 默认值 | string | number | Array<string | number> | LabelValue | LabelValue[] |
- |
|
| model-value (v-model) | 绑定值 | string | number | Array<string | number> | LabelValue | LabelValue[] |
- |
|
| field-names | 指定节点数据中的字段名 | TreeFieldNames |
- |
|
| data | 数据，兼容 options 别名 |
TreeNodeData[] |
[] |
|
| options | data 的兼容别名 |
TreeNodeData[] |
- |
|
| label-in-value | 设置value格式。默认是string，设置为true时候，value格式为： { label: string, value: string } | boolean |
false |
|
| tree-checkable | 是否展示复选框，兼容 checkable 别名 |
boolean |
false |
|
| checkable | tree-checkable 的兼容别名 |
boolean |
- |
|
| tree-check-strictly | 父子节点是否关联 | boolean |
false |
|
| tree-checked-strategy | 定制回显方式，兼容 checkStrategy 别名 |
'all' | 'parent' | 'child' |
'all' |
|
| checkStrategy | tree-checked-strategy 的兼容别名 |
'all' | 'parent' | 'child' |
- |
|
| show-path | 单选时展示从根节点到当前节点的完整路径 | boolean |
false |
|
| separator | show-path 开启时的路径分隔符 |
string |
' / ' |
|
| tree-props | 可以接受所有 Tree 组件的Props | Partial<TreeProps> |
- |
|
| trigger-props | 可以接受所有 Trigger 组件的Props | Partial<TriggerProps> |
- |
|
| virtual-list-props | 虚拟列表配置，传入此参数会显式启用虚拟滚动 | VirtualListProps |
- |
|
| virtual-scroll | 虚拟滚动开关；true 使用默认配置显式启用，false 强制关闭所有虚拟列表配置，未设置时不启用 |
boolean |
- |
|
| popup-visible (v-model) | 弹出框是否可见 | boolean |
- |
|
| default-popup-visible | 默认弹出框是否可见 | boolean |
false |
|
| dropdown-style | 下拉框样式 | CSSProperties |
- |
|
| dropdown-class-name | 下拉框样式 class | string | string[] |
- |
|
| filter-tree-node | 自定义节点过滤函数 | (searchKey: string, nodeData: TreeNodeData) => boolean |
- |
|
| load-more | 动态加载数据 | (nodeData: TreeNodeData) => Promise<void> |
- |
|
| disable-filter | 禁用内部过滤逻辑 | boolean |
false |
|
| popup-container | 弹出框的挂载容器 | string | HTMLElement |
- |
|
| fallback-option | 为 value 中找不到匹配项的 key 定义节点数据 | boolean | ((key: number | string) => TreeNodeData | boolean) |
true |
2.22.0 |
| selectable | 设置可选择的节点，默认全部可选 | boolean| 'leaf'| (( node: TreeNodeData, info: { isLeaf: boolean; level: number } ) => boolean) |
true |
2.27.0 |
| scrollbar | 是否开启虚拟滚动条 | boolean | ScrollbarProps |
true |
2.39.0 |
| show-header-on-empty | 空状态时是否显示header | boolean |
false |
|
| show-footer-on-empty | 空状态时是否显示footer | boolean |
false |
|
| input-value (v-model) | 输入框的值 | string |
- |
2.55.0 |
| default-input-value | 输入框的默认值（非受控模式） | string |
'' |
2.55.0 |
<tree-select> Events
Section titled “<tree-select> Events”| 事件名 | 描述 | 参数 | 版本 |
|---|---|---|---|
| change | 值改变时触发 | value: string | number | LabelValue | Array<string | number> | LabelValue[] | undefined |
|
| popup-visible-change | 下拉框显示状态改变时触发 | visible: boolean |
|
| search | 搜索值变化时触发 | searchKey: string |
|
| clear | 点击清除时触发 | - | |
| input-value-change | 输入框的值发生改变时触发 | inputValue: string |
2.55.0 |
<tree-select> Slots
Section titled “<tree-select> Slots”| 插槽名 | 描述 | 参数 | 版本 |
|---|---|---|---|
| trigger | 自定义触发元素 | TreeSelectTriggerSlotProps |
|
| prefix | 前缀 | - | |
| label | 自定义选择框显示 | data: mixed |
|
| tag | 自定义多选标签显示 | data: TreeNodeData |
|
| header | 自定义下拉框页头 | - | |
| loader | 定制加载中显示的内容 | - | |
| empty | 定制空数据展示 | - | |
| footer | 自定义下拉框页脚 | - | |
| tree-slot-extra | 定制 tree 组件的渲染额外节点内容 | - | |
| tree-slot-title | 定制 tree 组件的节点标题 | title: string |
|
| tree-slot-icon | 定制 tree 组件的节点图标 | node: TreeNodeData |
2.18.0 |
| tree-slot-switcher-icon | 定制 tree 组件的 switcher 图标 | - |