Vue Virtual Tree

一个基于 vue-virtual-scroller@next 的高性能 Vue 3 虚拟树列表组件库，功能参照 Element Plus Tree 组件。

特性

• ⚡️ 虚拟滚动 - 支持大量数据的高性能渲染
• 🌳 完整树功能 - 展开/折叠、选择、过滤、拖拽等
• 🎨 Element Plus 风格 - API 设计与 Element Plus Tree 保持一致
• 📦 TypeScript - 完整的类型支持
• 🔧 灵活配置 - 支持自定义字段映射、节点内容等

在线demo

安装

pnpm add @wxwzl/vue-virtual-tree vue-virtual-scroller@next

快速开始

<template>
  <VirtualTree :data="treeData" :height="400" />
</template>

<script setup lang="ts">
  import { VirtualTree } from "vue-virtual-tree";
  import "vue-virtual-tree/style";

  const treeData = [
    {
      id: 1,
      label: "节点 1",
      children: [
        { id: 2, label: "节点 1-1" },
        { id: 3, label: "节点 1-2" },
      ],
    },
  ];
</script>

加载状态

<template>
  <!-- 使用默认加载状态 -->
  <VirtualTree :data="treeData" :loading="isLoading" :height="400" />

  <!-- 自定义加载状态 -->
  <VirtualTree :data="treeData" :loading="isLoading" :height="400">
    <template #tree-loading>
      <div class="custom-loading">数据加载中...</div>
    </template>
  </VirtualTree>
</template>

<script setup lang="ts">
  import { ref } from 'vue'
  import { VirtualTree } from "vue-virtual-tree";

  const isLoading = ref(true)
  const treeData = ref([])

  // 模拟数据加载
  setTimeout(() => {
    treeData.value = [
      { id: 1, label: "节点 1" },
      { id: 2, label: "节点 2" },
    ]
    isLoading.value = false
  }, 2000)
</script>

功能

基础功能

• ✅ 树形结构展示
• ✅ 节点展开/折叠
• ✅ 虚拟滚动（支持大量数据）
• ✅ 节点点击事件

选择功能

• ✅ 单选模式
• ✅ 多选模式（复选框）
• ✅ 节点选中状态管理
• ✅ 父子节点关联选择

数据功能

• ✅ 懒加载节点
• ✅ 节点过滤/搜索
• ✅ 默认展开节点
• ✅ 默认选中节点

交互功能

• ✅ 自定义节点内容（插槽）
• ✅ 自定义节点类名
• ✅ 节点拖拽排序
• ✅ 手风琴模式（同级节点互斥展开）

高级功能

• ✅ 节点禁用
• ✅ 节点图标自定义
• ✅ 节点加载状态
• ✅ 空状态展示

API

Props

| 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | data | 树形数据 | TreeNodeData[] | [] | | props | 数据字段映射配置 | TreePropsConfig | {} | | show-checkbox | 是否显示复选框 | boolean | false | | check-strictly | 是否严格遵循父子不关联 | boolean | false | | default-expand-all | 是否默认展开所有节点 | boolean | false | | default-expanded-keys | 默认展开的节点 key 数组 | (string \| number)[] | [] | | default-checked-keys | 默认选中的节点 key 数组 | (string \| number)[] | [] | | current-node-key | 当前选中的节点 key | string \| number | - | | expand-on-click-node | 是否点击节点展开 | boolean | true | | lazy | 是否懒加载 | boolean | false | | load | 懒加载方法 | Function | - | | filter-node-method | 节点过滤方法 | Function | - | | accordion | 是否手风琴模式 | boolean | false | | draggable | 是否可拖拽 | boolean | false | | allow-drop | 拖拽时判断是否允许放置 | Function | - | | allow-drag | 拖拽时判断节点是否允许拖拽 | Function | - | | item-size | 节点高度（固定高度时使用） | number | 32 | | height | 虚拟滚动容器高度 | number \| string | '100%' | | indent | 每一级节点的缩进值，支持数字或函数（函数入参为 node: FlatTreeNode） | number \| (node) => number | 18 | | loading | 是否显示加载状态 | boolean | false |

Events

| 事件名 | 说明 | 参数 | | --------------- | ---------------- | ------------------------------------------- | | node-click | 节点点击 | (data, node, event) | | node-check | 节点复选框点击 | (data, checked) | | node-expand | 节点展开 | (data, node) | | node-collapse | 节点折叠 | (data, node) | | current-change | 当前选中节点变化 | (data, node) | | node-drag-start | 拖拽开始 | (node, event) | | node-drag-enter | 拖拽进入 | (draggingNode, event, node) | | node-drag-leave | 拖拽离开 | (draggingNode, event, node) | | node-drag-over | 拖拽悬停 | (draggingNode, event, node) | | node-drag-end | 拖拽结束 | (draggingNode, event) | | node-drop | 拖拽放置 | (draggingNode, dropNode, dropType, event) |

Methods

| 方法名 | 说明 | 参数 | | ----------------- | -------------------------- | ---------------------------------- | | getCheckedNodes | 获取选中的节点 | (leafOnly?, includeHalfChecked?) | | getCheckedKeys | 获取选中的节点 key | (leafOnly?) | | setCheckedNodes | 设置选中的节点 | (nodes, leafOnly?) | | setCheckedKeys | 设置选中的节点 key | (keys, leafOnly?) | | getCurrentNode | 获取当前选中节点 | - | | setCurrentNode | 设置当前选中节点 | (node) | | getCurrentKey | 获取当前选中节点的 key | - | | setCurrentKey | 设置当前选中节点的 key | (key) | | filter | 过滤节点 | (value) | | getNode | 根据 key 获取节点 | (key) | | remove | 删除节点 | (key) | | append | 追加节点 | (data, parentKey?) | | insertBefore | 在节点前插入 | (data, key) | | insertAfter | 在节点后插入 | (data, key) | | updateKeyChildren | 更新节点的子节点（懒加载） | (key, data) | | scrollToNode | 滚动到指定节点 | (key, options?) |

Slots

| 插槽名 | 说明 | 参数 | | ------------- | -------------------- | ---------------- | | default | 自定义节点内容 | { node, data } | | empty | 空状态内容 | - | | tree-loading | 整个树的加载状态 | - | | loading | 节点懒加载时的状态 | { node, data } | | icon | 自定义节点图标 | { node, data } |

开发

# 安装依赖
pnpm install

# 启动开发环境
pnpm dev

# 构建
pnpm build

技术栈

• Vue 3 (Composition API)
• TypeScript
• vue-virtual-scroller@next
• Vite
• pnpm

许可证

MIT