更新记录
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)待验证。

收藏人数:
下载插件并导入HBuilder
下载示例项目ZIP
赞赏(0)
下载 381
赞赏 1
下载 12779436
赞赏 1960
赞赏
京公网安备:11010802035340号