xe-utils 树形数据神器:toArrayTree 如何让扁平列表秒变树结构
xe-utils 树形数据神器:toArrayTree 如何让扁平列表秒变树结构
xe-utils 是一个轻量级、无依赖的 JS 函数库/工具类,其中的 toArrayTree 函数是处理树形数据的利器:只需一行代码,就能把带 id/parentId 关联的扁平列表秒变树结构,帮你告别手写递归拼接 children 的繁琐代码,广泛用于权限菜单、分类目录、组织架构、评论楼层等场景。
为什么需要树形数据转换?
后端接口返回的数据通常是扁平的列表,比如部门数据:
let list = [
{ id: 1, name: '总公司' },
{ id: 2, parentId: 1, name: '研发部' },
{ id: 3, parentId: 1, name: '市场部' },
{ id: 4, parentId: 2, name: '前端组' }
]
但前端组件(树形选择器、菜单、目录树)需要的是嵌套结构。手写转换往往要循环 2~3 遍、还要处理排序和循环依赖,代码量大且容易出 bug。
xe-utils 的 toArrayTree 把这件事封装成了高性能的一行调用,核心实现见 src/toArrayTree.js。
30 秒上手:一行代码搞定
XEUtils.toArrayTree(list)
/*
[
{
id: 1, name: '总公司',
children: [
{ id: 2, parentId: 1, name: '研发部',
children: [ { id: 4, parentId: 2, name: '前端组', children: [] } ] },
{ id: 3, parentId: 1, name: '市场部', children: [] }
]
}
]
*/
默认配置约定俗成,主键为 id、父键为 parentId、子节点挂在 children 字段,定义在 src/setupDefaults.js 的 treeOptions 中。如果你的字段名一致,一个参数都不用传。
常用配置选项一览 📋
XEUtils.toArrayTree(array, options) 的完整参数如下(默认值来自 src/toArrayTree.d.ts):
| 属性 | 描述 | 默认值 |
|---|---|---|
key |
主键字段名 | id |
parentKey |
关联父主键字段名 | parentId |
children |
树层级后的子节点字段名 | children |
strict |
严格模式:丢弃关联不存在的节点,空子级不保留 children 字段 |
false |
sortKey |
节点排序字段(升序) | — |
rootValues |
显式指定哪些 id 是根节点(优先级最高) | — |
rootParentValue |
指定 parentKey 等于何值时算根节点 |
— |
data |
把原始行数据单独存到指定字段,节点只保留结构字段 | — |
mapChildren |
额外映射一份子节点到指定字段 | — |
💡 更多完整示例见官方 API 文档:API.md
4 个高频场景实战
场景 1:按字段排序再组树
菜单、分类通常需要固定顺序,传入 sortKey 即可:
XEUtils.toArrayTree(list, { sortKey: 'seq' })
场景 2:严格模式,自动过滤脏数据
当某些节点的 parentId 指向不存在的数据(孤儿节点)时,strict: true 会自动丢弃这类无效关联,并在子节点为空时移除 children 字段:
XEUtils.toArrayTree(list, { strict: true })
场景 3:结构字段与业务数据分离
用 data 选项,树节点只保留 id/parentId/children,原始行数据整体存入 data 字段,便于做表单绑定:
XEUtils.toArrayTree(list, { data: 'data' })
// { data: { id: 1, name: '总公司', ... }, id: 1, children: [...] }
场景 4:自定义字段名
字段不叫 id/parentId?直接覆盖:
XEUtils.toArrayTree(list, { key: 'uid', parentKey: 'pid', children: 'childs' })
反向操作:toTreeArray 一键还原
如果拿到的是树结构、需要转回扁平列表,用它的姊妹函数 toTreeArray(实现见 src/toTreeArray.js):
XEUtils.toTreeArray(treeList)
// [{ id: 1, ... }, { id: 2, parentId: 1, ... }, { id: 4, parentId: 2, ... }]
两个函数配合,扁平列表 ⇄ 树结构随心切换,还支持 clear: true 在转换时顺手清掉 children 字段。
与树遍历函数组合,威力翻倍 🚀
组好树之后,xe-utils 还提供了一整套树操作函数,可以无缝衔接:
findTree:从树中查找第一个匹配的节点eachTree/mapTree:遍历 / 映射树的每个节点searchTree:批量搜索符合条件的节点filterTree:按条件过滤树
let node = XEUtils.findTree(tree, item => item.id === 4)
详见 API.md 中的树结构章节。
常见问题与避坑指南 ⚠️
- 主键重复:数组中出现重复
id时会在控制台输出Duplicate primary key警告,先uniq去重再转换更稳妥。 - 无限循环保护:某节点
id === parentId时,函数会自动将其parentId置空并告警,避免死循环(见 src/toArrayTree.js)。 - 根节点判定:非严格模式下,
parentId找不到对应父节点的数据会被当作根节点;严格模式下只有parentId为空(null)的才算根。 - 想控制根? 用
rootValues显式指定根 id 列表,或rootParentValue指定"顶级父键值",优先级最高。
单元测试覆盖了以上各种边界情况,可参考 test/array.test.js。
安装与引用
npm install xe-utils
引入后即可使用:
import XEUtils from 'xe-utils'
小结
toArrayTree 用一行代码解决了"扁平列表转树结构"这一前端高频痛点:默认配置开箱即用,排序、严格模式、字段分离等进阶能力一应俱全,再配合 toTreeArray 与 findTree、eachTree 等树操作函数,xe-utils 让树形数据的处理变得简单又高效。快去试试它吧!🎉