Virtual Tree

高性能虚拟树组件，支持 Vue 2 和 Vue 3。基于虚拟列表技术，轻松应对海量数据渲染。

特性

• 高性能虚拟渲染：仅渲染可视区域节点，轻松应对万级数据
• 懒加载支持：支持子节点懒加载和分页加载更多
• 多选模式：支持单选/多选模式，以及复选框父子联动
• 手风琴模式：支持手风琴展开
• 双端支持：同时支持 Vue 2 和 Vue 3
• 类型完善：完整的 TypeScript 类型支持

安装

npm install lhw-virtual-tree

基础使用

<template>
  <VirtualTree
    :data="treeData"
    :height="400"
    :item-height="36"
    @select="handleSelect"
    @expand="handleExpand"
  />
</template>

<script setup>
import { ref } from 'vue'
import { VirtualTree, type TreeNode } from 'lhw-virtual-tree'

const treeData = ref<TreeNode[]>([
  {
    id: 1,
    label: '节点 1',
    children: [
      { id: 11, label: '子节点 1-1' },
      { id: 12, label: '子节点 1-2' }
    ]
  },
  {
    id: 2,
    label: '节点 2',
    children: []
  }
])

const handleSelect = (node) => {
  console.log('选中节点:', node)
}

const handleExpand = (node, expanded) => {
  console.log('展开状态:', expanded, node)
}
</script>

Props

| 参数 | 说明 | 类型 | 默认值 | | ------------------- | --------------------------- | ---------------------- | ------- | | data | 树形数据 | TreeNode[] | [] | | height | 容器高度 (px) | number | 400 | | itemHeight | 每项高度 (px) | number | 36 | | showCheckbox | 是否显示复选框 | boolean | false | | multiple | 是否支持多选 | boolean | false | | accordion | 是否手风琴模式 | boolean | false | | defaultExpandedKeys | 默认展开的节点 keys | (string \| number)[] | [] | | defaultCheckedKeys | 默认选中的节点 keys | (string \| number)[] | [] | | lazy | 是否启用懒加载 | boolean | false | | loadDistance | 触发加载更多的距离阈值 (px) | number | 0 |

Events

| 事件名 | 说明 | 回调参数 | | -------------- | ------------------------------------- | --------------------------------------------- | | select | 节点选中时触发 | (node: TreeNode) => void | | expand | 节点展开/收起时触发 | (node: TreeNode, expanded: boolean) => void | | load-node | 懒加载子节点（需设置 lazy） | (node: TreeNode, resolve, reject) => void | | load-more | 滚动到底部加载更多 | () => void | | load-more-node | 懒加载更多子节点（节点 hasMore=true） | (node: TreeNode, resolve, reject) => void |

Methods

通过 ref 调用：

<template>
  <VirtualTree ref="treeRef" :data="treeData" />
</template>

<script setup>
const treeRef = ref();

// 展开节点
treeRef.value.expandNode(id);

// 收起节点
treeRef.value.collapseNode(id);

// 获取选中的节点
treeRef.value.getCheckedNodes();

// 获取展开的节点
treeRef.value.getExpandedNodes();
</script>

| 方法名 | 说明 | 参数 | 返回值 | | ---------------- | -------------- | ------------------------ | ------------ | | expandNode | 展开节点 | (id: string \| number) | void | | collapseNode | 收起节点 | (id: string \| number) | void | | getCheckedNodes | 获取选中的节点 | () | TreeNode[] | | getExpandedNodes | 获取展开的节点 | () | TreeNode[] |

TreeNode 类型

interface TreeNode {
  id: string | number; // 节点唯一标识
  label: string; // 节点显示文本
  children?: TreeNode[]; // 子节点
  disabled?: boolean; // 是否禁用
  isLeaf?: boolean; // 是否叶子节点（懒加载模式使用）
  loading?: boolean; // 加载中状态
  hasMore?: boolean; // 是否有更多子节点（分页加载使用）
  [key: string]: any; // 自定义属性
}

高级用法

多选模式

<VirtualTree
  :data="treeData"
  :show-checkbox="true"
  :multiple="true"
  @select="handleSelect"
/>

懒加载子节点

<template>
  <VirtualTree :data="treeData" :lazy="true" @load-node="handleLoadNode" />
</template>

<script setup>
const handleLoadNode = (node, resolve) => {
  // 模拟异步加载
  setTimeout(() => {
    resolve([
      { id: `${node.id}-1`, label: "子节点 1", isLeaf: false, children: [] },
      { id: `${node.id}-2`, label: "子节点 2", isLeaf: true },
    ]);
  }, 500);
};
</script>

加载更多（分页）

<template>
  <VirtualTree
    :data="treeData"
    :load-distance="50"
    @load-more="handleLoadMore"
    @load-more-node="handleLoadMoreNode"
  />
</template>

<script setup>
const handleLoadMore = () => {
  // 加载更多根节点
  console.log("加载更多根节点");
};

const handleLoadMoreNode = (node, resolve) => {
  // 加载更多子节点
  console.log("加载更多子节点:", node.id);
  setTimeout(() => {
    resolve([...newChildren]);
  }, 500);
};
</script>

默认展开/选中

<VirtualTree
  :data="treeData"
  :default-expanded-keys="[1, 2]"
  :default-checked-keys="[11]"
/>

手风琴模式

手风琴模式下，每次只能展开一个节点。

<VirtualTree :data="treeData" :accordion="true" />

CDN 引入

<!-- Vue 2 -->
<script src="https://unpkg.com/lhw-virtual-tree/dist/vue2/virtual-tree.umd.js"></script>

<!-- Vue 3 -->
<script src="https://unpkg.com/lhw-virtual-tree/dist/vue3/virtual-tree.umd.js"></script>

构建

# 构建全部（Vue 2 + Vue 3）
npm run build

# 仅构建 Vue 2
npm run build:vue2

# 仅构建 Vue 3
npm run build:vue3

License

MIT