@wxwzl/vue-virtual-tree

Vue Virtual Tree

一个基于自研虚拟列表（@wxwzl/vue-virtual-list）的高性能 Vue 3 虚拟树列表组件库，功能参照 Element Plus Tree 组件。

特性

• ⚡️ 虚拟滚动 - 支持百万级节点的高性能渲染（分片初始化，主线程不卡顿）
• 🌳 完整树功能 - 展开/折叠、选择、过滤、拖拽等
• 🎨 Element Plus 风格 - API 设计与 Element Plus Tree 保持一致
• 📦 TypeScript - 完整的类型支持
• 🔧 灵活配置 - 支持自定义字段映射、节点内容等

在线demo

安装

pnpm add @wxwzl/vue-virtual-tree

快速开始

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

<script setup lang="ts">
  import { VirtualTree } from "@wxwzl/vue-virtual-tree";
  import "@wxwzl/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 "@wxwzl/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

Events

Methods

replace 方法说明

replace(data, key) 用于节点级局部更新，替换指定节点的数据：

• data 中不包含 children 时：保留原子树，原地更新节点数据（O(1) 视图刷新，不重建整树）
• data 中包含 children 时：整体替换该节点的子树（走全量重建）
• 新数据的 key 与原 key 不同时：自动迁移该节点的展开 / 勾选 / 半选 / 当前选中状态

const treeRef = ref();

// 仅更新 label，保留子树
treeRef.value.replace({ id: 1, label: "新名称" }, 1);

// 替换子树
treeRef.value.replace({ id: 1, label: "新名称", children: [{ id: 11, label: "子节点" }] }, 1);

Slots

大数据量与性能

组件针对百万级节点做了专项优化：

• 分片初始化：扁平化按 8ms 时间片分批执行并让出主线程，初始化期间页面保持可交互（会短暂显示加载状态），百万节点不卡顿
• O(n) 勾选状态：父子关联勾选基于扁平数组一次倒序遍历完成，无 O(n²) 的元数据预计算
• 两种滚动模式（统一由自研 @wxwzl/vue-virtual-list 承载，Fenwick 树高度模型，展开/收起仅 O(log n)）：
  • 默认动态行高：支持超长 label 自动换行，行高由 ResizeObserver 实测回写
  • fixed-height 固定行高：O(1) 滚动定位、无高度测量，超大数据量下快速拖拽滚动条不白屏，配合 item-size 指定行高
• 局部更新：优先使用 append / remove / insertBefore / insertAfter / replace / updateKeyChildren 方法做运行时数据变更，避免整树重建

注意：data prop 采用浅监听（数组引用变化才触发重建）。原地修改数组或节点字段不会刷新视图，请改用上述命令式方法，或整体替换 data 数组。

Vapor 模式（实验性，Vue ≥ 3.6）

组件库提供 opt-in 的 Vapor 子路径入口：整链（VirtualTree / VirtualList / TreeNodeItem / TreeNode）按 Vapor 编译，VirtualList 已内联进产物（不依赖 @wxwzl/vue-virtual-list 的 vdom 版本），经 vaporInteropPlugin 与 vdom 应用混跑（仅应用根一处模式边界）。默认入口不受影响，永远是稳定的 vdom 路径。

已知边界：VirtualList 的 rowMemo 与 dynamic 隐藏测量通道是手写的 vdom 子组件，开启后经 interop 混跑（不影响正确性）。

import { createApp, vaporInteropPlugin } from "vue";
import { VirtualTree } from "@wxwzl/vue-virtual-tree/vapor";
import "@wxwzl/vue-virtual-tree/style";

const app = createApp(App);
app.use(vaporInteropPlugin); // 混合模式（vdom 父 → vapor 子）必需
app.mount("#app");

使用前提（均为 Vue 3.6 RC 的打包限制）：

1. vue 版本 ≥ 3.6；

2. 应用内必须统一把 vue 解析到带 vapor 运行时的独立产物——vapor runtime 与 vaporInteropPlugin 只存在于 vue.runtime-with-vapor.*.js，默认 bundler 入口不含。Vite 配置示例：

   export default defineConfig({
     resolve: {
       alias: { vue: "vue/dist/vue.runtime-with-vapor.esm-browser.js" },
     },
   });
   

   不可混用两份 vue 产物（会出现静默的响应式系统分裂）。

Vapor 编译基于 Vue 3.6 RC，属实验特性；性能对比见 playground 的「Vapor vs Vdom 基准对比」页。实测在虚拟滚动场景下（可视区仅数十行，实例开销已被虚拟化消除）vapor 暂无性能收益，该入口定位为技术验证与未来就绪，不建议以性能为目的接入。

开发

# 安装依赖
pnpm install

# 启动开发环境
pnpm dev

# 构建
pnpm build

技术栈

• Vue 3 (Composition API)
• TypeScript
• @wxwzl/vue-virtual-list（自研虚拟列表）
• Vite
• pnpm

许可证

MIT