VmoTree 使用指南

VmoTree 是一个用于简化树形结构数据操作的 JavaScript 类库。它为树的构建、查询、转换和操作提供了丰富的功能。

安装

npm install vmo-tree

快速开始

引入 VmoTree

import { VmoTree } from './VmoTree'

基本用法示例

以下示例展示了 VmoTree 的基本使用，包括数组转化为树、树转化为数组、查找节点和路径等功能。

将数组转换为树

const flatArray = [
  { id: 1, name: 'Root', parentId: null },
  { id: 2, name: 'Child 1', parentId: 1 },
  { id: 3, name: 'Child 2', parentId: 1 },
  { id: 4, name: 'Grandchild 1', parentId: 2 }
]

const tree = VmoTree.array2Tree(flatArray, 'id', 'parentId', 'children')
console.log(tree)

将树转换为数组

const flat = VmoTree.flatten2Array(tree, 'id', 'parentId', 'children')
console.log(flat)

查找节点

// 使用条件函数查找第一个匹配的节点
const node = VmoTree.find(node => node.name === 'Child 1', tree, 'children')
console.log(node)

// 使用节点对象查找
const node2 = VmoTree.find({ id: 2 }, tree, 'children')
console.log(node2)

获取节点路径

// 找出节点到根节点的路径
const path = VmoTree.path(node => node.name === 'Grandchild 1', tree, 'children')
console.log(path)

过滤树

// 过滤出名字中包含 "Child" 的节点
const filteredTree = VmoTree.filter(node => node.name.includes('Child'), tree, 'children', false)
console.log(filteredTree)

映射树

// 在树上应用映射函数
const mappedTree = VmoTree.map(node => ({ ...node, name: `${node.name} (mapped)` }), tree, 'children')
console.log(mappedTree)

静态方法

• VmoTree.array2Tree(array, nodeKey, parentKey, childrenKey,keepOrphansAsRoot): 把平展的数组变为树结构。

  • array: 需要转化的数组。
  • nodeKey: 节点主键
  • parentKey: 父节点主键
  • childrenKey: 子节点主键
  • keepOrphansAsRoot: 孤儿节点是否保留为根节点 defalut:false

• VmoTree.flatten2Array(tree, nodeKey, parentKey, childrenKey): 将树形结构展平特定数组。

  • tree: 需要转化的目标树。
  • nodeKey: 节点主键
  • parentKey: 父节点主键
  • childrenKey: 子节点主键

• VmoTree.path(predicate, targetTree, childrenKey, pickFirst): 获取给定节点到根节点的路径。

  • predicate: 目标节点指针或比对函数。
  • targetTree: 查找树
  • childrenKey: 子节点键名
  • pickFirst: 仅匹配首个结果

• VmoTree.filter(predicate, targetTree, childrenKey, prioritizeChildren): 过滤树节点。

  • predicate: 目标节点指针或比对函数。
  • targetTree: 查找树
  • childrenKey: 子节点键名
  • prioritizeChildren: 默认 true 子节点优先会先处理子节点情况，然后再将处理结果合并到父节点访问器中一并判断，false，则会优先处理父节点判定，再进行子节点处理

• VmoTree.map(visit, targetTree, childrenKey, prioritizeChildren): 映射节点。

  • visit: 访问器
  • targetTree: 遍历范围
  • childrenKey: 子节点键名
  • prioritizeChildren: 默认 true 子节点优先会先处理子节点情况，然后再将处理结果合并到父节点访问器中一并判断，false，则会优先处理父节点判定，再进行子节点

• VmoTree.find(targetNode, targetTree, childrenKey, pickFirst): 查找树节点。

  • visit: 条件函数，或者也可以给出目标节点的部分属性，方法会自动完成比对，属性给出越多越精准
  • targetTree: 子节点键名
  • childrenKey: 子节点键名
  • pickFirst:仅匹配首个结果

实例方法

实例方法是非静态的，需要在特定的 VmoTree 实例上调用。示例如下：

const vmoTreeInstance = new VmoTree(flatArray, { nodeKey: 'id', parentKey: 'parentId', childrenKey: 'children' })

find(target, option?)

• target: 条件函数，或节点比对数据，同静态方法。
• option: 可选对象，支持以下属性：
  • childrenKey：指定子节点的键名(本次操作)。
  • pickFirst：布尔值，是否只寻找第一个匹配的节点(本次操作)。

map(visit, option?)

• visit: 映射函数，接收并返回一个节点对象。
• option: 可选对象，支持以下属性：
  • nodeKey: 节点主键
  • parentKey: 父节点主键
  • childrenKey：指定子节点的键名 (本次操作)。
  • prioritizeChildren：子节点是否优先,如子节点优先，则父节点映射处理时，其子节点已先行被映射处理完毕 默认 true。

filter(predicate, option?)

• predicate: 用于确定节点是否应包含在返回的树中的函数。
• option: 可选对象，支持以下属性：
  • childrenKey：指定子节点的键名 (本次操作)。
  • prioritizeChildren：子节点是否优先,如子节点优先，则父节点过滤判定时，其子节点已先行被过滤判定完毕 默认 true。

path(targetNode, option?)

• targetNode: 条件函数，或节点比对数据。
• option: 可选对象，包含以下属性：
  • childrenKey：指定子节点的键名。
  • pickFirst：布尔值，是否只寻找第一个匹配的节点的路径(本次操作)。

flatten(option?)

• option: 可选对象，用于指定树展平到数组时的相关配置。
  • nodeKey: 节点主键(本次操作)
  • parentKey: 父节点主键(本次操作)
  • childrenKey: 子节点主键(本次操作)

配置树

设置和获取树配置

你可以通过 setConfig 和 getConfig 方法来自定义节点的关键属性。

// 设置树的配置
vmoTreeInstance.setConfig({ nodeKey: 'customId', parentKey: 'customParentId', childrenKey: 'customChildren' })

// 获取当前树的配置
const config = vmoTreeInstance.getConfig()
console.log(config)

注意事项

• 因为支持 prioritizeChildren 子节点优先，map, filter 处理非常深的树可能会导致性能问题 。
• 确保输入的数据结构符合期望的格式，以避免不可预见的错误。

通过上面的指南，你可以灵活地操作复杂的树形数据。希望此文档能帮助你快速上手 VmoTree 库！