@ticatec/uniface-element 0.3.16 → 0.3.17

package/dist/lib/TreeNodes.d.ts

@@ -1,112 +1,380 @@
+/**
+ * 比较两个数字
+ * @param a 第一个数字
+ * @param b 第二个数字
+ * @returns 如果相等返回 0，a > b 返回 1，否则返回 -1
+ */
 export declare function compareNumber(a: number, b: number): 0 | 1 | -1;
-export type TreeNode<T> = {
-    item: T;
-    expand?: boolean;
-    children?: TreeNode<T>[];
-};
-export type CheckIsRoot<T> = (data: T) => boolean;
-export type CompareFun<T> = (o1: T, o2: T) => number | undefined;
-export type GetText<T> = (data: T) => string;
-export type CheckIsDirectory<T> = (node: TreeNode<T>) => boolean;
-export interface TreeNodeOptions<T> {
-    keyField?: keyof T;
-    textField?: keyof T | GetText<T>;
-    parentKeyField?: keyof T;
-    checkIsRoot: CheckIsRoot<T>;
-    checkIsDirectory?: CheckIsDirectory<T>;
-    compareFun?: CompareFun<T>;
-    expendDepth?: number;
+/**
+ * 节点视图配置类 - 定义节点的显示方式
+ * @template T 节点数据的类型
+ *
+ * @example
+ * const options = new NodeViewOptions<MyData>({
+ *   keyField: 'id',
+ *   textField: 'name'
+ * });
+ */
+export declare class NodeViewOptions<T> {
+    /**
+     * 获取节点的唯一标识字段
+     */
+    keyField: keyof T;
+    /**
+     * 获取节点的文字
+     * 可以是字段名或函数
+     */
+    textField: keyof T | ((data: T) => string);
+    /**
+     * 创建节点视图配置
+     * @param options 配置选项
+     */
+    constructor(options: {
+        /** 唯一标识字段名 */
+        keyField: keyof T;
+        /** 显示文字的字段名或获取函数 */
+        textField: keyof T | ((data: T) => string);
+    });
+    /**
+     * 获取节点的文字
+     * @param data 节点数据
+     * @returns 显示文字
+     */
+    getText(data: T): string;
+    /**
+     * 获取节点的唯一标识
+     * @param data 节点数据
+     * @returns 唯一标识值
+     */
+    getKey(data: T): any;
 }
-export type TreeNodeWithMethods<T> = TreeNode<T> & {
+/**
+ * 树节点接口
+ * @template T 节点数据的类型
+ */
+export interface ITreeNode<T> {
     /**
-     * 添加子节点到当前节点
-     * @param childItem 子节点的数据（直接传入数据对象，不需要包装成 TreeNode）
+     * 是否展开（显示子节点）
+     */
+    expand: boolean;
+    /**
+     * 是否正在加载（用于懒加载）
+     */
+    loading: boolean;
+    /**
+     * 获取节点层级（根节点为 0）
+     */
+    get level(): number;
+    /**
+     * 获取子节点列表（只读，不能从外部修改）
+     * @returns 子节点数组，如果没有子节点返回 null
+     */
+    get children(): Array<ITreeNode<T>> | null;
+    /**
+     * 添加子节点
+     * @param childItem 子节点数据
+     * @returns 新创建的子节点
+     *
+     * @example
+     * const childNode = parentNode.append({ id: 1, name: "子节点" });
+     */
+    append(childItem: T): ITreeNode<T>;
+    /**
+     * 从父节点中分离（删除当前节点）
      *
      * @example
-     * // 直接传入数据对象
-     * parentNode.append({ id: 1, name: "子节点" });
+     * node.detach();
      */
-    append: (childItem: T) => void;
+    detach(): void;
     /**
-     * 删除当前节点（从父节点中移除）
+     * 移动到另一个父节点下
+     * @param newParent 新的父节点
+     * @returns 当前节点（支持链式调用）
      *
      * @example
-     * node.remove();
+     * node.moveTo(newParentNode);
      */
-    remove: () => void;
+    moveTo(newParent: ITreeNode<T>): ITreeNode<T>;
     /**
      * 替换当前节点的数据
-     * @param newItem 新的数据对象（直接传入数据对象，不需要包装成 TreeNode）
+     * @param newItem 新的数据对象
      *
      * @example
      * node.replace({ id: 1, name: "新名称", ...otherFields });
      */
-    replace: (newItem: T) => void;
+    replace(newItem: T): void;
     /**
-     * 将当前节点移动到另一个父节点下
-     * @param newParentId 新父节点的 ID（根据 keyField 指定的字段）
+     * 获取节点的数据
+     */
+    get item(): T;
+    /**
+     * 删除所有子节点
      *
      * @example
-     * node.moveTo("parent-123");
+     * node.removeChildren();
      */
-    moveTo: (newParentId: string) => void;
+    removeChildren(): void;
+}
+/**
+ * TreeNode 类 - 树节点，包含数据和方法
+ * @template T 节点数据的类型
+ *
+ * @description
+ * TreeNode 是树结构的基本单元，每个节点包含：
+ * - 节点数据（item）
+ * - 父节点引用（parent）
+ * - 子节点列表（children）
+ * - 展开状态（expand）
+ * - 加载状态（loading）
+ *
+ * 节点提供了丰富的操作方法，可以直接在节点上进行增删改查操作。
+ */
+export declare class TreeNode<T> implements ITreeNode<T> {
+    /**
+     * 节点数据（私有，只读）
+     * @private
+     */
+    private _item;
+    /**
+     * 节点层级（私有）
+     * @private
+     */
+    private _level;
+    /**
+     * 是否展开（显示子节点）
+     */
+    expand: boolean;
+    /**
+     * 是否正在加载（用于懒加载）
+     */
+    loading: boolean;
+    /**
+     * 父节点（只读）
+     */
+    readonly parent: TreeNode<T> | null;
+    /**
+     * 子节点数组（私有）
+     * @private
+     */
+    private _children;
+    /**
+     * 创建树节点
+     * @param item 节点数据
+     * @param parent 父节点（可选）
+     * @param children 子节点列表（可选）
+     *
+     * @example
+     * // 创建根节点
+     * const rootNode = new TreeNode({ id: 1, name: "根节点" });
+     *
+     * // 创建子节点
+     * const childNode = new TreeNode({ id: 2, name: "子节点" }, rootNode);
+     */
+    constructor(item: T, parent?: TreeNode<T> | null, children?: Array<TreeNode<T>> | null);
+    /**
+     * 获取节点层级
+     * @returns 层级值（根节点为 0）
+     */
+    get level(): number;
+    /**
+     * 获取子节点列表（只读）
+     * @returns 子节点数组的浅拷贝，如果没有子节点返回 null
+     *
+     * @example
+     * const children = node.children;
+     * if (children) {
+     *   children.forEach(child => console.log(child.item));
+     * }
+     */
+    get children(): Array<TreeNode<T>> | null;
+    /**
+     * 添加子节点
+     * @param childItem 子节点数据
+     * @returns 新创建的子节点
+     *
+     * @example
+     * const childNode = parentNode.append({ id: 1, name: "子节点" });
+     */
+    append(childItem: T): TreeNode<T>;
+    /**
+     * 从父节点中分离（删除当前节点）
+     *
+     * @example
+     * node.detach();
+     */
+    detach(): void;
     /**
      * 删除指定的子节点
-     * @param childId 子节点的 ID（根据 keyField 指定的字段）
+     * @param node 要删除的子节点
+     * @private
+     */
+    private removeNode;
+    /**
+     * 移动到另一个父节点下
+     * @param newParent 新的父节点
+     * @returns 新创建的节点（注意：返回的是新节点，不是原节点）
      *
      * @example
-     * node.removeChild(123);
+     * node.moveTo(newParentNode);
      */
-    removeChild: (childId: any) => void;
+    moveTo(newParent: TreeNode<T>): TreeNode<T>;
+    /**
+     * 替换当前节点的数据
+     * @param newItem 新的数据对象
+     *
+     * @example
+     * node.replace({ id: 1, name: "新名称", ...otherFields });
+     */
+    replace(newItem: T): void;
+    /**
+     * 获取节点数据
+     * @returns 节点数据对象
+     */
+    get item(): T;
     /**
      * 删除所有子节点
      *
      * @example
      * node.removeChildren();
      */
-    removeChildren: () => void;
-};
-export declare class CommonTreeNodes<T> {
-    protected readonly checkIsRoot: CheckIsRoot<T>;
-    protected readonly keyField: keyof T;
-    protected readonly parentKeyField: keyof T;
-    protected readonly textField: keyof T | GetText<T>;
-    protected readonly checkIsDirectory: CheckIsDirectory<T> | undefined;
-    protected nodeMap: Map<any, TreeNodeWithMethods<T>>;
-    protected compareFun: any | undefined;
-    protected expendDepth: number;
-    protected _nodes: Array<TreeNodeWithMethods<T>>;
-    protected _version: number;
-    constructor(options: TreeNodeOptions<T>);
-    protected touch(): void;
+    removeChildren(): void;
+    /**
+     * @internal 仅供 TreeNodes 内部使用
+     * 设置父节点，并将自己添加到父节点的 children 中
+     * @param parent 新的父节点
+     *
+     * @description
+     * 此方法会：
+     * 1. 从原父节点的 children 中移除自己
+     * 2. 更新父节点引用
+     * 3. 重新计算层级
+     * 4. 将自己添加到新父节点的 children 中
+     */
+    _setParent(parent: TreeNode<T> | null): void;
+}
+/**
+ * 判断数据是否为根节点的函数类型
+ * @template T 数据类型
+ */
+export type CheckIsRoot<T> = (data: T) => boolean;
+/**
+ * 比较函数类型
+ * @template T 数据类型
+ * @returns 返回 0 表示相等，正数表示 o1 > o2，负数表示 o1 < o2
+ */
+export type CompareFun<T> = (o1: T, o2: T) => number | undefined;
+/**
+ * 获取文本的函数类型
+ * @template T 数据类型
+ */
+export type GetText<T> = (data: T) => string;
+/**
+ * 判断节点是否为分支（有子节点）的函数类型
+ * @template T 数据类型
+ */
+export type CheckIsDirectory<T> = (node: ITreeNode<T>) => boolean;
+/**
+ * TreeNodes 配置选项
+ * @template T 节点数据的类型
+ */
+export interface TreeNodeOptions<T> {
     /**
-     * 创建带有方法的节点
+     * 唯一标识字段名（默认：'id'）
      */
-    protected createNodeWithMethods(item: T): TreeNodeWithMethods<T>;
+    keyField?: keyof T;
     /**
-     * 添加子节点到指定节点
+     * 显示文字的字段名或获取函数（默认：'text'）
      */
-    protected addNodeToNode(parentNode: TreeNodeWithMethods<T>, childItem: T): void;
+    textField?: keyof T | GetText<T>;
     /**
-     * 删除指定节点
+     * 父节点引用字段名（默认：'parentId'）
      */
-    protected removeNode(node: TreeNodeWithMethods<T>): void;
+    parentKeyField?: keyof T;
     /**
-     * 替换节点的数据
+     * 判断数据是否为根节点的函数（必需）
      */
-    protected replaceNodeItem(node: TreeNodeWithMethods<T>, newItem: T): void;
+    checkIsRoot: CheckIsRoot<T>;
     /**
-     * 将节点移动到新的父节点下
+     * 判断节点是否为分支的函数（可选）
      */
-    protected moveNodeTo(node: TreeNodeWithMethods<T>, newParentId: string): void;
+    checkIsDirectory?: CheckIsDirectory<T>;
     /**
-     * 删除指定节点的某个子节点
+     * 排序比较函数（可选）
      */
-    protected removeChildNode(parentNode: TreeNodeWithMethods<T>, childId: any): void;
+    compareFun?: CompareFun<T>;
     /**
-     * 删除指定节点的所有子节点
+     * 默认展开深度（默认：1）
+     */
+    expendDepth?: number;
+}
+/**
+ * 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<T> {
+    protected readonly checkIsRoot: CheckIsRoot<T>;
+    protected readonly keyField: keyof T;
+    protected readonly parentKeyField: keyof T;
+    protected readonly textField: keyof T | GetText<T>;
+    protected readonly checkIsDirectory: CheckIsDirectory<T> | undefined;
+    protected nodeMap: Map<any, TreeNode<T>>;
+    protected compareFun: any | undefined;
+    protected expendDepth: number;
+    protected _nodes: Array<TreeNode<T>>;
+    protected _version: number;
+    /**
+     * 创建 TreeNodes 实例
+     * @param options 配置选项
+     */
+    constructor(options: TreeNodeOptions<T>);
+    /**
+     * 设置树数据
+     * @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 }
+     * ]);
      */
-    protected removeChildrenNodes(parentNode: TreeNodeWithMethods<T>): void;
     setData(list: Array<T>): void;
     /**
      * 获取节点
@@ -124,32 +392,18 @@ export declare class CommonTreeNodes<T> {
      */
     protected setExpandForDepth(nodes: TreeNode<T>[], currentLevel: number): void;
     /**
-     * 添加一个节点
-     * @param node
-     * @param doSort
-     * @protected
+     * 获取展开的展示列表
      */
-    protected appendNode(node: TreeNodeWithMethods<T>, doSort?: boolean): void;
-}
-export default class TreeNodes<T> extends CommonTreeNodes<T> {
+    getHierarchyList(): Array<ITreeNode<T>>;
+    private addExpandNodesToList;
     /**
-     * 获取展开的展示列表
+     * 不检测匹配情况，在指定的父节点下添加子节点
      */
-    getHierarchyList(): Array<TreeNode<T>>;
+    batchAttachToParent(parent: TreeNode<T>, list: Array<T>): ITreeNode<T>[];
     /**
      * 增加一个新节点（便捷方法，会自动根据 parentKeyField 找到父节点）
      * @param item 要添加的节点数据
      */
-    append(item: T): void;
-    /**
-     * 获取除指定节点外的其他节点
-     * @param exclusiveData
-     */
-    extractDirectories(exclusiveData: T): TreeNode<T>[];
-    /**
-     * 获取所有展开的节点
-     * @param tree
-     * @private
-     */
-    private collectExpandedNodes;
+    append(item: T): ITreeNode<T>;
+    private findParent;
 }