xe-utils 树形数据神器:toArrayTree 如何让扁平列表秒变树结构

原创2026-11-04 10:41:371,975 阅读
文章标签:前端工具包

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 中的树结构章节。

常见问题与避坑指南 ⚠️

  1. 主键重复:数组中出现重复 id 时会在控制台输出 Duplicate primary key 警告,先 uniq 去重再转换更稳妥。
  2. 无限循环保护:某节点 id === parentId 时,函数会自动将其 parentId 置空并告警,避免死循环(见 src/toArrayTree.js)。
  3. 根节点判定:非严格模式下,parentId 找不到对应父节点的数据会被当作根节点;严格模式下只有 parentId 为空(null)的才算根。
  4. 想控制根? 用 rootValues 显式指定根 id 列表,或 rootParentValue 指定"顶级父键值",优先级最高。

单元测试覆盖了以上各种边界情况,可参考 test/array.test.js。

安装与引用

npm install xe-utils

引入后即可使用:

import XEUtils from 'xe-utils'

小结

toArrayTree 用一行代码解决了"扁平列表转树结构"这一前端高频痛点:默认配置开箱即用,排序、严格模式、字段分离等进阶能力一应俱全,再配合 toTreeArray 与 findTree、eachTree 等树操作函数,xe-utils 让树形数据的处理变得简单又高效。快去试试它吧!🎉

登录后查看全文
xe-utils