FxTreeV2 虚拟树

FxTreeV2 属于 @fx/components，不依赖任何 UI 框架。基于 FxFixedSizeList 只渲染可见节点，适合任意数据量的树；内部组合 FxTreeNode + FxCheckbox + FxIcon。

为任意数据量提供极速滚动的树视图。

基础用法

基础的树形结构。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  />
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
}
const data = createData(4, 30, 40)
</script>

可选择

用于节点选择。点击「清空勾选」可编程式清空全部勾选状态（setCheckedKeys([])），勾选状态应同步回退。

<template>
  <FxBtn class="!ml-0" style="margin-bottom: 5px" @click="clearChecked">清空勾选</FxBtn>
  <FxTreeV2
    ref="treeRef"
    style="max-width: 600px"
    :data="data"
    :props="props"
    show-checkbox
    :height="200"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import type { FxTreeV2Instance } from "@fx/components"

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
}
const data = createData(4, 30, 40)

const treeRef = ref<FxTreeV2Instance>()
const clearChecked = () => treeRef.value!.setCheckedKeys([])
</script>

WARNING

使用 show-checkbox 时，由于 check-on-click-leaf 默认为 true，点击叶子节点（最末级）会同时切换其勾选状态。

禁用 checkbox

可将节点的 checkbox 设为禁用。示例中 props 声明了 disabled 字段，key 含 2 的节点被设为 disabled: true，对应 checkbox 进入禁用态、不可点击。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    :props="props"
    show-checkbox
    :height="200"
  />
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
  disabled: boolean
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
        disabled: nodeKey.includes("2"),
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
  disabled: "disabled",
}
const data = createData(4, 30, 40)
</script>

默认展开与默认勾选

使用 default-expanded-keys 与 default-checked-keys 分别设置初始展开和初始勾选的节点。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    :height="200"
    :props="props"
    show-checkbox
    :default-checked-keys="defaultCheckedKeys"
    :default-expanded-keys="defaultExpandedKeys"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
}
const data = createData(4, 30, 40)
const checkedKeys: string[] = []
const expanedKeys: string[] = []
for (const datum of data) {
  const children = datum.children
  if (children) {
    expanedKeys.push(datum.id)
    checkedKeys.push(children[0].id)
    break
  }
}

const defaultCheckedKeys = ref(checkedKeys)
const defaultExpandedKeys = ref(expanedKeys)
</script>

自定义节点内容

节点内容可自定义，因此可按需加入图标或按钮。通过 default 作用域插槽控制，插槽参数含 node（TreeNode 对象，含 isLeaf / expanded 等状态）与 data（节点数据）。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  >
    <template #default="{ node }">
      <FxIcon
        class="fx-icon--left"
        :name="
          node.isLeaf
            ? 'ep:document'
            : node.expanded
              ? 'ep:folder-opened'
              : 'ep:folder'
        "
      />
      <span class="prefix" :class="{ 'is-leaf': node.isLeaf }">[FxTreeV2]</span>
      <span>{{ node.label }}</span>
    </template>
  </FxTreeV2>
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
}
const data = createData(4, 30, 40)
</script>

<style scoped>
.prefix {
  color: var(--fx-color-primary);
  margin-right: 10px;
}
.prefix.is-leaf {
  color: var(--fx-color-success);
}
</style>

自定义节点类名

通过 props.class 为节点生成自定义类名。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    show-checkbox
    :expand-on-click-node="false"
    :props="{ class: customNodeClass }"
  />
</template>

<script lang="ts" setup>
import type { TreeNode, TreeNodeData } from "@fx/components"

interface Tree {
  id?: string
  value?: string
  label?: string
  isPenultimate?: boolean
  children?: Tree[]
}

const customNodeClass = ({ isPenultimate }: TreeNodeData, _node: TreeNode) =>
  isPenultimate ? "is-penultimate" : ""

