@ticatec/uniface-element 0.3.16 → 0.3.17

package/dist/lib/TreeNodes.js

@@ -1,184 +1,376 @@
+/**
+ * 比较两个数字
+ * @param a 第一个数字
+ * @param b 第二个数字
+ * @returns 如果相等返回 0，a > b 返回 1，否则返回 -1
+ */
 export function compareNumber(a, b) {
     return a === b ? 0 : a > b ? 1 : -1;
 }
-export class CommonTreeNodes {
-    checkIsRoot;
+/**
+ * 节点视图配置类 - 定义节点的显示方式
+ * @template T 节点数据的类型
+ *
+ * @example
+ * const options = new NodeViewOptions<MyData>({
+ *   keyField: 'id',
+ *   textField: 'name'
+ * });
+ */
+export class NodeViewOptions {
+    /**
+     * 获取节点的唯一标识字段
+     */
     keyField;
-    parentKeyField;
+    /**
+     * 获取节点的文字
+     * 可以是字段名或函数
+     */
     textField;
-    checkIsDirectory;
-    nodeMap;
-    compareFun;
-    expendDepth;
-    _nodes = [];
-    _version = 0;
+    /**
+     * 创建节点视图配置
+     * @param options 配置选项
+     */
     constructor(options) {
-        this.checkIsRoot = options.checkIsRoot;
-        this.compareFun = options.compareFun;
-        this.keyField = options.keyField ?? 'id';
-        this.textField = options.textField ?? 'text';
-        this.parentKeyField = options.parentKeyField ?? 'parentId';
-        this.nodeMap = new Map();
-        this.expendDepth = options.expendDepth ?? 1;
-        this.checkIsDirectory = options.checkIsDirectory;
+        this.keyField = options.keyField;
+        this.textField = options.textField;
     }
-    touch() {
-        this._version++;
+    /**
+     * 获取节点的文字
+     * @param data 节点数据
+     * @returns 显示文字
+     */
+    getText(data) {
+        if (typeof this.textField === 'function') {
+            return this.textField(data);
+        }
+        return String(data[this.textField] ?? '');
     }
     /**
-     * 创建带有方法的节点
+     * 获取节点的唯一标识
+     * @param data 节点数据
+     * @returns 唯一标识值
      */
-    createNodeWithMethods(item) {
-        const node = {
-            item,
-            expand: false,
-            append: (childItem) => this.addNodeToNode(node, childItem),
-            remove: () => this.removeNode(node),
-            replace: (newItem) => this.replaceNodeItem(node, newItem),
-            moveTo: (newParentId) => this.moveNodeTo(node, newParentId),
-            removeChild: (childId) => this.removeChildNode(node, childId),
-            removeChildren: () => this.removeChildrenNodes(node)
-        };
-        return node;
+    getKey(data) {
+        return data[this.keyField];
     }
+}
+/**
+ * TreeNode 类 - 树节点，包含数据和方法
+ * @template T 节点数据的类型
+ *
+ * @description
+ * TreeNode 是树结构的基本单元，每个节点包含：
+ * - 节点数据（item）
+ * - 父节点引用（parent）
+ * - 子节点列表（children）
+ * - 展开状态（expand）
+ * - 加载状态（loading）
+ *
+ * 节点提供了丰富的操作方法，可以直接在节点上进行增删改查操作。
+ */
+export class TreeNode {
+    /**
+     * 节点数据（私有，只读）
+     * @private
+     */
+    _item;
+    /**
+     * 节点层级（私有）
+     * @private
+     */
+    _level;
+    /**
+     * 是否展开（显示子节点）
+     */
+    expand = false;
     /**
-     * 添加子节点到指定节点
+     * 是否正在加载（用于懒加载）
      */
-    addNodeToNode(parentNode, childItem) {
-        // 如果父节点还没有 children（可能是 lazy 节点）
-        // 自动触发 lazyLoader 加载或初始化 children 数组
-        if (parentNode.children == null) {
-            parentNode.children = [];
+    loading = false;
+    /**
+     * 父节点（只读）
+     */
+    parent = null;
+    /**
+     * 子节点数组（私有）
+     * @private
+     */
+    _children = null;
+    /**
+     * 创建树节点
+     * @param item 节点数据
+     * @param parent 父节点（可选）
+     * @param children 子节点列表（可选）
+     *
+     * @example
+     * // 创建根节点
+     * const rootNode = new TreeNode({ id: 1, name: "根节点" });
+     *
+     * // 创建子节点
+     * const childNode = new TreeNode({ id: 2, name: "子节点" }, rootNode);
+     */
+    constructor(item, parent = null, children = null) {
+        this._item = item;
+        this._level = parent ? parent._level + 1 : 0;
+        this.parent = parent;
+        this._children = children;
+        this.expand = false;
+        // 如果有父节点，将自己添加到父节点的 children 中
+        if (parent) {
+            if (!parent._children) {
+                parent._children = [];
+            }
+            parent._children.push(this);
         }
-        const childNode = this.createNodeWithMethods(childItem);
-        parentNode.children = [...parentNode.children, childNode];
-        if (this.compareFun) {
-            parentNode.children = parentNode.children.sort((n1, n2) => {
-                return this.compareFun(n1.item, n2.item);
-            });
+    }
+    /**
+     * 获取节点层级
+     * @returns 层级值（根节点为 0）
+     */
+    get level() {
+        return this._level;
+    }
+    /**
+     * 获取子节点列表（只读）
+     * @returns 子节点数组的浅拷贝，如果没有子节点返回 null
+     *
+     * @example
+     * const children = node.children;
+     * if (children) {
+     *   children.forEach(child => console.log(child.item));
+     * }
+     */
+    get children() {
+        return this._children ? [...this._children] : null;
+    }
+    /**
+     * 添加子节点
+     * @param childItem 子节点数据
+     * @returns 新创建的子节点
+     *
+     * @example
+     * const childNode = parentNode.append({ id: 1, name: "子节点" });
+     */
+    append(childItem) {
+        return new TreeNode(childItem, this);
+    }
+    /**
+     * 从父节点中分离（删除当前节点）
+     *
+     * @example
+     * node.detach();
+     */
+    detach() {
+        if (!this.parent) {
+            console.warn('TreeNode is not attached to a tree, cannot detach');
+            return;
         }
-        parentNode.expand = true;
-        this.nodeMap.set(childItem[this.keyField], childNode);
-        this.touch();
+        this.parent.removeNode(this);
     }
     /**
-     * 删除指定节点
+     * 删除指定的子节点
+     * @param node 要删除的子节点
+     * @private
      */
     removeNode(node) {
-        const idKey = node.item[this.keyField];
-        const parentKey = node.item[this.parentKeyField];
-        const parentNode = this.nodeMap.get(parentKey);
-        this.nodeMap.delete(idKey);
-        if (parentNode) {
-            if (parentNode.children) {
-                parentNode.children = parentNode.children.filter(el => el.item[this.keyField] != idKey);
+        if (this._children) {
+            let idx = this._children.indexOf(node);
+            if (idx >= 0) {
+                this._children.splice(idx, 1);
+            }
+            else {
+                console.warn(' The removed node has not been attached to this.');
             }
         }
         else {
-            // 是根节点
-            this._nodes = this._nodes.filter(el => el.item[this.keyField] != idKey);
+            console.warn(' The removed node has not been attached to this.');
         }
-        this.touch();
     }
     /**
-     * 替换节点的数据
+     * 移动到另一个父节点下
+     * @param newParent 新的父节点
+     * @returns 新创建的节点（注意：返回的是新节点，不是原节点）
+     *
+     * @example
+     * node.moveTo(newParentNode);
      */
-    replaceNodeItem(node, newItem) {
-        node.item = newItem;
-        // 如果排序字段改变了，需要重新排序
-        const parentKey = node.item[this.parentKeyField];
-        const parentNode = this.nodeMap.get(parentKey);
-        if (parentNode && parentNode.children && parentNode.children.length > 0) {
-            parentNode.children = parentNode.children.sort((n1, n2) => {
-                return this.compareFun?.(n1.item, n2.item);
-            });
-        }
-        else {
-            this._nodes.sort((n1, n2) => {
-                return this.compareFun?.(n1.item, n2.item);
-            });
-        }
-        this.touch();
+    moveTo(newParent) {
+        return new TreeNode(this._item, newParent, this._children);
     }
     /**
-     * 将节点移动到新的父节点下
+     * 替换当前节点的数据
+     * @param newItem 新的数据对象
+     *
+     * @example
+     * node.replace({ id: 1, name: "新名称", ...otherFields });
      */
-    moveNodeTo(node, newParentId) {
-        const newParent = this.nodeMap.get(newParentId);
-        const currentParentKey = node.item[this.parentKeyField];
-        const currentParent = this.nodeMap.get(currentParentKey);
-        if (!newParent || !currentParent) {
-            console.warn('Cannot move node: parent not found');
-            return;
-        }
-        // 从当前父节点移除
-        if (currentParent.children) {
-            currentParent.children = currentParent.children.filter(el => el.item[this.keyField] != node.item[this.keyField]);
-        }
-        // 如果新父节点还没有 children，初始化数组
-        if (newParent.children == null) {
-            newParent.children = [];
-        }
-        // 添加到新父节点
-        newParent.children = [...newParent.children, node];
-        if (this.compareFun) {
-            newParent.children = newParent.children.sort((n1, n2) => {
-                return this.compareFun(n1.item, n2.item);
-            });
-        }
-        // 更新节点的 parentKeyField
-        node.item[this.parentKeyField] = newParentId;
-        this.touch();
+    replace(newItem) {
+        this._item = newItem;
     }
     /**
-     * 删除指定节点的某个子节点
+     * 获取节点数据
+     * @returns 节点数据对象
      */
-    removeChildNode(parentNode, childId) {
-        if (!parentNode.children)
-            return;
-        const childNode = parentNode.children.find(child => child.item[this.keyField] == childId);
-        if (!childNode)
-            return;
-        // 从 children 数组中移除
-        parentNode.children = parentNode.children.filter(child => child.item[this.keyField] != childId);
-        // 从 nodeMap 中删除
-        this.nodeMap.delete(childId);
-        this.touch();
+    get item() {
+        return this._item;
     }
     /**
-     * 删除指定节点的所有子节点
+     * 删除所有子节点
+     *
+     * @example
+     * node.removeChildren();
      */
-    removeChildrenNodes(parentNode) {
-        if (!parentNode.children)
-            return;
-        // 从 nodeMap 中删除所有子节点
-        for (const child of parentNode.children) {
-            const childId = child.item[this.keyField];
-            this.nodeMap.delete(childId);
+    removeChildren() {
+        this._children = [];
+    }
+    /**
+     * @internal 仅供 TreeNodes 内部使用
+     * 设置父节点，并将自己添加到父节点的 children 中
+     * @param parent 新的父节点
+     *
+     * @description
+     * 此方法会：
+     * 1. 从原父节点的 children 中移除自己
+     * 2. 更新父节点引用
+     * 3. 重新计算层级
+     * 4. 将自己添加到新父节点的 children 中
+     */
+    _setParent(parent) {
+        // 从原父节点的 children 中移除自己
+        const oldParent = this.parent;
+        if (oldParent && oldParent._children) {
+            const index = oldParent._children.indexOf(this);
+            if (index >= 0) {
+                oldParent._children.splice(index, 1);
+            }
+        }
+        // 设置新父节点
+        this.parent = parent;
+        this._level = parent ? parent._level + 1 : 0;
+        // 将自己添加到新父节点的 children 中
+        if (parent) {
+            if (!parent._children) {
+                parent._children = [];
+            }
+            parent._children.push(this);
         }
-        // 清空 children 数组
-        parentNode.children = [];
-        this.touch();
     }
+}
+/**
+ * TreeNodes 类 - 树节点管理器
+ * @template T 节点数据的类型
+ *
+ * @description
+ * TreeNodes 负责管理树结构的数据，包括：
+ * - 树的构建和初始化
+ * - 节点的映射和查找
+ * - 版本管理（用于响应式更新）
+ * - 层级展开控制
+ *
+ * @example
+ * interface MyData {
+ *   id: number;
+ *   name: string;
+ *   parentId: number | null;
+ * }
+ *
+ * const treeNodes = new TreeNodes<MyData>({
+ *   keyField: 'id',
+ *   textField: 'name',
+ *   parentKeyField: 'parentId',
+ *   checkIsRoot: (item) => item.parentId === null,
+ *   checkIsDirectory: (node) => node.children !== null,
+ *   expendDepth: 2
+ * });
+ *
+ * treeNodes.setData([
+ *   { id: 1, name: "根节点", parentId: null },
+ *   { id: 2, name: "子节点1", parentId: 1 },
+ *   { id: 3, name: "子节点2", parentId: 1 }
+ * ]);
+ */
+export default class TreeNodes {
+    checkIsRoot;
+    keyField;
+    parentKeyField;
+    textField;
+    checkIsDirectory;
+    nodeMap;
+    compareFun;
+    expendDepth;
+    _nodes = [];
+    _version = 0;
+    /**
+     * 创建 TreeNodes 实例
+     * @param options 配置选项
+     */
+    constructor(options) {
+        this.checkIsRoot = options.checkIsRoot;
+        this.compareFun = options.compareFun;
+        this.keyField = options.keyField ?? 'id';
+        this.textField = options.textField ?? 'text';
+        this.parentKeyField = options.parentKeyField ?? 'parentId';
+        this.nodeMap = new Map();
+        this.expendDepth = options.expendDepth ?? 1;
+        this.checkIsDirectory = options.checkIsDirectory;
+    }
+    /**
+     * 设置树数据
+     * @param list 扁平化的节点数据数组
+     *
+     * @description
+     * 此方法会：
+     * 1. 清空现有树结构
+     * 2. 创建所有节点
+     * 3. 根据 parentKeyField 建立父子关系
+     * 4. 应用展开深度设置
+     * 5. 触发版本更新
+     *
+     * @example
+     * treeNodes.setData([
+     *   { id: 1, name: "根节点", parentId: null },
+     *   { id: 2, name: "子节点1", parentId: 1 },
+     *   { id: 3, name: "子节点2", parentId: 1 }
+     * ]);
+     */
     setData(list) {
         this.nodeMap = new Map();
         this._nodes = [];
-        // 初始化每个节点
+        // 第一遍：创建所有节点（不设置父子关系）
         for (const item of list) {
-            const node = this.createNodeWithMethods(item);
             const key = item[this.keyField];
+            const node = new TreeNode(item); // 创建节点时不设置 parent
             this.nodeMap.set(key, node);
         }
+        // 第二遍：建立父子关系
         for (const item of list) {
-            const node = this.nodeMap.get(item[this.keyField]);
-            if (node) {
-                this.appendNode(node);
+            const key = item[this.keyField];
+            const node = this.nodeMap.get(key);
+            if (this.checkIsRoot(item)) {
+                // 是根节点
+                this._nodes.push(node);
+            }
+            else {
+                // 不是根节点，找到父节点并建立关系
+                const parentKey = item[this.parentKeyField];
+                const parentNode = this.nodeMap.get(parentKey);
+                if (parentNode) {
+                    // 使用 _setParent 方法建立父子关系
+                    node._setParent(parentNode);
+                }
+                else {
+                    console.warn(`Parent node ${parentKey} not found for item ${key}, treating as root node`);
+                    this._nodes.push(node);
+                }
             }
         }
-        if (this.expendDepth > 1) {
-            this.setExpandForDepth(this.nodes, 0);
+        // 应用展开深度设置
+        if (this.expendDepth > 0) {
+            this.setExpandForDepth(this._nodes, 0);
         }
-        this.touch();
+        // 触发版本更新
+        this._version++;
     }
     /**
      * 获取节点
@@ -203,99 +395,77 @@ export class CommonTreeNodes {
     setExpandForDepth(nodes, currentLevel) {
         for (const node of nodes) {
             node.expand = currentLevel < this.expendDepth;
-            if (node.children) {
-                this.setExpandForDepth(node.children, currentLevel + 1);
-            }
+            // if (node.getInternalChildren().length > 0) {
+            //     this.setExpandForDepth(node.getInternalChildren(), currentLevel + 1);
+            // }
         }
     }
     /**
-     * 添加一个节点
-     * @param node
-     * @param doSort
-     * @protected
+     * 获取展开的展示列表
      */
-    appendNode(node, doSort = false) {
-        let item = node.item;
-        const parentKey = item[this.parentKeyField];
-        if (this.checkIsRoot(item)) {
-            this._nodes.push(node);
-            this._nodes.sort((n1, n2) => {
-                return this.compareFun?.(n1.item, n2.item);
-            });
-        }
-        else {
-            const parentNode = this.nodeMap.get(parentKey);
-            if (parentNode) {
-                parentNode.expand = true;
-                parentNode.children = [...(parentNode.children ?? []), node];
-                if (doSort && this.compareFun) {
-                    parentNode.children = parentNode.children.sort((n1, n2) => {
-                        return this.compareFun(n1.item, n2.item);
-                    });
-                }
-            }
-            else {
-                console.warn('Ignore the isolate item:', item);
+    getHierarchyList() {
+        let arr = [];
+        this.addExpandNodesToList(this.nodes, arr);
+        return arr;
+    }
+    addExpandNodesToList(nodes, list) {
+        for (let node of nodes) {
+            list.push(node);
+            if (node.expand) {
+                this.addExpandNodesToList(node.children ?? [], list);
             }
         }
     }
-}
-export default class TreeNodes extends CommonTreeNodes {
     /**
-     * 获取展开的展示列表
+     * 不检测匹配情况，在指定的父节点下添加子节点
      */
-    getHierarchyList() {
-        return this.collectExpandedNodes(this._nodes);
+    batchAttachToParent(parent, list) {
+        let nodes = [];
+        for (let item of list) {
+            nodes.push(new TreeNode(item, parent));
+        }
+        return nodes;
     }
     /**
      * 增加一个新节点（便捷方法，会自动根据 parentKeyField 找到父节点）
      * @param item 要添加的节点数据
      */
     append(item) {
-        const parentKey = item[this.parentKeyField];
-        const parentNode = this.nodeMap.get(parentKey);
-        if (!parentNode) {
-            console.warn(`Parent node ${parentKey} not found. Cannot add node.`);
-            return;
+        if (parent) {
+            if (this.checkIsRoot(item)) {
+                let node = new TreeNode(item);
+                this._nodes.push(node);
+                this._version++;
+                return node;
+            }
+            else {
+                throw new Error(`the entity is not a root data`);
+            }
         }
-        parentNode.append(item);
-    }
-    /**
-     * 获取除指定节点外的其他节点
-     * @param exclusiveData
-     */
-    extractDirectories(exclusiveData) {
-        const getNodes = (nodes, item) => {
-            let list = [];
-            for (let node of nodes) {
-                if (node.item != item && this.checkIsDirectory?.(node)) {
-                    list.push({
-                        item: node.item,
-                        expand: true,
-                        children: getNodes(node.children ?? [], item)
-                    });
-                }
+        else {
+            let parent = this.findParent(this.nodes, item);
+            if (!parent) {
+                let node = new TreeNode(item, parent);
+                this._version++;
+                return node;
             }
-            return list;
-        };
-        return getNodes(this.nodes, exclusiveData);
+            else {
+                throw new Error(`cannot find the parent.`);
+            }
+        }
     }
-    /**
-     * 获取所有展开的节点
-     * @param tree
-     * @private
-     */
-    collectExpandedNodes(tree) {
-        const result = [];
-        function traverse(nodes) {
-            for (const node of nodes) {
-                result.push(node);
-                if (node.expand && node.children) {
-                    traverse(node.children);
+    findParent(nodes, item) {
+        let found = null;
+        for (const node of nodes) {
+            if (!found) {
+                if (node.item[this.keyField] == item[this.parentKeyField]) {
+                    found = node;
+                }
+                else {
+                    found = node.children && node.children.length > 0 ? this.findParent(node.children, item) : null;
                 }
             }
         }
-        traverse(tree);
-        return result;
+        return found;
     }
 }

package/dist/lib/index.d.ts

@@ -1,9 +1,8 @@
 import TreeNodes from "./TreeNodes";
-import type { TreeNode } from "./TreeNodes";
-import { CommonTreeNodes } from "./TreeNodes";
+import type { ITreeNode } from "./TreeNodes";
 import type { CheckIsRoot, CompareFun, GetText, CheckIsDirectory, TreeNodeOptions } from "./TreeNodes";
 import { compareNumber } from "./TreeNodes";
 export default TreeNodes;
-export { CommonTreeNodes, compareNumber };
-export type { TreeNode };
+export { compareNumber };
+export type { ITreeNode };
 export type { CheckIsRoot, CompareFun, GetText, CheckIsDirectory, TreeNodeOptions };

package/dist/lib/index.js

@@ -1,5 +1,4 @@
 import TreeNodes from "./TreeNodes";
-import { CommonTreeNodes } from "./TreeNodes";
 import { compareNumber } from "./TreeNodes";
 export default TreeNodes;
-export { CommonTreeNodes, compareNumber };
+export { compareNumber };

package/dist/nav-menu/Menus.d.ts

@@ -1,6 +1,6 @@
-import { CommonTreeNodes } from "../lib/TreeNodes";
+import TreeNodes from "../lib/TreeNodes";
 import type MenuItem from "./MenuItem";
-export default class Menus extends CommonTreeNodes<MenuItem> {
+export default class Menus extends TreeNodes<MenuItem> {
     /**
      * 删除所有没有子节点的目录类型节点
      */