更新记录

1.1.4（2026-09-22） 下载此版本

优化图标样式

1.1.3（2026-09-21） 下载此版本

修复节点展开问题

1.1.2（2026-09-07） 下载此版本

修改说明

平台兼容性

uni-app(3.8.4)

lu-data-tree

uni-app 树形选择组件，支持单选、多选、父子级联、严格模式、节点禁用、懒加载、关键词筛选、默认展开及自定义节点插槽。

该组件基于 da-tree 树形选择 进行修改

特性

• 支持 Vue 2 和 Vue 3
• 支持单选和多选
• 支持父子节点联动及严格模式
• 支持半选状态
• 支持默认选中和默认展开
• 支持节点禁用
• 支持异步懒加载
• 支持关键词筛选
• 支持自定义节点内容
• 支持实例方法控制选中和展开状态
• 支持大数据量增量渲染

安装

将 lu-data-tree 放入项目的 uni_modules 目录，并确保项目中已安装 uni-icons。

组件支持 easycom，通常无需手动导入：

<lu-data-tree :data="treeData" />

基础用法

<template>
  <lu-data-tree
    :data="treeData"
    labelField="name"
    valueField="id"
    @change="handleChange"
    @expand="handleExpand"
  />
</template>

<script setup>
import { ref } from 'vue';

const treeData = ref([
  {
    id: '1',
    name: '一级节点',
    children: [
      { id: '1-1', name: '二级节点' }
    ]
  }
]);

function handleChange(keys, currentNode) {
  console.log(keys, currentNode);
}

function handleExpand(expanded, currentNode) {
  console.log(expanded, currentNode);
}
</script>

属性

选择模式

单选

默认关闭 showCheckbox，组件处于单选模式：

<lu-data-tree
  :data="treeData"
  defaultCheckedKeys="1-1"
  @change="handleChange"
/>

单选事件中的第一个参数为单个 key；取消选中时为 null。

多选

<lu-data-tree
  :data="treeData"
  showCheckbox
  :defaultCheckedKeys="['1-1']"
  @change="handleChange"
/>

默认情况下父子节点联动。选中父节点会联动选中可用子孙节点，子节点部分选中时父节点显示半选状态。

严格模式

开启 checkStrictly 后，默认父子联动关闭。此时每个节点只能处于未选中或选中状态，不会产生半选状态。需要联动时，可按需开启以下配置：

<lu-data-tree
  :data="treeData"
  showCheckbox
  checkStrictly
  autoCheckAllChildren
  autoUncheckAllChildren
  autoCheckAllParent
  autoUnCheckAllParent
/>

懒加载

<lu-data-tree
  :data="treeData"
  loadMode
  :loadApi="loadChildren"
/>

async function loadChildren(node) {
  const children = await fetchChildren(node.key);
  return children || [];
}

loadApi 接收处理后的当前节点。返回值应为子节点数组；没有子节点时返回 []。组件会根据 childrenField 合并并插入新节点。

筛选

<template>
  <input v-model="keyword" placeholder="请输入关键词" />
  <lu-data-tree :data="treeData" :filterValue="keyword" />
</template>

<script setup>
import { ref } from 'vue';

const keyword = ref('');
</script>

匹配节点及其祖先节点会显示。清空关键词后，组件会恢复筛选前的展开状态。

懒加载模式下，筛选范围仅包含已经加载到组件中的节点。

事件

currentNode 为组件处理后的内部节点，其中 originItem 保存原始数据节点。

实例方法

通过 ref 获取组件实例：

<lu-data-tree ref="treeRef" :data="treeData" showCheckbox />

const treeRef = ref(null);

treeRef.value?.setCheckedKeys(['1-1'], true);
treeRef.value?.setExpandedKeys(['1'], true);

const checkedKeys = treeRef.value?.getCheckedKeys();
const expandedKeys = treeRef.value?.getExpandedKeys();

自定义节点内容

组件提供默认插槽，插槽参数如下：

• node：组件处理后的内部节点
• data：原始数据节点

<lu-data-tree :data="treeData">
  <template #default="{ node, data }">
    <view class="custom-node">
      <text>{{ node.label }}</text>
      <text v-if="data.description">{{ data.description }}</text>
    </view>
  </template>
</lu-data-tree>

## 空状态插槽

组件提供两个空状态插槽，插槽内容均完全由调用方控制，不会自动附加组件空状态样式：

- `empty`：传入的树形数据为空时使用
- `search-empty`：搜索完成且没有匹配节点时使用

未提供插槽时，分别显示“暂无数据”和“未匹配到数据”。

```vue
<lu-data-tree :data="treeData" :filterValue="filterValue">
  <template #empty>
    <view class="custom-empty">暂无组织数据</view>
  </template>
  <template #search-empty>
    <view class="custom-search-empty">没有找到相关节点</view>
  </template>
</lu-data-tree>

节点数据结构

默认字段结构如下：

[
  {
    value: '1',
    label: '一级节点',
    disabled: false,
    leaf: false,
    children: [
      {
        value: '1-1',
        label: '二级节点'
      }
    ]
  }
]

使用自定义字段时：

<lu-data-tree
  :data="treeData"
  labelField="name"
  valueField="id"
  childrenField="nodes"
/>

valueField 对应的值必须在整棵树中唯一，否则节点选中、展开和实例查询可能产生冲突。

注意事项

1. 组件依赖 uni-icons。
2. loadMode 必须同时传入有效的 loadApi 函数。
3. loadApi 应返回数组；无子节点时返回 []。
4. onlyRadioLeaf 与懒加载组合时无法判断尚未加载节点是否为叶子节点。
5. 父容器应设置明确高度，否则 scroll-view 的百分比高度可能无法正常显示。
6. 当前组件适用于普通 uni-app Vue2/Vue3 项目，不适用于 uni-app x。
7. 组件声明支持的平台以 package.json 为准。