const data: Tree[] = [
  {
    id: "1",
    label: "一级 1",
    children: [
      {
        id: "4",
        label: "二级 1-1",
        isPenultimate: true,
        children: [
          { id: "9", label: "三级 1-1-1" },
          { id: "10", label: "三级 1-1-2" },
        ],
      },
    ],
  },
  {
    id: "2",
    label: "一级 2",
    isPenultimate: true,
    children: [
      { id: "5", label: "二级 2-1" },
      { id: "6", label: "二级 2-2" },
    ],
  },
  {
    id: "3",
    label: "一级 3",
    isPenultimate: true,
    children: [
      { id: "7", label: "二级 3-1" },
      { id: "8", label: "二级 3-2" },
    ],
  },
]
</script>

<style scoped>
:deep(.is-penultimate .fx-tree-node__label) {
  color: #626aef;
  font-weight: 600;
}
</style>

自定义节点图标

可为不同节点状态渲染不同图标。节点对象的 isLeaf 与 expanded 属性让你按叶子节点、展开节点、收起节点动态切换图标。

<template>
  <FxTreeV2
    style="max-width: 600px"
    :data="data"
    :props="props"
    :height="200"
  >
    <template #default="{ node }">
      <FxIcon
        class="node-icon"
        :class="{ 'is-leaf': node.isLeaf }"
        :name="
          node.isLeaf
            ? 'ep:document'
            : node.expanded
              ? 'ep:folder-opened'
              : 'ep:folder'
        "
      />
      <span>{{ node.label }}</span>
    </template>
  </FxTreeV2>
</template>

<script lang="ts" setup>
interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => {
  return `${prefix}-${id}`
}

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const props = {
  value: "id",
  label: "label",
  children: "children",
}
const data = createData(4, 30, 40)
</script>

<style scoped>
.node-icon {
  margin-right: 5px;
  color: var(--fx-color-warning);
}
</style>

节点过滤

调用 Tree 实例的 filter 方法过滤节点，参数为过滤关键字。注意必须设置 filter-method，其值为过滤方法。

<template>
  <FxInput
    v-model="query"
    style="width: 240px"
    placeholder="请输入关键字"
    @input="onQueryChanged"
  />
  <FxTreeV2
    ref="treeRef"
    style="max-width: 600px"
    :data="data"
    :props="props"
    :filter-method="filterMethod"
    :height="200"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue"
import type { FxTreeV2Instance, TreeNodeData } from "@fx/components"

interface Tree {
  id: string
  label: string
  children?: Tree[]
}

const getKey = (prefix: string, id: number) => `${prefix}-${id}`

const createData = (
  maxDeep: number,
  maxChildren: number,
  minNodesNumber: number,
  deep = 1,
  key = "node",
): Tree[] => {
  let id = 0
  return Array.from({ length: minNodesNumber })
    .fill(deep)
    .map(() => {
      const childrenNumber =
        deep === maxDeep ? 0 : Math.round(Math.random() * maxChildren)
      const nodeKey = getKey(key, ++id)
      return {
        id: nodeKey,
        label: nodeKey,
        children: childrenNumber
          ? createData(maxDeep, maxChildren, childrenNumber, deep + 1, nodeKey)
          : undefined,
      }
    })
}

const query = ref("")
const treeRef = ref<FxTreeV2Instance>()
const data = createData(4, 30, 5)
const props = {
  value: "id",
  label: "label",
  children: "children",
}

const onQueryChanged = (query: string) => {
  treeRef.value!.filter(query)
}
const filterMethod = (query: string, node: TreeNodeData) =>
  node.label!.includes(query)
</script>

API

Attributes

