@ticatec/uniface-element 0.3.18 → 0.3.19

package/dist/lib/TreeNode_README_CN.md

@@ -9,7 +9,7 @@
 ## TreeNode 类
 
 ```typescript
-class TreeNode<T> {
+class TreeNode<T> implements ITreeNode<T> {
   /** 节点的数据对象（只读） */
   public readonly item: T;
 
@@ -20,26 +20,26 @@ class TreeNode<T> {
   public loading: boolean;
 
   /** 父节点（根节点为 null） */
-  public parent: TreeNode<T> | null;
+  public readonly parent: TreeNode<T> | null;
 
-  /** 子节点（只读，使用方法修改） */
-  get children(): ReadonlyArray<TreeNode<T>>;
+  /** 节点层级（根节点为 0） */
+  get level(): number;
+
+  /** 子节点（浅拷贝，使用方法修改） */
+  get children(): Array<TreeNode<T>> | null;
 
   /** 添加子节点到当前节点 */
-  append(childItem: T): void;
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;
 
   /** 从父节点中分离（删除当前节点） */
   detach(): void;
 
-  /** 将当前节点移动到另一个父节点下 */
-  moveTo(newParent: TreeNode<T>): void;
+  /** 将当前节点移动到另一个父节点下（返回新节点） */
+  moveTo(newParent: TreeNode<T>): TreeNode<T>;
 
   /** 替换当前节点的数据 */
   replace(newItem: T): void;
 
-  /** 根据 ID 删除指定的子节点 */
-  removeChild(childId: any): void;
-
   /** 删除所有子节点 */
   removeChildren(): void;
 }
@@ -87,25 +87,33 @@ class NodeViewOptions<T> {
 
 ### 1. append(childItem)
 
-添加一个子节点到当前节点。
+添加子节点到当前节点。
 
 **参数**:
-- `childItem: T` - 子节点的数据对象
+- `childItem: T | Array<T>` - 子节点的数据对象或子对象数组
 
 **示例**:
 ```typescript
-// 直接传入数据对象
+// 添加单个子节点
 parentNode.append({
   id: 123,
   name: "新子节点",
   parentId: parentNode.item.id  // 会自动设置
 });
+
+// 添加多个子节点
+parentNode.append([
+  { id: 124, name: "子节点1", parentId: parentNode.item.id },
+  { id: 125, name: "子节点2", parentId: parentNode.item.id }
+]);
 ```
 
+**返回值**:
+- `ITreeNode<T> | Array<ITreeNode<T>>` - 添加的子节点
+
 **注意事项**:
 - 自动初始化 children 数组（如果需要）
 - 如果配置了排序函数，会自动排序
-- 父节点的 `expand` 会自动设置为 `true`
 - 触发版本更新以实现响应式更新
 
 ---
@@ -195,32 +203,7 @@ node.replace({
 
 ---
 
-### 5. removeChild(childId)
-
-删除指定的子节点。
-
-**参数**:
-- `childId: any` - 要删除的子节点的 ID
-
-**示例**:
-```typescript
-// 删除指定 ID 的子节点
-parentNode.removeChild(123);
-
-// 使用变量
-const childId = childNode.item.id;
-parentNode.removeChild(childId);
-```
-
-**注意事项**:
-- 只删除直接子节点，不会递归删除孙子节点
-- 如果子节点不存在，会静默忽略
-- 子节点的所有后代也会被删除
-- 触发版本更新以实现响应式更新
-
----
-
-### 6. removeChildren()
+### 5. removeChildren()
 
 删除所有子节点。
 
@@ -387,7 +370,6 @@ node.append(childItem);      // 添加子节点到该节点
 node.detach();               // 从父节点中分离该节点
 node.replace(newItem);       // 替换该节点的数据
 node.moveTo(newParentNode);  // 将该节点移动到另一个父节点
-node.removeChild(childId);   // 删除该节点的指定子节点
 node.removeChildren();       // 删除该节点的所有子节点
 ```
 
@@ -409,10 +391,10 @@ treeNodes.extractDirectories(item); // 提取目录结构（仅 TreeNodes）
 节点中存储的数据对象。不能直接修改。使用 `replace()` 来更新数据。
 
 ### children（只读）
