Tree 树形控件

常用的树形展示组件，支持海量数据虚拟滚动、搜索过滤、拖拽排序等高级特性。

基础用法

Node 1

Node 2

基础用法

可选择与禁用

通过 show-checkbox 开启复选框。在数据项中设置 disabled: true 可禁用该节点（不可点击、不可选中）。

父子不相关联

设置 check-strictly=true，父子节点的选中状态将互不影响。

手风琴模式

设置 accordion=true，每次展开一个节点时将自动收起其它同级节点。

Level one 1

Level one 2

手风琴模式

展示连接线

使用 show-line 属性清晰展示树层级关系。

Level one 1

Level two 1-1

Level two 1-2

Level three 1-2-1

Level one 2

Level two 2-1

Level two 2-2

连接线模式

复选框位置

通过 checkbox-position 将复选框置于右侧。

异步懒加载

Lazy Root

懒加载演示

自定义节点类名

重点关注节点

警告提示节点

自定义类名

自定义展开图标

Level one 1

Level one 2

自定义图标

自定义节点内容

Level one 1Root

Level one 2Root

自定义内容

自定义前缀与后缀

1Level one 1

2Level one 2

前缀与后缀

万级数据虚拟滚动

Virtual Node 0

Virtual Node 1

Virtual Node 2

Virtual Node 3

Virtual Node 4

Virtual Node 5

Virtual Node 6

Virtual Node 7

Virtual Node 8

Virtual Node 9

Virtual Node 10

虚拟滚动

节点过滤

Level one 1

Level one 2

树节点过滤

可拖拽节点

Level one 1

Level one 2

拖拽演示

多选与节点获取

自定义字段映射

Root A

Root B

字段映射

综合进阶：大数据量下的过滤与选择

综合示例

在 Nuxt 中使用

Tree 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。

Nuxt SSR Node 1

Nuxt SSR Node 2

Nuxt 中使用

SSR 注意事项：

✅ 数据结构完美序列化
✅ 节点展开状态在 SSR 环境下正确生成
✅ 虚拟滚动功能在客户端自动激活
✅ 事件绑定与响应式状态无缝对接

SSR 安全性

Tree 组件内部处理了虚拟滚动和 DOM 操作，确保在服务端不触发浏览器 API，在客户端注入后平滑过渡。

API

Props

属性名	说明	类型	默认值
data	数据源	`TreeNodeData[]`	`[]`
props	配置选项，具体见下表	`object`	`{ label: 'label', children: 'children', disabled: 'disabled' }`
node-key	每个树节点用来作为唯一标识的属性字段名	`string`	`'id'`
show-checkbox	节点是否可被选择	`boolean`	`false`
checkbox-position	复选框相对于文字的位置	`'left' \| 'right'`	`'left'`
default-expand-all	是否默认展开所有节点	`boolean`	`false`
default-expanded-keys	默认展开的节点 key 数组	`(string \| number)[]`	`[]`
default-checked-keys	默认选中的节点 key 数组	`(string \| number)[]`	`[]`
current-node-key	当前选中节点的 key，支持 v-model	`string \| number`	`-`
highlight-current	是否高亮当前选中节点	`boolean`	`true`
accordion	是否每次只打开一个同级树节点展开	`boolean`	`false`
indent	相邻级节点间的水平缩进，单位为像素	`number`	`18`
check-strictly	在显示复选框的情况下，是否严格的遵循父子不互相关联	`boolean`	`false`
expand-on-click-node	是否在点击节点时展开或者收起节点	`boolean`	`true`
check-on-click-node	是否在点击节点的时候选中复选框	`boolean`	`false`
empty-text	内容为空的时候展示的文本	`string`	`'暂无数据'`
filter-method	对树节点进行筛选时执行的方法	`(query, node) => boolean`	`-`
lazy	是否懒加载子节点，需与 `load` 方法结合使用	`boolean`	`false`
load	加载子树数据的方法，仅在 `lazy` 属性为 `true` 时有效	`(node) => Promise`	`-`
virtual	是否开启虚拟滚动	`boolean`	`false`
height	虚拟滚动窗口高度 (px)	`number`	`400`
item-height	每个节点的高度 (px)	`number`	`30`
show-line	是否显示连接线	`boolean`	`false`
draggable	是否开启拖拽功能	`boolean`	`false`

Props Data Mapping

属性名	说明	类型	默认值
label	指定节点标签为节点对象的某个属性值	`string`	`'label'`
children	指定子树为节点对象的某个属性值	`string`	`'children'`
disabled	指定节点选择框是否禁用的属性名	`string`	`'disabled'`

TreeNodeData 字段定义

属性名	说明	类型
key	唯一标识 (必须)	`string \| number`
label	显示文本 (必须)	`string`
children	子节点数组	`TreeNodeData[]`
disabled	是否禁用该节点的选择/点击	`boolean`
isLeaf	是否为叶子节点 (懒加载场景下使用)	`boolean`
icon	自定义节点图标类名	`string`
class	自定义节点样式类名	`string`

