VbenTree 用法说明

VbenTree 是 Vben5 中基于 radix-vue 实现的树形组件，支持单选、多选、展开/折叠、权限控制等功能。以下是其核心用法说明：

1. 基础引入

import { VbenTree } from '@vben-core/shadcn-ui';

2. 核心属性（Props）

属性名	类型	说明	默认值
treeData	Recordable<any>[]	树形结构数据	-（必填）
valueField	string	节点值字段名（用于标识节点唯一性）	'value'
labelField	string	节点显示文本字段名	'label'
childrenField	string	子节点字段名	'children'
multiple	boolean	是否支持多选	false
checkStrictly	boolean	是否取消父子节点关联（独立选择）	false
autoCheckParent	boolean	非严格模式下，是否自动选中父节点	true
defaultExpandedKeys	Array<number/string>	默认展开的节点 key 数组	[]
defaultExpandedLevel	number	默认展开的层级（优先级高于 defaultExpandedKeys）	0
disabled	boolean	是否禁用整个树	false
disabledField	string	节点禁用状态的字段名	'disabled'
bordered	boolean	是否显示边框	false
showIcon	boolean	是否显示节点图标（通过 iconField 指定字段）	true
iconField	string	节点图标字段名	'icon'

3. 事件（Events）

事件名	回调参数	说明
select	(item: FlattenedItem) => void	节点选中状态变化时触发
expand	(item: FlattenedItem) => void	节点展开/折叠状态变化时触发

4. 插槽（Slots）

插槽名	说明	参数
node	自定义节点内容	{ value: 节点数据, level: 层级 }
header	树顶部的自定义内容	-

5. 示例代码

<template><VbenTreev-model="selectedKeys":tree-data="treeData":multiple="true":check-strictly="false"label-field="name"value-field="id"children-field="children"@select="handleSelect"><template #node="{ value }"><span>{{ value.name }}</span><span v-if="value.size" class="ml-2 text-gray-500">({{ value.size }})</span></template></VbenTree>
</template><script lang="ts" setup>
import { ref } from 'vue';
import { VbenTree } from '@core/ui-kit/shadcn-ui/src/ui/tree';// 示例数据
const treeData = ref([{id: 1,name: '文件夹1',children: [{ id: 11, name: '文件1-1', size: '10KB' },{ id: 12, name: '文件1-2', size: '20KB' },],},{id: 2,name: '文件夹2',children: [{ id: 21, name: '文件2-1', size: '15KB' }],},
]);// 选中的节点值
const selectedKeys = ref<number[]>([11]);// 选中事件处理
const handleSelect = (item) => {console.log('选中节点:', item.value);
};
</script>

6. 方法（通过 ref 调用）

方法名	说明	参数
expandAll	展开所有节点	-
collapseAll	折叠所有节点	-
expandNodes	展开指定节点	keys: Arrayable<number/string>
collapseNodes	折叠指定节点	keys: Arrayable<number/string>
getItemByValue	根据值获取节点数据	value: number/string

示例：

<template><VbenTree ref="treeRef" :tree-data="treeData" /><button @click="handleExpandAll">展开全部</button>
</template><script lang="ts" setup>
import { ref } from 'vue';
import { VbenTree } from '@core/ui-kit/shadcn-ui/src/ui/tree';const treeRef = ref();
const handleExpandAll = () => {treeRef.value?.expandAll();
};
</script>

注意事项

• 数据格式：treeData 需为数组，每个节点的子节点通过 childrenField 指定的字段（默认 children）嵌套。
• 选中值绑定：通过 v-model 绑定选中的节点值（单选为单个值，多选为数组）。
• 禁用节点：可通过节点数据中的 disabledField 字段（默认 disabled）单独禁用某个节点。