-返回子节点的只读数组。要修改子节点，使用以下方法：
+返回子节点数组的浅拷贝。要修改子节点，使用以下方法：
 - `append()` - 添加子节点
-- `removeChild()` - 删除特定子节点
 - `removeChildren()` - 删除所有子节点
+- 要删除特定子节点，请遍历子节点并对子节点调用 `detach()` 方法
 
 ### expand
 控制节点是否展开（显示其子节点）。可以直接设置：

package/dist/lib/TreeNodes.d.ts

@@ -8,12 +8,6 @@ export declare function compareNumber(a: number, b: number): 0 | 1 | -1;
 /**
  * 节点视图配置类 - 定义节点的显示方式
  * @template T 节点数据的类型
- *
- * @example
- * const options = new NodeViewOptions<MyData>({
- *   keyField: 'id',
- *   textField: 'name'
- * });
  */
 export declare class NodeViewOptions<T> {
     /**
@@ -70,37 +64,20 @@ export interface ITreeNode<T> {
      * @returns 子节点数组，如果没有子节点返回 null
      */
     get children(): Array<ITreeNode<T>> | null;
-    /**
-     * 添加子节点
-     * @param childItem 子节点数据
-     * @returns 新创建的子节点
-     *
-     * @example
-     * const childNode = parentNode.append({ id: 1, name: "子节点" });
-     */
-    append(childItem: T): ITreeNode<T>;
+    append(childItem: T | Array<T>): ITreeNode<T> | Array<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;
     /**
@@ -109,15 +86,17 @@ export interface ITreeNode<T> {
     get item(): T;
     /**
      * 删除所有子节点
-     *
-     * @example
-     * node.removeChildren();
      */
     removeChildren(): void;
+    /**
+     * 获取父节点
+     */
+    parent: TreeNode<T> | null;
 }
 /**
- * TreeNode 类 - 树节点，包含数据和方法
+ * TreeNode 类 - 树节点，包含数据和方法（内部类）
  * @template T 节点数据的类型
+ * @internal
  *
  * @description
  * TreeNode 是树结构的基本单元，每个节点包含：
@@ -128,8 +107,10 @@ export interface ITreeNode<T> {
  * - 加载状态（loading）
  *
  * 节点提供了丰富的操作方法，可以直接在节点上进行增删改查操作。
+ *
+ * 注意：此类为内部实现，外部应使用 ITreeNode 接口
  */
