dlsjs 0.1.26 → 1.0.3

package/src/ES/Tree.js

@@ -0,0 +1,916 @@
+import {uniqBy} from "ramda";
+
+/**
+ * 列表转树（高性能版，适配100W+数据）
+ * 时间复杂度O(n)：n 是 list 的长度（输入数据量）
+ * 不改变原数组指针，生成的children也会注入原数组
+ *
+ * @param {Array} list - 原始列表数据
+ * @param {Object} extendProps - 自定义属性映射 {id: 'id', children: 'children', parentId: 'parentId'}
+ * @returns {Array} 树形结构数据
+ */
+export function list2Tree (list, extendProps = {}) {
+    // 1. 配置默认属性映射，兼容自定义字段
+    const props = {
+        id: 'id',
+        children: 'children',
+        parentId: 'parentId',
+        useConcat: false, // 保留原有配置，实际优化后无需concat
+        ...extendProps
+    };
+
+    // 校验数据结构
+    if(list && list[0] && !list[0].hasOwnProperty(props.id)) {
+        console.warn('数据非标准，未找到唯一标识字段，直接返回')
+        return list
+    }
+
+    const { id: idKey, children: childrenKey, parentId: parentIdKey, useConcat } = props;
+
+    // -1.先清空children。防止重复叠加调用。
+    if(useConcat === false) {
+        for (const node of list) {
+            delete node[childrenKey];
+        }
+    }
+
+    // 2. 构建ID到节点的哈希映射（O(n)），同时初始化children数组
+    const nodeMap = new Map();
+    const rootNodes = []; // 存储根节点（parentId为空/0/不存在的节点）
+
+    // 第一次遍历：初始化映射和children，O(n)
+    for (const node of list) {
+        const nodeId = node[idKey];
+        // 初始化children数组（避免后续判断undefined）
+        if (!node[childrenKey]) {
+            node[childrenKey] = [];
+        }
+        // 将节点存入Map，方便后续快速查找父节点
+        nodeMap.set(nodeId, node);
+    }
+
+    // 第二次遍历：关联父子节点，O(n)
+    for (const node of list) {
+        const parentId = node[parentIdKey];
+        const parentNode = nodeMap.get(parentId);
+
+        if (parentNode) {
+            // 有父节点：添加到父节点的children中
+            if (useConcat && Array.isArray(parentNode[childrenKey])) {
+                parentNode[childrenKey] = parentNode[childrenKey].concat(node);
+            } else {
+                parentNode[childrenKey].push(node);
+            }
+        } else {
+            // 无父节点：归为根节点（parentId为空/0/不存在）
+            rootNodes.push(node);
+        }
+    }
+
+    // 3. 清理空children（可选，保持和原逻辑一致）
+    for (const node of list) {
+        if (Array.isArray(node[childrenKey]) && node[childrenKey].length === 0) {
+            delete node[childrenKey];
+        }
+    }
+
+    return rootNodes;
+}
+
+/**
+ * 为list添加_parentIds属性，属性为不含自身的数组，顺序从最外层开始
+ * 该函数将遍历列表中的每个节点，并为其添加一个_parentIds属性，
+ * 该属性包含从根节点到当前节点父节点的完整路径（不包括自身）
+ * 时间复杂度O(n)：n 是 list 的长度（输入数据量）
+ *
+ * @param {Array} list - 包含树节点的平铺数组，每个节点应具有id和parentId属性
+ *
+ * @example
+ * const list = [
+ *   { id: '1', name: 'Root' },
+ *   { id: '2', name: 'Child1', parentId: '1' },
+ *   { id: '3', name: 'GrandChild1', parentId: '2' }
+ * ];
+ *
+ * setParentIds4List(list);
+ * // 结果:
+ * // list[0] = { id: '1', name: 'Root', _parentIds: [] }
+ * // list[1] = { id: '2', name: 'Child1', parentId: '1', _parentIds: ['1'] }
+ * // list[2] = { id: '3', name: 'GrandChild1', parentId: '2', _parentIds: ['1', '2'] }
+ *
+ * @returns {Array} list - 直接返回入参数组，指针不变
+ */
+export function setParentIds4List(list) {
+    if (!list || list.length === 0) return;
+
+    // 创建ID到节点的映射表
+    const nodeMap = new Map();
+    for (const node of list) {
+        nodeMap.set(node.id, node);
+        node._parentIds = []; // 初始化_parentIds
+    }
+
+    // 计算每个节点的_parentIds，使用记忆化避免重复计算
+    function calculateParentIds(node) {
+        if (node._parentIds.length > 0 || !node.parentId) {
+            // 如果已经计算过或者没有父节点，直接返回
+            return node._parentIds;
+        }
+
+        const parentNode = nodeMap.get(node.parentId);
+        if (!parentNode) {
+            // 父节点不存在，清空_parentIds
+            node._parentIds = [];
+            return node._parentIds;
+        }
+
+        // 先确保父节点的_parentIds已经计算完成
+        const parentParentIds = calculateParentIds(parentNode);
+
+        // 当前节点的_parentIds = 父节点的_parentIds + 父节点ID
+        node._parentIds = [...parentParentIds, node.parentId];
+
+        return node._parentIds;
+    }
+
+    // 遍历所有节点，计算_parentIds
+    for (const node of list) {
+        if (node._parentIds.length === 0) { // 只对未计算过的节点进行计算
+            calculateParentIds(node);
+        }
+    }
+    return list
+}
+
+/**
+ * 查找树上的点
+ * 在树形结构中查找满足指定条件的第一个节点
+ * 时间复杂度O(n)：n 是 treeLike 的节点总数（输入数据量）
+ *
+ * @param {Array|Object|null|undefined} treeLike - 待处理的树形结构数据，可以是数组、单个对象或null/undefined
+ * @param {Function} func - 判断函数，接收节点作为参数，返回true表示匹配
+ * @returns {Object|null} 找到的第一个匹配节点，未找到则返回null
+ *
+ * @example
+ * const tree = [
+ *   { id: 1, name: 'A', children: [
+ *     { id: 2, name: 'B' },
+ *     { id: 3, name: 'C', children: [
+ *       { id: 4, name: 'D' }
+ *     ]}
+ *   ]},
+ *   { id: 5, name: 'E' }
+ * ];
+ *
+ * // 查找id为3的节点
+ * const result = treeFind(tree, node => node.id === 3);
+ * console.log(result); // { id: 3, name: 'C', children: [{ id: 4, name: 'D' }] }
+ */
+export function treeFind(treeLike, func) {
+    // 统一处理为数组格式
+    const tree = treeSafe(treeLike)
+
+    // 使用迭代方式遍历，避免深层递归可能导致的栈溢出
+    const stack = [...tree];
+
+    while (stack.length > 0) {
+        const currentNode = stack.pop();
+
+        if (func(currentNode)) {
+            return currentNode;
+        }
+
+        // 将子节点添加到栈中（反向添加以保持遍历顺序）
+        if (currentNode?.children && Array.isArray(currentNode.children)) {
+            for (let i = currentNode.children.length - 1; i >= 0; i--) {
+                stack.push(currentNode.children[i]);
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * 查找节点的父级
+ * 在树结构中查找满足条件的节点的父节点
+ *
+ * @param {Array|Object|null|undefined} treeLike - 待处理的树形结构数据，可以是数组、单个对象或null/undefined
+ * @param {Function} func - 用于判断节点是否满足条件的函数
+ * @param {*} parent - 当前层级的父节点，默认为null
+ *
+ * @returns {*} 找到的第一个满足条件的节点的父节点，如果没找到则返回null
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数，最坏情况下需要遍历所有节点
+ * 空间复杂度: O(h) - 其中h是树的高度，用于存储迭代栈的空间
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'parent',
+ *     children: [
+ *       { id: '11', name: 'child1' },
+ *       { id: '12', name: 'child2' }
+ *     ]
+ *   }
+ * ];
+ * const parent = treeFindParent(tree, item => item.id === '11');
+ * // 返回 id 为 '1' 的节点
+ */
+export function treeFindParent(treeLike, func, parent) {
+    // 统一处理为数组格式
+    const tree = treeSafe(treeLike)
+
+    // 输入验证
+    if (typeof func !== 'function') {
+        return null;
+    }
+
+    // 使用栈进行迭代遍历，避免深层递归导致的栈溢出
+    const stack = tree.map(node => ({ node, parent }));
+
+    while (stack.length > 0) {
+        const { node, parent: parentNode } = stack.pop();
+
+        // 检查当前节点是否满足条件
+        if (func(node)) {
+            return parentNode; // 如果满足条件，返回其父节点
+        }
+
+        // 如果当前节点有子节点，将子节点加入栈中继续遍历
+        if (node.children && Array.isArray(node.children)) {
+            // 反向添加子节点以保持原有遍历顺序
+            for (let i = node.children.length - 1; i >= 0; i--) {
+                stack.push({ node: node.children[i], parent: node });
+            }
+        }
+    }
+
+    // 遍历完所有节点仍未找到满足条件的节点，返回null
+    return null;
+}
+
+
+/**
+ * 修改树上的点
+ * 对树形结构中的每个节点应用变换函数，返回一个新的树结构
+ *
+ * @param {Array|Object} treeLike - 树形结构数据，可以是数组或单个对象
+ * @param {Function} func - 应用于每个节点的变换函数，接收节点作为参数并返回新节点
+ *
+ * @returns {Array} 经过变换后的新树形结构数组
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数，需要访问每个节点一次
+ * 空间复杂度: O(n + h) - 其中n用于存储新树结构，h是树的高度用于递归调用栈
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'parent',
+ *     children: [
+ *       { id: '11', name: 'child1' },
+ *       { id: '12', name: 'child2' }
+ *     ]
+ *   }
+ * ];
+ * const newTree = treeMap(tree, node => ({ ...node, processed: true }));
+ */
+export function treeMap(treeLike, func) {
+    // 统一处理为数组格式
+    const tree = treeSafe(treeLike)
+    // 输入验证
+    if (typeof func !== 'function') {
+        console.warn('treeMap: func 参数必须是函数类型');
+        return tree;
+    }
+
+    // 创建新数组以避免修改原数据
+    const newTree = [];
+
+    for (let i = 0; i < tree.length; i++) {
+        const item = tree[i];
+
+        // 对当前节点应用变换函数
+        const newItem = func(item);
+
+        // 递归处理子节点（如果存在）
+        if (item.children && Array.isArray(item.children) && item.children.length > 0) {
+            // 注意：应该对newItem的children进行映射，而不是item的children
+            newTree[i] = {
+                ...newItem,
+                children: treeMap(item.children, func)
+            };
+        } else {
+            newTree[i] = newItem;
+        }
+    }
+
+    return newTree;
+}
+
+
+/**
+ * 遍历树上的点
+ * 对树形结构中的每个节点执行指定的函数
+ *
+ * @param {Array|Object} treeLike - 树形结构数据，可以是数组或单个对象
+ * @param {Function} func - 对每个节点执行的回调函数，接收节点作为参数
+ *
+ * @returns {void}
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数，需要访问每个节点一次
+ * 空间复杂度: O(h) - 其中h是树的高度，用于递归调用栈的存储空间
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'parent',
+ *     children: [
+ *       { id: '11', name: 'child1' },
+ *       { id: '12', name: 'child2' }
+ *     ]
+ *   }
+ * ];
+ * treeForEach(tree, node => console.log(node.id));
+ * // 输出: '1', '11', '12'
+ */
+export function treeForEach(treeLike, func) {
+    // 输入验证
+    if (typeof func !== 'function') {
+        console.warn('treeForEach: func 参数必须是函数类型');
+        return;
+    }
+
+    // 统一处理为数组格式
+    const tree = treeSafe(treeLike);
+
+    // 使用迭代方式替代递归，避免深层树导致的栈溢出
+    const stack = [...tree];
+
+    while (stack.length > 0) {
+        const currentItem = stack.pop();
+
+        // 对当前节点执行函数
+        func(currentItem);
+
+        // 如果当前节点有子节点，将子节点添加到栈中（逆序添加以保持原有遍历顺序）
+        if (currentItem.children && Array.isArray(currentItem.children) && currentItem.children.length > 0) {
+            for (let i = currentItem.children.length - 1; i >= 0; i--) {
+                stack.push(currentItem.children[i]);
+            }
+        }
+    }
+}
+
+
+/**
+ * 删除树上的点，所有符合条件的节点都将被删除，直接操作原始树，返回被删除的节点数组。
+ *
+ * @param {Array|Object} treeLike - 树形结构数据，可以是数组或单个对象
+ * @param {Function} func - 判断节点是否需要删除的函数，接收节点作为参数
+ *
+ * @returns {Array} 入参treeLike，直接返回，指针不变
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数，需要访问每个节点一次
+ * 空间复杂度: O(n) - 最坏情况下需要存储所有被删除的节点和栈空间
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'parent',
+ *     children: [
+ *       { id: '11', name: 'child1' },
+ *       { id: '12', name: 'child2' }
+ *     ]
+ *   }
+ * ];
+ * const deleted = treeDel(tree, node => node.id === '11');
+ * // deleted 包含被删除的节点
+ * // tree 中id为'11'的节点及其所有子节点已被删除
+ */
+export function treeDel(treeLike, func) {
+    // 输入验证
+    if (typeof func !== 'function') {
+        console.warn('dlsjs: treeDel函数的第二个参数必须是函数类型');
+        return [];
+    }
+
+    // 统一处理为数组格式
+    const tree = treeSafe(treeLike);
+
+    // 存储被删除的节点
+    const removedNodes = [];
+
+    // 使用迭代方式替代递归，避免深层树导致的栈溢出
+    // 使用栈来存储需要处理的节点及其父节点的children数组和索引
+    const stack = [];
+
+    // 初始化栈，存储根节点数组
+    for (let i = tree.length - 1; i >= 0; i--) {
+        stack.push({
+            node: tree[i],
+            parentArray: tree,
+            index: i
+        });
+    }
+
+    // 处理栈中的节点（从后往前处理，避免索引变化影响）
+    const nodesToDelete = [];
+
+    while (stack.length > 0) {
+        const { node, parentArray, index } = stack.pop();
+
+        // 检查当前节点是否符合删除条件
+        if (func(node)) {
+            // 标记节点待删除
+            nodesToDelete.push({ node, parentArray, index });
+        } else {
+            // 如果节点不符合删除条件，将其子节点加入栈中继续处理
+            if (node.children && Array.isArray(node.children) && node.children.length > 0) {
+                // 从后向前添加子节点，以保持正确的处理顺序
+                for (let i = node.children.length - 1; i >= 0; i--) {
+                    stack.push({
+                        node: node.children[i],
+                        parentArray: node.children,
+                        index: i
+                    });
+                }
+            }
+        }
+    }
+
+    // 按照从后往前的顺序删除节点，避免索引变化影响
+    nodesToDelete.sort((a, b) => {
+        // 按照在各自数组中的索引从大到小排序
+        if (a.parentArray === b.parentArray) {
+            return b.index - a.index;
+        }
+        // 如果在不同数组中，我们简单地按删除顺序处理
+        return 0;
+    });
+
+    // 实际删除节点
+    for (const deletion of nodesToDelete) {
+        const { node, parentArray, index } = deletion;
+
+        // 从数组中移除节点并添加到已删除节点数组
+        const removed = parentArray.splice(index, 1)[0];
+        removedNodes.push(removed);
+    }
+
+    return tree;
+}
+
+
+
+/**
+ * 寻找叶子对象
+ * 沿着指定的键路径递归查找，直到找到没有该键的对象
+ *
+ * @param {Object} obj - 要查找的对象
+ * @param {string} leafKey - 用于查找的键名
+ *
+ * @returns {Object|null} 找到的叶子对象，如果输入无效则返回null
+ *
+ * 时间复杂度: O(k) - 其中k是叶子键的嵌套深度
+ * 空间复杂度: O(1) - 使用迭代方式，仅需常量额外空间
+ *
+ * @example
+ * const obj = {
+ *   a: {
+ *     b: {
+ *       c: 'leaf value'
+ *     }
+ *   }
+ * };
+ * const result = findLeaf(obj, 'a'); // 返回 { b: { c: 'leaf value' } }
+ * const result2 = findLeaf(obj, 'c'); // 返回 'leaf value'
+ */
+export function findLeaf(obj, leafKey) {
+    // 输入验证
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        console.warn('dlsjs: findLeaf函数的第一个参数必须是对象类型');
+        return null;
+    }
+
+    if (typeof leafKey !== 'string' || leafKey.trim() === '') {
+        console.warn('dlsjs: findLeaf函数的第二个参数必须是有效的字符串');
+        return null;
+    }
+
+    // 使用迭代方式替代递归，避免深层嵌套导致的栈溢出
+    let current = obj;
+
+    while (current !== null && typeof current === 'object') {
+        // 检查当前对象是否包含指定的键
+        if (current.hasOwnProperty(leafKey)) {
+            // 如果包含键，继续向下查找
+            current = current[leafKey];
+        } else {
+            // 如果不包含键，说明已经到达叶子节点
+            break;
+        }
+    }
+
+    return current;
+}
+
+
+/**
+ * 沿着叶子键路径查找属性值
+ * 在当前对象中查找指定属性，如果不存在则沿着叶子键路径递归查找
+ *
+ * @param {Object} obj - 要查找的对象
+ * @param {string} leafKey - 用于递归查找的叶子键名
+ * @param {string} propName - 要查找的属性名
+ *
+ * @returns {any|null} 找到的属性值，如果未找到则返回null
+ *
+ * 时间复杂度: O(k) - 其中k是叶子键的嵌套深度
+ * 空间复杂度: O(1) - 使用迭代方式，仅需常量额外空间
+ *
+ * @example
+ * const obj = {
+ *   a: {
+ *     b: {
+ *       c: 'leaf value',
+ *       targetProp: 'found value'
+ *     }
+ *   },
+ *   targetProp: 'root value'
+ * };
+ * const result = forkProp(obj, 'a', 'targetProp'); // 返回 'root value'
+ * const result2 = forkProp(obj, 'a', 'nonexistent'); // 返回 null
+ */
+export function forkProp(obj, leafKey, propName) {
+    // 输入验证
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        console.warn('dlsjs: forkProp函数的第一个参数必须是对象类型');
+        return null;
+    }
+
+    if (typeof leafKey !== 'string' || leafKey.trim() === '') {
+        console.warn('dlsjs: forkProp函数的第二个参数必须是有效的字符串');
+        return null;
+    }
+
+    if (typeof propName !== 'string' || propName.trim() === '') {
+        console.warn('dlsjs: forkProp函数的第三个参数必须是有效的字符串');
+        return null;
+    }
+
+    // 使用迭代方式替代递归，避免深层嵌套导致的栈溢出
+    let current = obj;
+
+    while (current !== null && typeof current === 'object') {
+        // 1. 优先在当前对象中查找目标属性
+        if (current.hasOwnProperty(propName)) {
+            return current[propName];
+        }
+
+        // 2. 如果当前对象包含叶子键，继续向下查找
+        if (current.hasOwnProperty(leafKey)) {
+            current = current[leafKey];
+        } else {
+            // 3. 如果不包含叶子键，说明已经到达叶子节点，查找结束
+            break;
+        }
+    }
+
+    // 遍历完所有层级仍未找到目标属性
+    return null;
+}
+
+
+/**
+ * 维表转树
+ * @param dimList 平铺维表
+ * @param dimLink 维表关联关系 e.g.['市','区县','乡镇']
+ * @param dimMap 维表关联映射字段 e.g.{'市': {propFieldName: 'code1', textFieldName: 'name1'}, '区': {propFieldName: 'code2', textFieldName: 'name2'}, '乡镇': {propFieldName: 'code3', textFieldName: 'name3'}}
+ */
+export function dim2Tree(dimList, dimLink, dimMap) {
+    let list = dim2List(dimList, dimLink, dimMap)
+    return list2Tree(list);
+}
+
+/**
+ * 维度数据转平铺列表
+ * 将多维度数据转换为带有层级关系的平铺列表，用于构建树形结构
+ * 时间复杂度O(m × k)：
+ * m 是 dimList 的长度（输入数据量）
+ * k 是 dimLink 的长度（维度层级数量）
+ *
+ * @param {Array} dimList - 维度数据源，包含各个维度信息的对象数组
+ * @param {Array} dimLink - 维度关联关系，按层级顺序排列的维度名称数组
+ * @param {Object} dimMap - 维度映射配置，定义各维度的属性字段
+ *
+ * @returns {Array} 转换后的节点列表，每个节点包含 id、parentId、label、value 等属性
+ *
+ * @example
+ * const dimList = [
+ *   { code1: '01', name1: '北京', code2: '0101', name2: '东城区' }
+ * ];
+ * const dimLink = ['市', '区'];
+ * const dimMap = {
+ *   '市': { propFieldName: 'code1', textFieldName: 'name1' },
+ *   '区': { propFieldName: 'code2', textFieldName: 'name2' }
+ * };
+ *
+ * const result = dim2List(dimList, dimLink, dimMap);
+ */
+export function dim2List(dimList, dimLink, dimMap) {
+    // 验证输入参数
+    if (!Array.isArray(dimList) || !Array.isArray(dimLink) || !dimMap) {
+        return [];
+    }
+
+    // 构建字段排序数组，按维度关联顺序排列
+    const fieldSort = [];
+    for (let i = 0; i < dimLink.length; i++) {
+        const propName = dimLink[i];
+        if (propName) {
+            const match = dimMap[propName];
+            if (match) {
+                fieldSort.push(match);
+            }
+        }
+    }
+
+    // 如果没有有效的字段配置，直接返回空数组
+    if (fieldSort.length === 0) {
+        return [];
+    }
+
+    const dataTreeOrg = [];
+
+    // 遍历每条维度数据
+    for (let i = 0; i < dimList.length; i++) {
+        const record = dimList[i];
+
+        // 为每个维度层级生成对应的节点
+        for (let j = 0; j < fieldSort.length; j++) {
+            const fieldConfig = fieldSort[j];
+
+            // 创建节点对象
+            const node = {
+                id: '',
+                parentId: '',
+                label: '',
+                value: ''
+            };
+
+            // 构建节点ID：连接当前层级及之前所有层级的编码
+            for (let k = 0; k <= j; k++) {
+                const currentField = fieldSort[k];
+                node.id += record[currentField.propFieldName] || '';
+            }
+
+            // 设置父节点ID：连接当前层级之前所有层级的编码
+            if (j > 0) {
+                for (let k = 0; k < j; k++) {
+                    const prevField = fieldSort[k];
+                    node.parentId += record[prevField.propFieldName] || '';
+                }
+            } else {
+                // 顶层节点的父ID设为'-1'
+                node.parentId = '-1';
+            }
+
+            // 设置显示标签和值
+            node.label = record[fieldConfig.textFieldName] || '';
+            node.value = record[fieldConfig.propFieldName] || '';
+
+            dataTreeOrg.push(node);
+        }
+    }
+
+    // 使用uniqBy去重，确保每个ID只对应一个节点
+    // 注意：这里假设uniqBy函数已正确导入
+    return uniqBy(item => item.id, dataTreeOrg);
+}
+
+/**
+ * 树筛选（包含父节点）
+ * 筛选出符合条件的节点及其所有父节点，返回包含这些节点的树形结构
+ *
+ * @param {Array|Object} treeLike - 树形结构数据，可以是数组或单个对象
+ * @param {Function} func - 判断节点是否满足条件的函数
+ *
+ * @returns {Array} 包含符合条件的节点及其所有父节点的树形结构
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数，需要访问每个节点一次
+ * 空间复杂度: O(n) - 需要存储所有节点和父节点关系
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'parent',
+ *     children: [
+ *       { id: '11', name: 'child1' },
+ *       { id: '12', name: 'child2' }
+ *     ]
+ *   }
+ * ];
+ * const result = treeFilter(tree, node => node.id === '11');
+ * // 返回包含id为'1'和'11'的节点的树形结构
+ */
+export function treeFilter(treeLike, func) {
+  // 输入验证
+  if (typeof func !== 'function') {
+    console.warn('dlsjs: treeFilter函数的第二个参数必须是函数类型');
+    return [];
+  }
+
+  // 统一处理为数组格式
+  const tree = treeSafe(treeLike);
+
+  // 如果树为空，直接返回空数组
+  if (tree.length === 0) {
+    return [];
+  }
+
+  // 将树转换为平铺列表
+  const list = tree2List(tree);
+
+  // 使用迭代方式设置父ID列表，避免递归栈溢出
+  setParentIds4List(list);
+
+  // 筛选符合条件的节点
+  const matchedNodes = list.filter(func);
+
+  // 如果没有符合条件的节点，返回空数组
+  if (matchedNodes.length === 0) {
+    return [];
+  }
+
+  // 收集所有需要保留的节点ID（符合条件的节点及其所有父节点）
+  const nodeIdsToKeep = new Set();
+
+  // 添加符合条件的节点ID
+  for (let i = 0; i < matchedNodes.length; i++) {
+    nodeIdsToKeep.add(matchedNodes[i].id);
+  }
+
+  // 添加所有父节点ID
+  for (let i = 0; i < matchedNodes.length; i++) {
+    const parentIds = matchedNodes[i]._parentIds || [];
+    for (let j = 0; j < parentIds.length; j++) {
+      nodeIdsToKeep.add(parentIds[j]);
+    }
+  }
+
+  // 筛选出需要保留的节点
+  const filteredList = list.filter(item => nodeIdsToKeep.has(item.id));
+
+  // 将筛选后的列表重新构建为树形结构
+  return list2Tree(filteredList);
+}
+
+/**
+ * 树转平铺
+ * 将树形结构数据转换为平铺的数组形式
+ *
+ * @param {Array|Object|null|undefined} treeLike - 待处理的树形结构数据，可以是数组、单个对象或null/undefined
+ * @param {Array} list - 可选的初始数组，用于累积结果，默认为空数组
+ *
+ * @returns {Array} 包含所有节点的平铺数组
+ *
+ * 时间复杂度: O(n) - 其中n是树中节点总数
+ * 空间复杂度: O(n) - 用于存储结果数组和递归调用栈
+ *
+ * @example
+ * const tree = [
+ *   {
+ *     id: '1',
+ *     name: 'a',
+ *     children: [
+ *       { id: '11', name: 'a1', parentId: '1' },
+ *       { id: '12', name: 'a2', parentId: '1' }
+ *     ]
+ *   }
+ * ];
+ * console.log(tree2List(tree));
+ * // 输出: [{ id: '1', name: 'a', children: [...] }, { id: '11', name: 'a1', parentId: '1' }, { id: '12', name: 'a2', parentId: '1' }]
+ */
+export function tree2List(treeLike, list = []) {
+  // 统一处理为数组格式
+  const tree = treeSafe(treeLike)
+
+  // 使用迭代方法替代递归，避免深层树导致的栈溢出
+  const stack = [...tree];
+
+  while (stack.length > 0) {
+    const currentNode = stack.pop();
+
+    // 添加当前节点到结果列表
+    list.push(currentNode);
+
+    // 如果当前节点有子节点，则将子节点添加到栈中（逆序添加以保持原有顺序）
+    if (currentNode.children && Array.isArray(currentNode.children) && currentNode.children.length > 0) {
+      // 逆序添加子节点以保持与原递归实现相同的遍历顺序
+      for (let i = currentNode.children.length - 1; i >= 0; i--) {
+        stack.push(currentNode.children[i]);
+      }
+    }
+  }
+
+  return list;
+}
+
+
+/**
+ * 裁剪树形结构到指定层级（高性能版，不裁剪原始树，返回一颗新树）
+ * @param {Array|Object|null|undefined} treeLike - 待处理的树形结构数据，可以是数组、单个对象或null/undefined
+ * @param {number} level - 要保留的层级（从1开始，level=1保留根节点，level=2保留根+一级子节点，以此类推）
+ * @returns {Array} 裁剪后的指定层级节点列表
+ */
+export function treeCutLevel(treeLike, level) {
+    // 统一处理为数组格式
+    treeLike = treeSafe(treeLike)
+    // 边界值处理：层级≤0 返回空，层级=1 直接返回根节点（浅拷贝避免修改原数据）
+    if (level <= 0) return [];
+    if (level === 1) {
+        // 只保留根节点，浅拷贝根节点（删除children），不影响原数据
+        return treeLike.map(node => {
+            const newNode = { ...node }; // 浅拷贝当前节点
+            delete newNode.children;     // 移除子节点，只保留当前层级
+            return newNode;
+        });
+    }
+
+    // 初始化：当前处理的层级节点列表（初始为根节点）
+    let currentLevelNodes = [...treeLike]; // 浅拷贝当前层级节点，不修改原数组
+    // 存储最终要返回的目标层级节点
+    let targetNodes = [];
+
+    // 遍历到指定层级（从第2层开始，到level层结束）
+    for (let currentLevel = 2; currentLevel <= level; currentLevel++) {
+        // 收集下一层的所有节点
+        const nextLevelNodes = [];
+
+        for (const node of currentLevelNodes) {
+            // 只处理有children的节点
+            if (node.children && node.children.length > 0) {
+                if (currentLevel === level) {
+                    // 到达目标层级：浅拷贝当前子节点，删除其children后加入结果
+                    const cutNodes = node.children.map(child => {
+                        const newChild = { ...child };
+                        delete newChild.children;
+                        return newChild;
+                    });
+                    targetNodes.push(...cutNodes);
+                } else {
+                    // 未到目标层级：收集子节点，继续遍历下一层
+                    nextLevelNodes.push(...node.children);
+                }
+            }
+        }
+
+        // 更新当前层级节点为下一层
+        currentLevelNodes = nextLevelNodes;
+
+        // 提前终止：如果下一层没有节点，无需继续循环
+        if (currentLevelNodes.length === 0) break;
+    }
+
+    return targetNodes;
+}
+
+
+/**
+ * 安全处理树形结构，确保树为数组格式
+ * 将输入的树形结构统一转换为数组格式，便于后续处理
+ *
+ * @param {Array|Object|null|undefined} treeLike - 待处理的树形结构数据，可以是数组、单个对象或null/undefined
+ *
+ * @returns {Array} 统一格式的数组，如果输入为数组则直接返回，如果是对象则包装成数组，其他情况返回空数组
+ *
+ * 时间复杂度: O(1) - 仅执行简单的类型检查和转换操作
+ * 空间复杂度: O(1) - 不考虑输出数组的空间，仅使用常量额外空间
+ *
+ * @example
+ * treeSafe([]); // 返回 []
+ * treeSafe({id: 1, name: 'node'}); // 返回 [{id: 1, name: 'node'}]
+ * treeSafe([{id: 1}, {id: 2}]); // 返回 [{id: 1}, {id: 2}]
+ * treeSafe(null); // 返回 []
+ * treeSafe(undefined); // 返回 []
+ */
+function treeSafe(treeLike) {
+  // 统一处理为数组格式
+  let tree = [];
+  if (Array.isArray(treeLike)) {
+    // 如果输入已经是数组，直接返回
+    tree = treeLike;
+  } else if (typeof treeLike === 'object' && treeLike !== null) {
+    // 如果输入是对象且不为null，将其包装在数组中
+    tree = [treeLike];
+  }
+  // 对于其他情况（null, undefined, 基本类型等），返回空数组
+  return tree;
+}
+