BizTree 业务树

基于 el-tree 封装的“展示 + 操作”形态业务树：关键字搜索过滤（命中高亮）、复选（父子关联开关）、展开层级控制、懒加载透传、内置 loading 遮罩、节点 hover 操作按钮（新增 / 编辑 / 删除事件外抛，action-filter 按节点定制）。其余属性 / 事件透传 el-tree（node-click、node-expand、check 等）。菜单管理、组织部门管理、商品 / 物料分类管理。

与 BizOrgTreeSelect 的边界：后者是表单字段级的“选出来”形态；本组件面向页面主体区的展示与维护（搜索、操作、懒加载一体的管理树）。

基础用法

华东大区

上海分公司

市场部

销售部

杭州分公司

运营部

华北大区

北京分公司

研发部

天津分公司

静态数据 + expand-level 层级展开 + node-click 当前高亮（透传 el-tree）。

<script setup lang="ts">
/** 场景：分类管理——基础展示、层级展开控制、点击节点高亮（node-click 透传 el-tree） */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeNodeData } from 'vue3-ep-biz-lib'

const data: BizTreeNodeData[] = [
  {
    id: 1,
    label: '华东大区',
    children: [
      {
        id: 11,
        label: '上海分公司',
        children: [
          { id: 111, label: '市场部' },
          { id: 112, label: '销售部' },
        ],
      },
      { id: 12, label: '杭州分公司', children: [{ id: 121, label: '运营部' }] },
    ],
  },
  {
    id: 2,
    label: '华北大区',
    children: [
      { id: 21, label: '北京分公司', children: [{ id: 211, label: '研发部' }] },
      { id: 22, label: '天津分公司' },
    ],
  },
]

const clicked = ref('')

const onClick = (nodeData: BizTreeNodeData): void => {
  clicked.value = String(nodeData.label)
  ElMessage.info(`选中：${clicked.value}`)
}
</script>

<template>
  <div style="max-width: 360px">
    <BizTree :data="data" :expand-level="2" @node-click="onClick" />
    <p v-if="clicked" style="margin-top: 10px; font-size: 13px; color: #909399">
      当前选中：{{ clicked }}
    </p>
  </div>
</template>

显示代码

搜索过滤

系统管理

用户管理

用户列表

用户分组

角色管理

角色列表

数据权限

操作日志

商品中心

商品列表

分类管理

searchable 输入即过滤，命中关键词自动高亮、命中路径自动展开。

<script setup lang="ts">
/** 场景：节点检索——searchable 输入即过滤，命中关键词自动高亮，命中路径自动展开 */
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeNodeData } from 'vue3-ep-biz-lib'

const data: BizTreeNodeData[] = [
  {
    id: 1,
    label: '系统管理',
    children: [
      {
        id: 11,
        label: '用户管理',
        children: [
          { id: 111, label: '用户列表' },
          { id: 112, label: '用户分组' },
        ],
      },
      {
        id: 12,
        label: '角色管理',
        children: [
          { id: 121, label: '角色列表' },
          { id: 122, label: '数据权限' },
        ],
      },
      { id: 13, label: '操作日志' },
    ],
  },
  {
    id: 2,
    label: '商品中心',
    children: [
      { id: 21, label: '商品列表' },
      { id: 22, label: '分类管理' },
    ],
  },
]
</script>

<template>
  <div style="max-width: 360px">
    <BizTree :data="data" searchable default-expand-all filter-placeholder="搜索菜单 / 角色" />
  </div>
</template>

显示代码

节点操作按钮

商品中心

商品列表

分类管理

hover 节点显示操作按钮；新增 / 删除直接操作本地数据，编辑仅演示事件外抛

show-actions hover 显示操作按钮，node-add / node-edit / node-remove 事件外抛（数据变更由外部处理，示例内直接改本地数据）；action-filter 按节点定制可见操作。

<script setup lang="ts">
/** 场景：菜单维护——hover 操作按钮增删改（事件外抛，数据变更由外部处理），actionFilter 控制叶子不显示新增 */
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeAction, BizTreeNodeData, BizTreeInstance, BizTreeTreeNode } from 'vue3-ep-biz-lib'

let seed = 100
const data = ref<BizTreeNodeData[]>([
  {
    id: 1,
    label: '商品中心',
    children: [
      { id: 11, label: '商品列表', isLeaf: true },
      { id: 12, label: '分类管理', isLeaf: true },
    ],
  },
])

const treeRef = ref<BizTreeInstance>()

/** 叶子节点隐藏“新增子级” */
const actionFilter = (_data: BizTreeNodeData, isLeaf: boolean): BizTreeAction[] =>
  isLeaf ? ['edit', 'remove'] : ['add', 'edit', 'remove']

