Tree 树形控件

BzTree 是基于 Element Plus ElTreeV2 封装的高性能虚拟化树形控件，适用于大数据量的层级数据展示。组件会自动撑满容器高度，内部使用 ResizeObserver 动态跟踪容器尺寸变化。

注意：BzTree 基于 ElTreeV2 虚拟化树组件，数据要求为扁平化 children 结构（非懒加载），支持所有 ElTreeV2 的对外方法和属性。

基础用法

通过 data 传入树形数据，使用 height 设置组件高度。

基础用法

Vue Demo

一级节点 1

一级节点 2

可直接复制并在项目中使用

<template>
  <BzTree
    :data="treeData"
    height="300px"
  />
</template>

<script setup lang="ts">
const treeData = [
  {
    id: '1',
    label: '一级节点 1',
    children: [
      { id: '1-1', label: '二级节点 1-1' },
      { id: '1-2', label: '二级节点 1-2', disabled: true },
    ],
  },
  {
    id: '2',
    label: '一级节点 2',
    children: [
      { id: '2-1', label: '二级节点 2-1' },
      { id: '2-2', label: '二级节点 2-2' },
    ],
  },
]
</script>

深层数据结构

支持任意深度的嵌套数据。

深层数据

Vue Demo

Asia

Europe

可直接复制并在项目中使用

<template>
  <BzTree
    :data="deepTreeData"
    height="320px"
  />
</template>

<script setup lang="ts">
const deepTreeData = [
  {
    id: '1',
    label: 'Asia',
    children: [
      { id: '1-1', label: 'China', children: [
        { id: '1-1-1', label: 'Beijing' },
        { id: '1-1-2', label: 'Shanghai' },
      ]},
      { id: '1-2', label: 'Japan' },
    ],
  },
  {
    id: '2',
    label: 'Europe',
    children: [
      { id: '2-1', label: 'Germany' },
      { id: '2-2', label: 'France' },
    ],
  },
]
</script>

复选框模式

通过 showCheckbox 开启复选框，配合 defaultCheckedKeys 设置默认选中项。

复选框

Vue Demo

权限管理

系统设置

可直接复制并在项目中使用

<template>
  <BzTree
    :data="checkboxData"
    :show-checkbox="true"
    :default-checked-keys="defaultCheckedKeys"
    height="300px"
    @check="(...args) => console.log('check', args)"
  />
</template>

<script setup lang="ts">
const checkboxData = [
  {
    id: '1',
    label: '权限管理',
    children: [
      { id: '1-1', label: '用户管理' },
      { id: '1-2', label: '角色管理' },
    ],
  },
  {
    id: '2',
    label: '系统设置',
    children: [
      { id: '2-1', label: '基本设置' },
      { id: '2-2', label: '日志管理' },
    ],
  },
]
const defaultCheckedKeys = ['1-1']
</script>

节点事件

支持 node-click 和 current-change 等事件，disabled 节点不会被高亮选中。

节点事件

Vue Demo

一级节点 1

一级节点 2

可直接复制并在项目中使用

<template>
  <BzTree
    :data="treeData"
    height="300px"
    @node-click="handleNodeClick"
    @current-change="handleCurrentChange"
  />
</template>

<script setup lang="ts">
function handleNodeClick(data: any, node: any) {
  console.log('node-click', data, node)
}
function handleCurrentChange(data: any, node: any) {
  console.log('current-change', data, node)
}
</script>

自定义节点内容

通过默认插槽自定义每个节点的渲染内容。

自定义节点

Vue Demo

一级节点 1 [1]

一级节点 2 [2]

可直接复制并在项目中使用

<template>
  <BzTree :data="treeData" height="300px">
    <template #default="{ node }">
      <span>{{ node.label }} [{{ node.key }}]</span>
    </template>
  </BzTree>
</template>

<script setup lang="ts">
const treeData = [
  {
    id: '1',
    label: '一级节点 1',
    children: [
      { id: '1-1', label: '二级节点 1-1' },
      { id: '1-2', label: '二级节点 1-2' },
    ],
  },
]
</script>

Props

参数	说明	类型	默认值
data	树形数据，需包含 id、label、children 字段	Record<string, any>[]	[]
height	树组件高度，支持 CSS 单位	string	'100%'
emptyText	数据为空时展示的文本	string	'暂无数据'
expandOnClickNode	是否在点击节点时展开或收缩节点，false 则仅点击箭头图标触发	boolean	true
defaultExpandedKeys	默认展开的节点 key 数组	string[]	-
showCheckbox	是否展示复选框	boolean	false
checkStrictly	复选框是否严格遵循父子不互相关联	boolean	false
defaultCheckedKeys	默认选中节点的 key 数组	any[]	-
currentNodeKey	当前选中节点的 key	string | number	-
indent	父子节点之间的缩进间距 (px)	number	16
itemSize	单个节点高度 (px)	number	40
scrollbarAlwaysOn	是否始终展示滚动条	boolean	false
highlightCurrent	是否高亮当前选中的节点	boolean	true

Events

事件名	说明	回调参数
node-click	节点被点击时触发	(data, node, event: MouseEvent)
node-drop	节点拖拽放置时触发	(data, node, event: DragEvent)
node-contextmenu	节点右键菜单时触发	(event, data, node)
check-change	节点选中状态变化时触发	(data, checked: boolean)
check	复选框点击时触发	(data, info: { checkedNodes, checkedKeys, ... })
current-change	当前选中节点变化时触发	(data, node)
node-expand	节点展开时触发	(data, node)
node-collapse	节点收缩时触发	(data, node)

Slots

插槽名	说明
default	自定义节点内容，作用域参数 { node }，node 包含 label、key、data 等属性

Expose 方法

通过组件实例可调用以下方法：

方法名	说明	参数
filter	过滤所有树节点，过滤后的节点将被隐藏	(query: string)
getCheckedNodes	获取当前选中节点的数组	(leafOnly?: boolean)
getCheckedKeys	获取当前选中节点 key 的数组	(leafOnly?: boolean)
setCheckedKeys	通过 keys 设置当前勾选的节点	(keys: any[])
setChecked	设置某个节点是否被选中	(key, checked: boolean, deep?: boolean)
setExpandedKeys	设置当前展开的节点	(keys: any[])
getHalfCheckedNodes	获取当前半选中节点组成的数组	-
getHalfCheckedKeys	获取当前半选中节点的 key 数组	-
getCurrentKey	获取当前被选中节点的 key	-
getCurrentNode	获取当前被选中节点的 data	-
setCurrentKey	通过 key 设置某个节点的当前选中状态	(key: any)
getNode	通过 key 或 data 获取节点	(data: any)
expandNode	展开指定节点	(node: any)
collapseNode	折叠指定节点	(node: any)
setData	数据量非常庞大时，显式设置数据	(data: any[])
scrollTo	滚动到给定位置 (2.8.0+)	(offset: number)
scrollToNode	使用给定滚动策略滚动至指定节点 (2.8.0+)	(key: any, strategy?: any)