react-ui-tree树形数据结构深度解析:children、collapsed、leaf三个关键字段完全指南

原创2026-10-28 22:11:461,447 阅读

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 数据时有三条经验法则:

  1. 目录节点:写 children 数组 + 可选 collapsed,例如 example 目录在 example/tree.js 中默认展开。
  2. 文件节点:标上 leaf: true,不需要 children,拖拽引擎会自动阻止往里面塞节点。
  3. 不想让用户看到深层内容:给目录加 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 树形组件,快去试试吧 🚀

登录后查看全文
react-ui-tree