更新记录

1.0.1(2026-11-22) 下载此版本

  • 新增 change 事件:单选模式下选中节点、多选模式下勾选状态变化时触发,参数与 v-model 绑定值一致(单选为节点原始 key,多选为完全勾选的 key 数组,不含半选态)

1.0.0(2026-11-22) 下载此版本

  • 新增 tree-view 树形组件,基于 list-view 虚拟列表实现,大数据量下只渲染可见行
  • 目前仅在 App-Android 端测试通过,其他平台待验证

数据与配置

  • 支持 v-model 绑定选中值(单选为 key,多选为 keys 数组),对外输出还原节点原始 key 类型(数字 id 输出仍是数字)
  • 支持自定义节点字段映射(treeProps):key / label / children / disabled 均支持字符串属性名或函数两种写法
  • 支持节点禁用(disabled)与「只能选中子节点」策略(selectableType="leaf",父节点点击文本切换展开/收起)
  • 支持 defaultExpandAll / defaultExpandLevel 控制默认展开,expandedKeys 受控同步
  • 支持主题色(themeColor)、加载态(loading)、行高(rowHeight)、缩进(indentWidth)、空态文案(emptyText)

交互

  • 支持展开/收起、单选高亮、复选框多选与半选态
  • 勾选父节点级联勾选全部后代,取消同理;级联时自动跳过禁用的后代,禁用子节点不参与父节点全选/半选推导
  • 支持搜索定位与关键字高亮:大小写不敏感,命中节点及祖先链自动展开,未命中分支整体裁剪

事件

  • 新增 node-click / check / expand / update:modelValue 事件,参数包含完整层级路径与父级信息(path / pathLabels / pathKeys / parentKey / parentKeys / parentLabel / parentPath / parentNode)

组件方法

  • 新增 ref 调用方法:setLoading / isLoading / expandAll / collapseAll / getCheckedKeys / getCheckedNodes / getIndeterminateKeys / getIndeterminateNodes / getSelectedKey / getSelectedNode

样式

  • 新增外部样式类:node-class(节点行)、label-class(节点文本)、search-class(搜索栏)

平台兼容性

uni-app x(4.87)

Chrome Safari Android Android插件版本 iOS 鸿蒙 微信小程序
- - 5.0 1.0.0 - - -

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

tree-view 树形视图

通用树形组件,支持展开/收起、单选高亮、复选框多选与半选态、搜索定位、节点禁用、主题色与加载态。

基于 list-view 虚拟列表实现,大数据量下只渲染可见行。

使用方式

<template>
    <!-- 单选 -->
    <tree-view :data="treeData" v-model="selectedKey" @node-click="onNodeClick" />

    <!-- 多选 -->
    <tree-view :data="treeData" v-model="checkedKeys" checkable @check="onCheck" />
</template>

<script setup lang="ts">
    const treeData = ref([
        {
            id: '1',
            label: '总部',
            children: [
                { id: '1-1', label: '技术中心', children: [] },
                { id: '1-2', label: '运营中心', children: [], disabled: true }
            ]
        }
    ])

    const selectedKey = ref(null)
    const checkedKeys = ref([])
</script>

Props

名称 说明 类型 默认值
data 树数据,节点默认结构 { id, label, children: [], disabled: false } Array []
v-model 选中值。单选为节点 key(字符串/数字/null),多选为 key 数组。内部统一用字符串比对,对外输出时还原成节点原始 key 类型(如数字 id 输出仍是数字) String / Number / Array null
treeProps 节点字段映射,支持字段名与函数两种写法:{ key, label, children, disabled },四个字段默认为 id / label / children / disabled Object {}
checkable 是否显示复选框(多选模式) Boolean false
selectableType 节点可选策略。all 全部可选;leaf 只能选中子节点(叶子),父节点不可勾选、不可选中,但箭头展开仍可用,点击父节点文本切换展开/收起 String all
searchable 是否显示搜索框 Boolean false
expandedKeys 已展开的节点 key 列表(受控)。传入即作为初始展开状态,父组件后续修改该值会同步到组件内部 Array []
defaultExpandAll 是否默认展开全部节点。首次加载及树数据异步加载完成后均会生效;与 defaultExpandLevel 同时存在时以后者的层级限制为准 Boolean false
defaultExpandLevel 默认展开的层级上限。0 表示不限制,1 只展开第一层,2 展开前两层 Number 0
loading 是否处于加载中,加载时隐藏列表与搜索框,显示加载指示器。也可通过 ref 方法 setLoading 控制 Boolean false
loadingText 加载中提示文案 String 加载中...
themeColor 主题色,支持 #RRGGBB 与 #RGB 两种写法。影响复选框选中态底色与边框、单选选中行背景、搜索命中文字高亮、搜索清除按钮;非十六进制颜色时选中行背景回退为默认浅色 String #3A7AFE
indentWidth 每级缩进像素 Number 18
rowHeight 行高像素 Number 44
emptyText 空数据提示文案 String 暂无数据
nodeClass 节点行的自定义样式类(外部样式类) string ''
labelClass 节点文本的自定义样式类(外部样式类) string ''
searchClass 搜索栏的自定义样式类(外部样式类) string ''