const onAdd = (nodeData: BizTreeNodeData): void => {
  const child = { id: ++seed, label: `新分类 ${seed}`, isLeaf: true }
  treeRef.value?.append(child, Number(nodeData.id))
  ElMessage.success(`已在「${nodeData.label}」下新增子节点`)
}

const onRemove = (nodeData: BizTreeNodeData, node: BizTreeTreeNode): void => {
  treeRef.value?.remove(node)
  ElMessage.success(`已删除「${nodeData.label}」`)
}
</script>

<template>
  <div style="max-width: 360px">
    <BizTree
      ref="treeRef"
      :data="data"
      :action-filter="actionFilter"
      show-actions
      default-expand-all
      @node-add="onAdd"
      @node-edit="(d: BizTreeNodeData) => ElMessage.info(`编辑：${d.label}`)"
      @node-remove="onRemove"
    />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      hover 节点显示操作按钮；新增 / 删除直接操作本地数据，编辑仅演示事件外抛
    </p>
  </div>
</template>

显示代码

复选形态

父子不关联（checkStrictly）

数据看板

销售统计

库存统计

报表中心

日报

月报

已勾选叶子节点：（暂无）

checkable 复选 + check-strictly 父子关联开关，getCheckedNodes 经 expose 取完整节点。

<script setup lang="ts">
/** 场景：资源勾选——复选形态 + 父子关联开关（checkStrictly），getCheckedNodes 取完整节点 */
import { ref } from 'vue'
import { ElSwitch } from 'element-plus'
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeNodeData, BizTreeInstance } from 'vue3-ep-biz-lib'

const data: BizTreeNodeData[] = [
  {
    id: 1,
    label: '数据看板',
    children: [
      { id: 11, label: '销售统计' },
      { id: 12, label: '库存统计' },
    ],
  },
  {
    id: 2,
    label: '报表中心',
    children: [
      { id: 21, label: '日报' },
      { id: 22, label: '月报' },
    ],
  },
]

const treeRef = ref<BizTreeInstance>()
const strict = ref(true)
const checked = ref<string[]>([])

const onCheck = (): void => {
  checked.value = treeRef.value?.getCheckedNodes(true).map((n) => String(n.label)) ?? []
}
</script>

<template>
  <div style="max-width: 420px">
    <div style="margin-bottom: 10px; display: flex; align-items: center; gap: 8px">
      <span style="font-size: 13px">父子不关联（checkStrictly）</span>
      <ElSwitch v-model="strict" />
    </div>
    <BizTree
      ref="treeRef"
      :data="data"
      checkable
      :check-strictly="strict"
      default-expand-all
      :height="260"
      @check="onCheck"
    />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      已勾选叶子节点：{{ checked.length ? checked.join('、') : '（暂无）' }}
    </p>
  </div>
</template>

显示代码

懒加载

暂无数据

展开节点时延迟 600ms 模拟接口返回子级

lazy + load 按需拉取子级（透传 el-tree），loading 控制首屏遮罩。

<script setup lang="ts">
/** 场景：异步组织架构——lazy + load 按需拉取子级，loading 遮罩演示首屏加载态 */
import { onMounted, ref } from 'vue'
import type { LoadFunction } from 'element-plus'
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeNodeData } from 'vue3-ep-biz-lib'

/** 本地全量数据，模拟接口按父级返回子级 */
const all: Record<string, BizTreeNodeData[]> = {
  root: [
    { id: 1, label: '总部' },
    { id: 2, label: '华南大区' },
  ],
  '1': [{ id: 11, label: '研发中心', isLeaf: true }, { id: 12, label: '产品中心', isLeaf: true }],
  '2': [{ id: 21, label: '深圳分公司', isLeaf: true }, { id: 22, label: '广州分公司', isLeaf: true }],
}

const loading = ref(true)

const load: LoadFunction = (node, resolve) => {
  setTimeout(() => {
    const key = node.level === 0 ? 'root' : String(node.data.id)
    resolve(all[key] ?? [])
  }, 600)
}

onMounted(() => {
  setTimeout(() => {
    loading.value = false
  }, 400)
})
</script>

<template>
  <div style="max-width: 360px">
    <BizTree :data="[]" lazy :load="load" :loading="loading" :height="280" />
    <p style="margin-top: 10px; font-size: 13px; color: #909399">
      展开节点时延迟 600ms 模拟接口返回子级
    </p>
  </div>
</template>

显示代码

自定义节点

运营管理

活动管理启用12 条

内容审核停用3 条

会员管理

会员列表启用230 条

等级规则启用

默认 slot 接管节点内容（图标 / 状态标签 / 计数），tree-props 重定义 label 字段。

<script setup lang="ts">
/** 场景：自定义节点——默认 slot 接管节点内容（图标 + 状态标签 + 计数），treeProps 重定义字段 */
import { Folder, FolderOpened } from '@element-plus/icons-vue'
import { ElIcon, ElTag } from 'element-plus'
import { BizTree } from 'vue3-ep-biz-lib'
import type { BizTreeNodeData } from 'vue3-ep-biz-lib'

