@ticatec/uniface-element 0.3.15 → 0.3.17

package/dist/lib/TreeNodes.d.ts

@@ -1,23 +1,346 @@
+/**
+ * 比较两个数字
+ * @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>[];
-};
+/**
+ * 节点视图配置类 - 定义节点的显示方式
+ * @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;
+}
+/**
+ * 树节点接口
+ * @template T 节点数据的类型
+ */
+export interface ITreeNode<T> {
+    /**
+     * 是否展开（显示子节点）
+     */
+    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
+     * node.detach();
+     */
+    detach(): void;
+    /**
+     * 移动到另一个父节点下
+     * @param newParent 新的父节点
+     * @returns 当前节点（支持链式调用）
+     *
+     * @example
+     * node.moveTo(newParentNode);
+     */
+    moveTo(newParent: ITreeNode<T>): ITreeNode<T>;
+    /**
+     * 替换当前节点的数据
+     * @param newItem 新的数据对象
+     *
+     * @example
+     * node.replace({ id: 1, name: "新名称", ...otherFields });
+     */
+    replace(newItem: T): void;
+    /**
+     * 获取节点的数据
+     */
+    get item(): T;
+    /**
+     * 删除所有子节点
+     *
+     * @example
+     * node.removeChildren();
+     */
+    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 node 要删除的子节点
+     * @private
+     */
+    private removeNode;
+    /**
+     * 移动到另一个父节点下
+     * @param newParent 新的父节点
+     * @returns 新创建的节点（注意：返回的是新节点，不是原节点）
+     *
+     * @example
+     * node.moveTo(newParentNode);
+     */
+    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;
+    /**
+     * @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;
-export type CheckIsDirectory<T> = (node: TreeNode<T>) => boolean;
+/**
+ * 判断节点是否为分支（有子节点）的函数类型
+ * @template T 数据类型
+ */
+export type CheckIsDirectory<T> = (node: ITreeNode<T>) => boolean;
+/**
+ * TreeNodes 配置选项
+ * @template T 节点数据的类型
+ */
 export interface TreeNodeOptions<T> {
+    /**
+     * 唯一标识字段名（默认：'id'）
+     */
     keyField?: keyof T;
+    /**
+     * 显示文字的字段名或获取函数（默认：'text'）
+     */
     textField?: keyof T | GetText<T>;
+    /**
+     * 父节点引用字段名（默认：'parentId'）
+     */
     parentKeyField?: keyof T;
+    /**
+     * 判断数据是否为根节点的函数（必需）
+     */
     checkIsRoot: CheckIsRoot<T>;
+    /**
+     * 判断节点是否为分支的函数（可选）
+     */
     checkIsDirectory?: CheckIsDirectory<T>;
+    /**
+     * 排序比较函数（可选）
+     */
     compareFun?: CompareFun<T>;
+    /**
+     * 默认展开深度（默认：1）
+     */
     expendDepth?: number;
 }
-export declare class CommonTreeNodes<T> {
+/**
+ * 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;
@@ -27,12 +350,40 @@ export declare class CommonTreeNodes<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 }
+     * ]);
+     */
     setData(list: Array<T>): void;
     /**
      * 获取节点
      */
     get nodes(): Array<TreeNode<T>>;
+    /**
+     * 获取版本号，用于触发 Svelte 响应式更新
+     */
+    get version(): number;
     /**
      * 设置展开层级
      * @param nodes
@@ -40,49 +391,19 @@ export declare class CommonTreeNodes<T> {
      * @protected
      */
     protected setExpandForDepth(nodes: TreeNode<T>[], currentLevel: number): void;
-    /**
-     * 添加一个节点
-     * @param node
-     * @param doSort
-     * @protected
-     */
-    protected appendNode(node: TreeNode<T>, doSort?: boolean): void;
-}
-export default class TreeNodes<T> extends CommonTreeNodes<T> {
     /**
      * 获取展开的展示列表
      */
-    getHierarchyList(): Array<TreeNode<T>>;
+    getHierarchyList(): Array<ITreeNode<T>>;
+    private addExpandNodesToList;
     /**
-     * 给treeview设定数据，根据数据构建树结构
-     * @param list
+     * 不检测匹配情况，在指定的父节点下添加子节点
      */
+    batchAttachToParent(parent: TreeNode<T>, list: Array<T>): ITreeNode<T>[];
     /**
-     * 增加一个新节点
-     * @param item
-     */
-    append(item: T): void;
-    /**
-     * 替换一个节点的数据
-     * @param item
-     */
-    replace(item: T): void;
-    remove(item: T): void;
-    /**
-     * 将一个节点移动到另外一个节点下
-     * @param item
-     * @param parentId
-     */
-    moveTo(item: T, parentId: string): void;
-    /**
-     * 获取除指定节点外的其他节点
-     * @param exclusiveData
-     */
-    extractDirectories(exclusiveData: T): TreeNode<T>[];
-    /**
-     * 获取所有展开的节点
-     * @param tree
-     * @private
+     * 增加一个新节点（便捷方法，会自动根据 parentKeyField 找到父节点）
+     * @param item 要添加的节点数据
      */
-    private collectExpandedNodes;
+    append(item: T): ITreeNode<T>;
+    private findParent;
 }