vben admin5组件文档（豆包版）---VbenTree

一只一只妖

1248人浏览 · 2025-08-29 18:19:35

一只一只妖 · 2025-08-29 18:19:35 发布

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>
  <VbenTree
    v-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>