react-ui-tree树形数据结构深度解析:children、collapsed、leaf三个关键字段完全指南
react-ui-tree树形数据结构深度解析:children、collapsed、leaf三个关键字段完全指南
react-ui-tree 是一个功能强大的 React 树形组件(tree component),原生支持拖拽(drag & drop)交互。它的渲染完全依赖你传入的一个树形 JSON 对象,而这个对象中有三个硬编码的关键字段:children(子节点)、collapsed(折叠状态) 和 leaf(叶子标记)。本文通过源码级解读,带你一次性彻底搞懂这三个字段的含义、作用与配合方式,让你快速上手搭建自己的 React 树形界面 🌲
一、先认识整体:一棵树长什么样?
react-ui-tree 的内部结构由 js-tree。
以官方示例数据为例(完整数据见 example/tree.js),简化后结构如下:
{
"module": "react-ui-tree",
"children": [
{
"module": "dist",
"collapsed": true,
"children": [
{ "module": "node.js", "leaf": true }
]
},
{ "module": "LICENSE", "leaf": true }
]
}
💡 注意:
module这类字段是自定义的,想写什么写什么;而children、collapsed、leaf是组件硬编码识别的保留字段,不能改名。
三个字段的角色可以用一张表快速速览:
| 字段 | 类型 | 作用一句话总结 |
|---|---|---|
children |
数组 | 决定节点是否为"目录",有子节点才会出现折叠箭头并渲染子层 |
collapsed |
布尔 | 控制该节点是否折叠,折叠后子节点不渲染、不占位 |
leaf |
布尔 | 标记叶子节点,是"不可再放入子节点"的提示,主要影响拖拽行为 |
二、children 字段:树的分叉点
2.1 只有 children 才显示折叠箭头
节点的折叠/展开箭头并不是每个节点都有的。在 lib/node.js 的 renderCollapse 方法中,判断条件非常直接:
if (index.children && index.children.length) {
// 渲染 caret-right(右箭头)或 caret-down(下箭头)
}
也就是说:只要 children 存在且数组非空,节点前才会出现小箭头。没有 children 的节点就是"末端节点",不显示任何箭头。
2.2 children 如何驱动子层渲染
子节点的递归渲染发生在 renderChildren 方法中,见 lib/node.js:它遍历 index.children,为每个子节点递归创建 UITreeNode 组件,并通过 paddingLeft(默认 20px)逐层缩进,形成我们熟悉的层级树状视觉。
📌 提示:
children里的每个元素仍然是完整的节点对象,同样可以携带collapsed和leaf,规则递归生效。
三、collapsed 字段:折叠与展开的开关
3.1 折叠时子节点完全不渲染
collapsed 是最"看得见效果"的字段。渲染逻辑见 lib/node.js:
{node.collapsed ? null : this.renderChildren()}
一行代码说清一切:collapsed 为 true 时,children 直接不渲染。节点前的小箭头也会从 caret-down(▼ 展开态)切换为 caret-right(▶ 折叠态),样式定义在 lib/react-ui-tree.css。
3.2 折叠还会影响内部坐标计算
react-ui-tree 会预先计算每个节点的 top / left 坐标,用于拖拽落点判断。这个布局算法在 lib/tree.js 的 updateNodesPosition 中:父节点 collapsed 为 true 时,其所有子孙的 top/left 被置为 null(即从可视布局中"消失"),父节点高度记为 1。单元测试中的数据与预期可参考 tests/tree.js。
3.3 折叠状态的切换与回调
点击箭头时,组件会翻转 node.collapsed 并重新布局,见 lib/react-ui-tree.js 的 toggleCollapse 方法;翻转后还会触发 onChange(tree) 回调,把最新树对象同步给你的 state,实现"UI 状态 → 数据状态"的双向闭环。
四、leaf 字段:给拖拽引擎看的"身份标签"
leaf 是最容易被忽略的字段——它不参与渲染(没有箭头、不影响缩进),而是专门服务于拖拽逻辑。
核心判断在 lib/react-ui-tree.js 的拖拽处理中:当你把一个节点拖到右侧、准备嵌入另一个节点内部时,目标节点必须同时满足两个条件:
if (!prevNode.collapsed && !prevNode.leaf) {
newIndex = tree.move(index.id, index.prev, 'append');
}
翻译成人话:
- ✅ 目标节点未折叠(
collapsed为 falsy) - ✅ 目标节点不是叶子(
leaf为 falsy)
两个条件都满足,才允许把节点"塞进去"(append)。同样的保护逻辑也出现在向下拖拽嵌入的判断中,见 lib/react-ui-tree.js:目标节点必须有非空的 children 且未折叠,才允许 prepend 插入。
⚠️ 实际效果:把
leaf: true标注在文件类节点上,拖拽时其他节点就无法被塞进"文件"里,只有"目录"类节点可以接收子节点——这正是示例数据里文件都标leaf: true的原因,可对照 example/tree.js 观察。
五、三个字段组合实战:一份正确的树数据怎么写?
结合前面的分析,编写 react-ui-tree 数据时有三条经验法则:
- 目录节点:写
children数组 + 可选collapsed,例如example目录在 example/tree.js 中默认展开。 - 文件节点:标上
leaf: true,不需要children,拖拽引擎会自动阻止往里面塞节点。 - 不想让用户看到深层内容:给目录加
collapsed: true(如dist目录,见 example/tree.js)。
组件的 Props 类型定义见 index.d.ts,最小配置只需 tree + renderNode,onChange 用于接收拖拽/折叠后的新树:
<Tree
paddingLeft={20}
tree={this.state.tree}
onChange={this.handleChange}
renderNode={this.renderNode}
/>
一个完整的可运行示例在 example/app.js,右侧面板还实时打印了树的 JSON,非常适合调试观察 collapsed 翻转后的数据变化。
六、常见疑问快答
leaf: true的节点为什么没有箭头? 箭头由children决定,与leaf无关;leaf 只是拖拽用的标记。collapsed: true会丢失子节点吗? 不会。数据里children始终保留,只是 UI 不渲染,展开即恢复。children为空数组[]时? 视为无子节点(children.length为 0),不显示箭头,行为等同叶子节点。- 拖拽后数据会怎么变? 组件内部通过 lib/tree.js 的
move方法重排树结构并重新计算坐标,最后经onChange把整棵新树交还给你。
七、总结
掌握 children、collapsed、leaf 三个字段的分工,就掌握了 react-ui-tree 数据层的全部奥秘:
| 字段 | 一句话记忆 |
|---|---|
children |
有没有它,决定"是不是目录" |
collapsed |
它管"看不看得見" |
leaf |
它管"能不能往里塞" |
核心源码索引:渲染逻辑 lib/node.js、拖拽与折叠 lib/react-ui-tree.js、布局与移动 lib/tree.js、示例数据 example/tree.js。按这套规则组织你的 JSON,就能轻松构建带拖拽能力的 React 树形组件,快去试试吧 🚀