属性	说明	类型	默认值
data	树数据	Array<Record<string, any>>	[]
empty-text	数据为空时显示的文本	string	暂无数据
height	树的高度（视口高度，超出滚动）	number	200
props	数据字段别名配置，见下表	TreeOptionProps	见下表
highlight-current	是否高亮当前节点	boolean	false
expand-on-click-node	是否在点击节点时展开/收起；为 false 时仅点击箭头图标才展开/收起	boolean	true
check-on-click-node	是否在点击节点时勾选/取消勾选；为 false 时仅点击 checkbox 才切换	boolean	false
check-on-click-leaf	是否在点击叶子节点时勾选/取消勾选	boolean	true
default-expanded-keys	默认展开的节点 key 数组	Array<string | number>	—
show-checkbox	是否显示 checkbox（节点可选）	boolean	false
check-strictly	显示 checkbox 时，父子节点是否不联动	boolean	false
default-checked-keys	默认勾选的节点 key 数组	Array<string | number>	—
current-node-key	当前选中节点的 key	string | number	—
filter-method	过滤节点的方法（配合 filter 实例方法使用；返回 false 的节点被隐藏）	(query, data, node) => boolean	—
indent	相邻层级节点的水平缩进（像素）	number	16
icon	自定义树节点图标：IconString（传给 FxIcon）或组件；默认 ep:caret-right	IconString | Component	—
item-size	单个节点高度（虚拟列表行高）	number	26
scrollbar-always-on	是否始终显示滚动条	boolean	false
perf-mode	性能模式：增大内存占用以换取更流畅的滚动	boolean	true
accordion	是否每次只展开同级一个节点	boolean	false

props（字段别名）

属性	说明	类型	默认值
value	节点唯一标识字段（值需全树唯一）	string	id
label	指定作为节点标签的字段	string	label
children	指定作为子树的字段	string	children
disabled	指定节点 checkbox 是否禁用的字段	string	disabled
class	自定义节点类名	string | (data, node) => string | object	—

Exposes

名称	说明	参数
filter	过滤所有节点，不匹配的节点被隐藏	(query: string)
getCheckedNodes	返回当前勾选的节点数据数组	(leafOnly: boolean)
getCheckedKeys	返回当前勾选的节点 key 数组	(leafOnly: boolean)
setCheckedKeys	勾选指定节点	(keys: TreeKey[])
setChecked	勾选/取消勾选单个节点，deep 表示是否递归子节点	(key: TreeKey, checked: boolean, deep?: boolean)
setExpandedKeys	展开指定节点	(keys: TreeKey[])
getHalfCheckedNodes	返回半选节点数据数组	—
getHalfCheckedKeys	返回半选节点 key 数组	—
getCurrentKey	返回当前高亮节点的 key（undefined 表示无高亮）	—
getCurrentNode	返回当前高亮节点的数据（undefined 表示无高亮）	—
setCurrentKey	设置高亮节点	(key: TreeKey)
getNode	按 key 或 data 获取节点	(data: TreeKey | TreeNodeData)
expandNode	展开指定节点	(node: TreeNode)
collapseNode	收起指定节点	(node: TreeNode)
toggleCheckbox	切换节点勾选态	(node: TreeNode, checked, nodeClick?)
setData	大数据量时绕过响应式直接设置数据，避免响应式开销	(data: TreeData)
scrollTo	滚动到指定位置	(offset: number)
scrollToNode	滚动到指定节点（strategy: auto / smart / center / start / end）	(key: TreeKey, strategy?)

Events

事件名	说明	参数
node-click	点击节点时触发	(data, node, e)
node-drop	拖拽某物并放置到节点时触发	(data, node, e)
node-contextmenu	右键点击节点时触发	(e, data, node)
check-change	节点勾选状态变化时触发	(data, checked)
check	点击 checkbox 时触发	(data, { checkedNodes, checkedKeys, halfCheckedNodes, halfCheckedKeys })
current-change	当前节点变化时触发	(data, node)
node-expand	节点展开时触发	(data, node)
node-collapse	节点收起时触发	(data, node)

Slots

插槽名	说明	类型
default	自定义节点内容	{ node: TreeNode, data: TreeNodeData }
empty	数据为空时的自定义内容	—

类型声明

展开声明

type TreeKey = string | number
type TreeNodeData = Record<string, any>
type TreeData = TreeNodeData[]

interface TreeNode {
  key: TreeKey
  level: number
  parent?: TreeNode
  children?: TreeNode[]
  data: TreeNodeData
  disabled?: boolean
  label?: string
  isLeaf?: boolean
  expanded?: boolean
  isEffectivelyChecked?: boolean
}