treeProps 字段映射

每个字段都支持字符串(属性名)或函数两种写法:

const treeProps = {
    key: 'code',
    children: 'subs',
    disabled: (node) => node.locked === true,
    label: (node) => node.title + ' [' + node.code + ']'
}

Events

名称 说明 参数
node-click 单选模式下点击了节点文本 { key, label, node, level, path, pathLabels, pathKeys, parentKey, parentKeys, parentLabel, parentPath, parentNode }
check 多选模式下勾选状态变化 { key, label, checked, checkedKeys, level, path, ... },checkedKeys 为完全勾选的 key 列表,不含半选态节点
expand 展开状态变化。点击箭头或调用 expandAll / collapseAll 方法触发;后者仅返回 { key, expanded, expandedKeys }(key 为空串),不含路径与父级信息 { key, expanded, expandedKeys, level, path, ... }
change 选中值变化。单选模式下选中节点、多选模式下勾选状态变化时触发 单选为节点原始 key,多选为完全勾选的 key 数组(不含半选态)

level 为节点所在层级,根节点为 1,子节点依次递增。 多选模式下点击节点文本为展开/收起,不会选中,也不会触发 node-click。 selectableType="leaf" 时点击父节点文本同样为切换展开/收起,不触发 node-click。 禁用(disabled)节点点击无响应。 change 事件与 v-model 绑定值一致;使用 v-model 时无需再监听 change。

勾选与级联规则

  • 勾选父节点会连带勾选其全部后代,取消勾选同理。
  • 禁用节点不可勾选,级联勾选时会自动跳过禁用的后代。
  • 禁用子节点不参与父节点全选/半选状态的推导,避免父节点因存在永远勾不上的子节点而停在半选态。
  • 半选态 = 节点自身未勾选,但存在被勾选的后代。v-model、check 事件与 getCheckedKeys() 的输出均只含完全勾选节点,半选态通过 getIndeterminateKeys() / getIndeterminateNodes() 获取。
  • 点击半选态节点的复选框视为「勾选」。

搜索

  • searchable 开启后显示搜索框与「清除」按钮,按 label 包含匹配,大小写不敏感。
  • 命中节点及其祖先链保留并自动展开,未命中的分支会被整体裁剪。
  • 命中关键字以主题色加粗高亮。

组件方法(通过 ref 调用)

方法 说明 返回
setLoading(visible) 设置加载状态 -
isLoading() 查询当前加载状态 Boolean
expandAll() 展开全部 -
collapseAll() 收起全部 -
getCheckedKeys() 获取已勾选节点 key(完全勾选,不含半选态) Array
getCheckedNodes() 获取已勾选节点完整信息 Array
getIndeterminateKeys() 获取半选节点 key Array
getIndeterminateNodes() 获取半选节点完整信息 Array
getSelectedKey() 获取当前选中节点 key,未选中时为空串 String
getSelectedNode() 获取当前选中节点完整信息 Object / null
<tree-view ref="treeRef" :data="treeData" />
const treeRef = ref(null)
const half = treeRef.value?.getIndeterminateKeys()

节点信息结构

事件参数与查询方法返回的节点信息结构一致:

{
    key: '1-1-1',        // 节点 id
    label: '前端组',      // 节点文本
    node: { ... },       // 原始节点对象
    level: 3,            // 所在层级,根节点为 1
    path: '总部 / 技术中心 / 前端组',          // 完整层级路径
    pathLabels: ['总部', '技术中心', '前端组'],  // 逐级文本
    pathKeys: ['1', '1-1', '1-1-1'],           // 逐级 id
    parentKey: '1-1',     // 直接父级 id
    parentKeys: ['1', '1-1'],
    parentLabel: '技术中心',
    parentPath: '总部 / 技术中心',
    parentNode: { ... }   // 直接父级原始节点
}

根节点的 parentKey、parentLabel、parentPath 为空串,parentNode 为 null。

外部样式类

组件通过 defineOptions({ externalClasses }) 开放了以下样式类,可直接在组件上使用:

<tree-view class="my-tree" node-class="my-node" label-class="my-label" search-class="my-search" />
外部样式类 作用位置
node-class 节点行
label-class 节点文本
search-class 搜索栏

平台支持

目前仅在 App-Android 端测试通过,其他平台(iOS / HarmonyOS / 小程序 / Web)待验证。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议

暂无用户评论。