-export declare class TreeNode<T> implements ITreeNode<T> {
+declare class TreeNode<T> implements ITreeNode<T> {
     /**
      * 节点数据（私有，只读）
      * @private
@@ -157,20 +138,15 @@ export declare class TreeNode<T> implements ITreeNode<T> {
      * @private
      */
     private _children;
+    private readonly nodes;
     /**
      * 创建树节点
      * @param item 节点数据
+     * @param nodes
      * @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);
+    constructor(item: T, nodes: TreeNodes<T>, parent?: TreeNode<T> | null, children?: Array<TreeNode<T>> | null);
     /**
      * 获取节点层级
      * @returns 层级值（根节点为 0）
@@ -179,28 +155,17 @@ export declare class TreeNode<T> implements ITreeNode<T> {
     /**
      * 获取子节点列表（只读）
      * @returns 子节点数组的浅拷贝，如果没有子节点返回 null
-     *
-     * @example
-     * const children = node.children;
-     * if (children) {
-     *   children.forEach(child => console.log(child.item));
-     * }
      */
     get children(): Array<TreeNode<T>> | null;
+    set children(value: Array<TreeNode<T>>);
     /**
      * 添加子节点
      * @param childItem 子节点数据
      * @returns 新创建的子节点
-     *
-     * @example
-     * const childNode = parentNode.append({ id: 1, name: "子节点" });
      */
-    append(childItem: T): TreeNode<T>;
+    append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;
     /**
      * 从父节点中分离（删除当前节点）
-     *
-     * @example
-     * node.detach();
      */
     detach(): void;
     /**
@@ -213,17 +178,11 @@ export declare class TreeNode<T> implements ITreeNode<T> {
      * 移动到另一个父节点下
      * @param newParent 新的父节点
      * @returns 新创建的节点（注意：返回的是新节点，不是原节点）
-     *
-     * @example
-     * node.moveTo(newParentNode);
      */
-    moveTo(newParent: TreeNode<T>): TreeNode<T>;
+    moveTo(newParent: TreeNode<T>): ITreeNode<T>;
     /**
      * 替换当前节点的数据
      * @param newItem 新的数据对象
-     *
-     * @example
-     * node.replace({ id: 1, name: "新名称", ...otherFields });
      */
     replace(newItem: T): void;
     /**
@@ -233,9 +192,6 @@ export declare class TreeNode<T> implements ITreeNode<T> {
     get item(): T;
     /**
      * 删除所有子节点
-     *
-     * @example
-     * node.removeChildren();
      */
     removeChildren(): void;
     /**
@@ -273,6 +229,9 @@ export type GetText<T> = (data: T) => string;
  * @template T 数据类型
  */
 export type CheckIsDirectory<T> = (node: ITreeNode<T>) => boolean;
+type StringKeys<T> = {
+    [K in keyof T]: T[K] extends string ? K : never;
+}[keyof T];
 /**
  * TreeNodes 配置选项
  * @template T 节点数据的类型
@@ -281,7 +240,7 @@ export interface TreeNodeOptions<T> {
     /**
      * 唯一标识字段名（默认：'id'）
      */
-    keyField?: keyof T;
+    keyField?: StringKeys<T>;
     /**
      * 显示文字的字段名或获取函数（默认：'text'）
      */
@@ -289,7 +248,7 @@ export interface TreeNodeOptions<T> {
     /**
      * 父节点引用字段名（默认：'parentId'）
      */
-    parentKeyField?: keyof T;
+    parentKeyField?: StringKeys<T>;
     /**
      * 判断数据是否为根节点的函数（必需）
      */
@@ -317,33 +276,11 @@ export interface TreeNodeOptions<T> {
  * - 节点的映射和查找
  * - 版本管理（用于响应式更新）
  * - 层级展开控制
- *
- * @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 keyField: StringKeys<T>;
+    protected readonly parentKeyField: StringKeys<T>;
     protected readonly textField: keyof T | GetText<T>;
     protected readonly checkIsDirectory: CheckIsDirectory<T> | undefined;
     protected nodeMap: Map<any, TreeNode<T>>;
@@ -367,19 +304,12 @@ export default class TreeNodes<T> {
      * 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>>;
+    get nodes(): Array<ITreeNode<T>>;
     /**
      * 获取版本号，用于触发 Svelte 响应式更新
      */
@@ -393,17 +323,38 @@ export default class TreeNodes<T> {
     protected setExpandForDepth(nodes: TreeNode<T>[], currentLevel: number): void;
     /**
      * 获取展开的展示列表
+     * @returns 展开的所有节点（按层级顺序）
      */
     getHierarchyList(): Array<ITreeNode<T>>;
-    private addExpandNodesToList;
     /**
-     * 不检测匹配情况，在指定的父节点下添加子节点
+     * 将展开的节点添加到列表
+     * @param nodes 节点数组
+     * @param list 结果列表
+     * @private
      */
-    batchAttachToParent(parent: TreeNode<T>, list: Array<T>): ITreeNode<T>[];
+    private addExpandNodesToList;
     /**
      * 增加一个新节点（便捷方法，会自动根据 parentKeyField 找到父节点）
      * @param item 要添加的节点数据
      */
     append(item: T): ITreeNode<T>;
-    private findParent;
+    replace(item: T): ITreeNode<T> | null;
+    remove(item: T): ITreeNode<T> | null;
+    /**
+     * 从节点列表中查找节点
+     * @param nodes 节点数组
+     * @param item 要查找的数据项
+     * @param matchedKey 匹配的字段名
+     * @returns 找到的节点或 null
+     * @private
+     */
+    private _findNodeFromList;
+}
+export declare class MenuNodes<T> extends TreeNodes<T> {
+    /**
+     * 删除所有属于分支但没有子节点的节点
+     */
+    protected cleanEmptyDirectories(): void;
+    private pruneEmptyDirs;
 }
+export {};