TreeSelect 树形选择
支持极致的虚拟滚动检索。
当数据量巨大或呈现清晰的树形层级结构时，使用 TreeSelect 可以在紧凑的空间内提供高效的选择方案。
基础用法
基础单选模式。默认仅允许选中叶子节点，点击父节点会自动展开或收起。
Value:
禁用状态
可以禁用整个组件，或在数据中通过 disabled 字段禁用特定节点（如测试组）。
可清空
设置 clearable 属性后，鼠标悬停时会显示清空按钮。
Value: 1-1-1
多选与折叠
设置 multiple 开启多选模式。多选模式下建议配合 collapse-tags 使用以节省空间。
Value: []
选择任意级别
启用 check-strictly 属性后，用户可以选中分级中的任何一级节点。
Value: 1-1
复选框
使用 show-checkbox 属性来启用复选框，这在多选场景下能提供更清晰的视觉勾选状态。
Value: []
可筛选
设置 filterable 后，用户可以直接在输入框中输入关键字进行节点过滤。
懒加载
设置 lazy 和 load 函数来实现异步加载子节点数据。这对于大型组织架构非常实用。
自定义内容
使用 #default 插槽可以完全自定义树节点在菜单中的渲染方式。
虚拟滚动 (10,000+ 节点)
本组件内置自研虚拟滚动方案。为了性能最优化，虚拟滚动默认不开启。当数据量较大（建议 500 条以上）时，请设置 virtual 属性为 true。
基础搜索演示
Value Count: 0
复选框模式
即便在海量数据下，复选框的级联勾选同样流畅。
Checked Count: 0
在 Nuxt 中使用
TreeSelect 组件完全兼容 Nuxt 3/4。在 Nuxt 环境下，得益于组件自动导入（Auto Import）功能，你可以直接在模板中使用而无需手动注册。
SSR 注意事项：
- ✅ 树形结构的首屏渲染（包含展开/收起状态）完全支持
- ✅ 选中的 Token 标签在服务端正确展示
- ✅ 虚拟滚动（virtual）支持 SSR 首屏基础节点渲染
- ✅ 懒加载（lazy）初始数据支持 SSR
- 💡 搜索过滤和异步加载通过客户端激活（Hydration）后生效
SSR 安全性
TreeSelect 使用了 Vue 3.5 的原生 useId 机制，确保了在复杂的递归树结构中，服务端和客户端生成的节点 ID、ARIA 属性保持绝对一致，消除了深层嵌套结构中常见的水合一致性报错。
API
TreeSelect Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string | number | (string | number)[] | — |
| data | 展示数据 | TreeOption[] | [] |
| props | 配置选项，详见下表 | object | — |
| node-key | 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的 | string | 'value' |
| multiple | 是否多选 | boolean | false |
| clearable | 是否可以清空选项 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| size | 输入框尺寸 | 'large' | 'default' | 'small' | 'default' |
| placeholder | 输入框占位文本 | string | '请选择' |
| empty-text | 无数据时显示的文本 | string | '暂无数据' |
| filterable | 是否可搜索 | boolean | false |
| filter-node-method | 自定义过滤方法 | (value: string, data: TreeOption, node: any) => boolean | — |
| collapse-tags | 多选时是否折叠标签 | boolean | false |
| collapse-tags-tooltip | 是否在折叠标签时显示 tooltip (仅展示数量) | boolean | false |
| max-collapse-tags | 标签折叠前的最大展示数量 | number | 1 |
| check-strictly | 是否遵循父子不互相关的原则 | boolean | false |
| show-checkbox | 节点前是否显示复选框 | boolean | false |
| default-expand-all | 是否默认展开所有节点 | boolean | false |
| default-expanded-keys | 默认展开的节点的 key 的数组 | TreeKey[] | [] |
| accordion | 是否每次只打开一个同级树节点展开 | boolean | false |
| indent | 相邻级节点间的水平缩进 | number | 16 |
| check-on-click-node | 是否在点击节点时选中复选框 | boolean | false |
| expand-on-click-node | 是否在点击节点时展开/收起 | boolean | true |
| lazy | 是否懒加载子节点 | boolean | false |
| load | 加载子树数据的方法 | Function | — |
| virtual | 是否开启虚拟滚动渲染 | boolean | false |
| height | 下拉菜单的最大高度 | string | number | 274 |
| item-size | 虚拟滚动时每一项的高度 | number | 34 |
| teleported | 是否直接将下拉层挂载至 body | boolean | true |
| popper-class | 下拉菜单的自定义类名 | string | — |
| status | 设置输入框的校验状态 | 'success' | 'warning' | 'error' | '' | — |
TreeSelect Props (配置选项)
| 属性名 | 说明 | 类型 |
|---|---|---|
| label | 指定节点标签为节点对象的某个属性值 | string |
| value | 指定节点选择值为节点对象的某个属性值 | string |
| children | 指定子树为节点对象的某个属性值 | string |
| disabled | 指定节点选择框是否禁用的属性值 | string |
| isLeaf | 指定节点是否为叶子节点 (仅懒加载有效) | string |
TreeSelect Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 选中值发生变化时触发 | (value: any) => void |
| visible-change | 下拉框出现/隐藏时触发 | (visible: boolean) => void |
| clear | 点击清空按钮时触发 | — |
| node-click | 节点被点击时的回调 | (data: TreeOption, node: TreeNode, e: MouseEvent) => void |
| check-change | 节点复选框状态改变时的回调 | (data: TreeOption, checked: boolean, indeterminate: boolean) => void |
| check | 点击复选框时的回调 | (data: TreeOption, info: any) => void |
TreeSelect Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
| default | 自定义树节点的内容 | { node: TreeNode, data: TreeOption } |
| prefix | 自定义输入框前缀内容 | — |
| empty | 无匹配数据时的显示内容 | — |
主题变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-tree-select-node-hover-bg | 节点悬停时的背景颜色 | var(--yh-fill-color-light) |
--yh-tree-select-node-selected-color | 选中节点时的文字颜色 | var(--yh-color-primary) |