interface MenuNode extends BizTreeNodeData {
  name: string
  status?: 'enabled' | 'disabled'
  count?: number
  children?: MenuNode[]
}

const data: MenuNode[] = [
  {
    name: '运营管理',
    children: [
      { name: '活动管理', status: 'enabled', count: 12 },
      { name: '内容审核', status: 'disabled', count: 3 },
    ],
  },
  {
    name: '会员管理',
    children: [
      { name: '会员列表', status: 'enabled', count: 230 },
      { name: '等级规则', status: 'enabled' },
    ],
  },
]
</script>

<template>
  <div style="max-width: 420px">
    <BizTree :data="data" :tree-props="{ label: 'name' }" default-expand-all :height="300">
      <template #default="{ data }">
        <span style="display: inline-flex; align-items: center; gap: 6px; min-width: 0">
          <ElIcon :size="15" style="color: var(--el-color-primary)">
            <FolderOpened v-if="(data as MenuNode).children?.length" />
            <Folder v-else />
          </ElIcon>
          <span style="overflow: hidden; text-overflow: ellipsis; white-space: nowrap">
            {{ (data as MenuNode).name }}
          </span>
          <ElTag
            v-if="(data as MenuNode).status"
            :type="(data as MenuNode).status === 'enabled' ? 'success' : 'info'"
            size="small"
            style="flex-shrink: 0"
          >
            {{ (data as MenuNode).status === 'enabled' ? '启用' : '停用' }}
          </ElTag>
          <span
            v-if="(data as MenuNode).count"
            style="margin-left: auto; font-size: 12px; color: var(--el-text-color-secondary)"
          >
            {{ (data as MenuNode).count }} 条
          </span>
        </span>
      </template>
    </BizTree>
  </div>
</template>

显示代码

Props

属性名	类型	默认值	说明
data	BizTreeNodeData[]	[]	树数据
tree-props	TreeOptionProps	—	字段映射（透传 el-tree props：label / children / disabled / isLeaf）
node-key	string	'id'	节点唯一键字段名，操作类方法（append / remove 等）依赖
searchable	boolean	false	顶部搜索框：输入即过滤，命中关键词高亮
filter-placeholder	string	'请输入关键字'	搜索占位文案
filter-method	(query, data) => boolean	—	自定义过滤方法（默认 label 包含匹配，不区分大小写）
checkable	boolean	false	复选形态（show-checkbox）
check-strictly	boolean	false	复选父子不关联
default-expand-all	boolean	false	默认展开全部（懒加载模式下仅展开已加载节点）
expand-level	number	1	展开层级（default-expand-all 为 false 时生效，懒加载模式无效）
lazy	boolean	false	懒加载模式（load 必传）
load	LoadFunction	—	懒加载函数（透传 el-tree load）
loading	boolean	false	加载中遮罩
highlight-current	boolean	true	高亮当前点击节点
expand-on-click-node	boolean	false	点击节点即展开 / 折叠
show-actions	boolean	false	节点 hover 显示操作按钮（事件外抛，数据变更由外部处理）
action-filter	(data, isLeaf) => BizTreeAction[]	—	按节点定制可见操作（返回空数组则该节点不显示；默认 add / edit / remove）
empty-text	string	'暂无数据'	空态文案
height	number | string	—	容器高度（超出滚动），如 360 / '100%'

Events

事件名	参数	说明
node-add	(data, node)	点击节点「新增子级」按钮
node-edit	(data, node)	点击节点「编辑」按钮
node-remove	(data, node)	点击节点「删除」按钮
node-click / node-expand / check / …	—	el-tree 原生事件透传（v-bind="$attrs" 落到内部 el-tree）

Slots

插槽名	说明
default	节点内容，作用域 { node, data }（不传时渲染 label + 搜索高亮 + 操作按钮）
search	搜索区整体替换，作用域 { query }
empty	空态整体替换

Expose

名称	类型	说明
getTree	() => TreeInstance	el-tree 实例（链式调用原生方法）
filter	(query: string) => void	外部触发关键字过滤
clearFilter	() => void	清空搜索
append	(data, parent) => void	在指定父节点（key 或节点）下追加子节点
remove	(node) => void	删除节点
getCheckedKeys	() => Array<string | number>	获取勾选节点 key 集合
getCheckedNodes	(leafOnly?: boolean) => BizTreeNodeData[]	获取勾选节点数据集合
setCheckedKeys	(keys) => void	设置勾选
setCurrentKey	(key) => void	设置当前高亮节点
getCurrentNode	() => BizTreeNodeData | undefined	获取当前高亮节点数据

TIP

需要 node-contextmenu、node-collapse 等更多 el-tree 能力时直接在组件上绑定即可（原生透传）；节点右键菜单可基于 node-contextmenu + ElDropdown 自行组合。