Events

事件名	说明	回调参数
node-click	节点被点击时的回调	`(node: TreeNode, e: MouseEvent)`
node-expand	节点被展开或收起时的回调	`(node: TreeNode, expanded: boolean)`
check	复选框状态改变时的回调	`(node: TreeNode, checked: boolean, checkedKeys: (string \| number)[])`
current-change	当前选中节点发生变化时的回调	`(node: TreeNode \| null)`
node-drag-start	节点开始拖拽时的回调	`(node: TreeNode, e: DragEvent)`
node-drag-end	节点拖拽结束时的回调	`(node: TreeNode, dropNode: TreeNode \| null, pos: 'before' \| 'after' \| 'inner', e: DragEvent)`
node-drag-over	节点拖拽过程中的回调	`(node: TreeNode, e: DragEvent)`
node-drag-enter	拖拽进入节点时的回调	`(node: TreeNode, e: DragEvent)`
node-drag-leave	拖拽离开节点时的回调	`(node: TreeNode, e: DragEvent)`
node-drop	节点完成拖拽投放时的回调	`(node: TreeNode, dropNode: TreeNode, type: 'before' \| 'after' \| 'inner', e: DragEvent)`

Slots

插槽名	说明	参数
default	自定义节点内容	`{ node, data }`
icon	自定义展开图标	`{ node, data }`
prefix	自定义内容前缀	`{ node, data }`
suffix	自定义内容后缀	`{ node, data }`
empty	无数据时的内容	`-`

注：node 对象包含：key, label, level, expanded, checked, indeterminate, loading, isLeaf 等属性。data 为原始数据项。

Expose

方法名/属性	说明	参数/类型
filter	对树节点进行筛选操作	`(query: string)`
getNode	根据 key 获取节点数据	`(key: string \| number)`
getCheckedNodes	返回目前被选中的节点所组成的数组	`-`
getCheckedKeys	返回目前被选中的节点的 key 所组成的数组	`-`
getHalfCheckedNodes	返回目前半选中的节点所组成的数组	`-`
getHalfCheckedKeys	返回目前半选中的节点的 key 所组成的数组	`-`
getCurrentKey	获取当前选中节点的 key	`-`
getCurrentNode	获取当前选中节点的数据	`-`
setChecked	通过 key 设置某个节点的勾选状态	`(key: string \| number, checked: boolean, deep?: boolean)`
setCheckedKeys	通过 keys 设置节点选中状态	`(keys: (string \| number)[])`
setCheckedNodes	通过节点数据设置选中状态	`(nodes: TreeNodeData[])`
setCurrentKey	通过 key 设置当前选中节点	`(key: string \| number \| undefined)`
setExpandedKeys	设置当前展开的节点	`(keys: (string \| number)[])`
setData	显式设置树插件数据	`(data: TreeNodeData[])`
expandNode	展开指定节点	`(key: string \| number)`
collapseNode	折叠指定节点	`(key: string \| number)`
scrollTo	滚动到给定位置 (仅虚拟滚动开启时有效)	`(options: number \| ScrollToOptions)`
scrollToNode	使用给定的滚动策略滚动至指定位置	`(key: string \| number)`
expandedKeys	当前展开的节点 key 集合	`Ref<Set<string \| number>>`
checkedKeys	当前选中的节点 key 集合	`Ref<Set<string \| number>>`

主题变量

变量名	说明	默认值
`--yh-tree-node-height`	节点高度	`28px`
`--yh-tree-text-color`	节点文字颜色	`var(--yh-text-color-primary)`
`--yh-tree-hover-bg`	节点悬停背景色	`var(--yh-color-primary-light-9)`
`--yh-tree-current-bg`	当前选中节点背景色	`var(--yh-color-primary-light-8)`

Tree 树形控件 ​

基础用法 ​

可选择与禁用 ​

父子不相关联 ​

手风琴模式 ​

展示连接线 ​

复选框位置 ​

异步懒加载 ​

自定义节点类名 ​

自定义展开图标 ​

自定义节点内容 ​

自定义前缀与后缀 ​

万级数据虚拟滚动 ​

节点过滤 ​

可拖拽节点 ​

多选与节点获取 ​

自定义字段映射 ​

综合进阶：大数据量下的过滤与选择 ​

在 Nuxt 中使用 ​

API ​

Props ​

Props Data Mapping ​

TreeNodeData 字段定义 ​

Events ​

Slots ​

Expose ​

主题变量 ​

Tree 树形控件

基础用法

可选择与禁用

父子不相关联

手风琴模式

展示连接线

复选框位置

异步懒加载

自定义节点类名

自定义展开图标

自定义节点内容

自定义前缀与后缀

万级数据虚拟滚动

节点过滤

可拖拽节点

多选与节点获取

自定义字段映射

综合进阶：大数据量下的过滤与选择

在 Nuxt 中使用

API

Props

Props Data Mapping

TreeNodeData 字段定义

Events

Slots

Expose

主题变量