@ticatec/uniface-element 0.3.15 → 0.3.16

package/dist/lib/TreeNode_README_CN.md

@@ -0,0 +1,449 @@
+# TreeNode - 树节点数据结构
+
+## 概述
+
+`TreeNode` 是用于表示树形结构中节点的核心数据类型。它包含了节点的数据、子节点、展开状态等信息，并提供了便捷的方法来操作节点本身和其子节点。
+
+每个从 `TreeNodes` 获取的节点都自动绑定了操作方法，可以直接调用。
+
+## 类型定义
+
+```typescript
+interface TreeNode<T> {
+  /** 节点的数据对象 */
+  item: T;
+
+  /** 是否展开（显示子节点） */
+  expand?: boolean;
+
+  /** 子节点数组 */
+  children?: TreeNode<T>[];
+}
+```
+
+### TreeNodeWithMethods<T>
+
+这是实际使用的节点类型，继承了 `TreeNode<T>` 并添加了操作方法：
+
+```typescript
+interface TreeNodeWithMethods<T> extends TreeNode<T> {
+  /** 添加子节点到当前节点 */
+  append: (childItem: T) => void;
+
+  /** 删除当前节点（从父节点中移除） */
+  remove: () => void;
+
+  /** 替换当前节点的数据 */
+  replace: (newItem: T) => void;
+
+  /** 将当前节点移动到另一个父节点下 */
+  moveTo: (newParentId: string) => void;
+
+  /** 删除指定的子节点 */
+  removeChild: (childId: any) => void;
+
+  /** 删除所有子节点 */
+  removeChildren: () => void;
+}
+```
+
+## 节点方法详解
+
+### 1. append(childItem)
+
+添加一个子节点到当前节点。
+
+**参数**:
+- `childItem: T` - 子节点的数据对象
+
+**示例**:
+```typescript
+// 直接传入数据对象
+parentNode.append({
+  id: 123,
+  name: "新子节点",
+  parent: parentNode.item.id  // 可选，会自动设置
+});
+```
+
+**注意事项**:
+- **自动加载 lazy 节点**：当节点被选中（点击或外部设置 `activeNode`）时，如果是 lazy 节点且未加载（`children === null`），TreeView 会自动触发 `lazyLoader.load()` 加载子节点
+- **手动添加子节点**：可以手动调用 `append()` 添加子节点
+  - 如果节点还未加载，会自动初始化 `children` 数组
+  - 节点会从 leaf 转为 branch，UI 会显示 branch 图标
+- 如果配置了排序函数，会自动排序
+- 父节点的 `expand` 会自动设置为 `true`
+
+---
+
+### 2. remove()
+
+删除当前节点（从其父节点中移除）。
+
+**参数**: 无
+
+**示例**:
+```typescript
+// 删除节点
+node.remove();
+
+// 删除后清空引用
+activeNode.remove();
+activeNode = null;
+```
+
+**注意事项**:
+- 从父节点的 `children` 数组中移除
+- 从内部映射表中删除
+- 如果是根节点，从根节点列表中移除
+
+---
+
+### 3. replace(newItem)
+
+替换当前节点的数据。
+
+**参数**:
+- `newItem: T` - 新的数据对象
+
+**示例**:
+```typescript
+// 更新节点的部分字段
+node.replace({
+  ...node.item,        // 保持其他字段
+  name: "新的名称",     // 更新名称
+  status: "active"     // 更新状态
+});
+
+// 或完全替换
+node.replace({
+  id: node.item.id,    // 必须保持 ID
+  name: "完全新的数据",
+  newField: "值"
+});
+```
+
+**注意事项**:
+- 通常需要保持 `id` 字段不变
+- 如果配置了排序函数且排序字段改变，会自动重新排序
+- 会自动触发视图更新
+
+---
+
+### 4. moveTo(newParentId)
+
+将当前节点移动到另一个父节点下。
+
+**参数**:
+- `newParentId: string | number` - 新父节点的 ID
+
+**示例**:
+```typescript
+// 移动到指定的父节点
+node.moveTo("parent-123");
+
+// 使用另一个节点的 ID
+node.moveTo(anotherNode.item.id);
+```
+
+**注意事项**:
+- 会自动更新节点的 `parent` 字段
+- 从原父节点的 `children` 中移除
+- 添加到新父节点的 `children`
+- **Lazy 节点处理**：如果新父节点是 lazy-loaded 且未加载（`children === null`），会自动初始化 `children` 数组
+  - 新父节点会从 leaf 转为 branch，UI 会显示 branch 图标
+  - 未来用户展开节点时，lazyLoader 加载的子节点会与移动过来的节点合并
+
+---
+
+### 5. removeChild(childId)
+
+删除指定的子节点。
+
+**参数**:
+- `childId: any` - 要删除的子节点的 ID
+
+**示例**:
+```typescript
+// 删除指定 ID 的子节点
+parentNode.removeChild(123);
+
+// 使用变量
+const childId = childNode.item.id;
+parentNode.removeChild(childId);
+```
+
+**注意事项**:
+- 只删除直接子节点，不会递归删除孙子节点
+- 如果子节点不存在，会静默忽略
+- 子节点的所有后代也会被删除
+
+---
+
+### 6. removeChildren()
+
+删除所有子节点。
+
+**参数**: 无
+
+**示例**:
+```typescript
+// 清空所有子节点
+parentNode.removeChildren();
+
+// 删除后添加新节点
+parentNode.removeChildren();
+parentNode.append(newChildData);
+```
+
+**注意事项**:
+- 会删除所有子节点及其后代
+- 节点本身的 `expand` 状态保持不变
+- 内部映射表会同步更新
+
+## 完整使用示例
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
+
+  // 数据类型定义
+  interface MyData {
+    id: number;
+    name: string;
+    parent: number | null;
+  }
+
+  let activeNode: TreeNodeWithMethods<MyData> | null = null;
+
+  // 创建树结构
+  const treeNodes = new TreeNodes<MyData>({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.children != null
+  });
+
+  // 初始化数据
+  treeNodes.setData([
+    { id: 1, name: "根节点", parent: null },
+    { id: 2, name: "子节点1", parent: 1 },
+    { id: 3, name: "子节点2", parent: 1 }
+  ]);
+
+  // 添加子节点
+  function addChild() {
+    if (!activeNode) return;
+
+    activeNode.append({
+      id: Date.now(),
+      name: "新子节点",
+      parent: activeNode.item.id
+    });
+  }
+
+  // 删除当前节点
+  function deleteCurrentNode() {
+    if (!activeNode) return;
+    activeNode.remove();
+    activeNode = null;
+  }
+
+  // 删除指定子节点
+  function deleteChild(childId: number) {
+    if (!activeNode) return;
+    activeNode.removeChild(childId);
+  }
+
+  // 清空所有子节点
+  function clearChildren() {
+    if (!activeNode) return;
+    activeNode.removeChildren();
+  }
+
+  // 重命名节点
+  function renameNode(newName: string) {
+    if (!activeNode) return;
+    activeNode.replace({
+      ...activeNode.item,
+      name: newName
+    });
+  }
+
+  // 移动节点
+  function moveNodeTo(newParentId: number) {
+    if (!activeNode) return;
+    activeNode.moveTo(newParentId);
+  }
+</script>
+
+<div>
+  <TreeView
+    nodes={treeNodes.nodes}
+    version={treeNodes.version}
+    textField="name"
+    bind:activeNode
+    checkIsDirectory={(node) => node.children != null}
+  />
+
+  {#if activeNode}
+    <div class="node-actions">
+      <h3>当前选中: {activeNode.item.name}</h3>
+      <button on:click={addChild}>添加子节点</button>
+      <button on:click={deleteCurrentNode}>删除节点</button>
+      <button on:click={() => renameNode("新名称")}>重命名</button>
+      <button on:click={() => moveNodeTo(1)}>移动到根节点</button>
+      <button on:click={clearChildren}>清空子节点</button>
+    </div>
+  {/if}
+</div>
+```
+
+## 与 TreeNodes 类方法的区别
+
+`TreeNode` 的方法和 `TreeNodes` 类的方法有明确的职责分工：
+
+### TreeNode 节点方法（推荐用于操作特定节点）
+
+```typescript
+// 直接在节点上操作 - 推荐用于已知节点实例的场景
+node.append(childItem);      // 添加子节点到该节点
+node.remove();               // 删除该节点
+node.replace(newItem);       // 替换该节点的数据
+node.moveTo(newParentId);    // 移动该节点
+node.removeChild(childId);   // 删除该节点的指定子节点
+node.removeChildren();       // 删除该节点的所有子节点
+```
+
+### TreeNodes 类方法（用于批量操作或初始化）
+
+```typescript
+// 类级别操作 - 适合只知道数据的场景
+treeNodes.setData(data);           // 初始化树结构
+treeNodes.append(item);            // 添加新节点（自动找父节点）
+treeNodes.nodes;                   // 获取根节点列表
+treeNodes.version;                 // 获取版本号
+treeNodes.getHierarchyList();      // 获取展开的节点列表
+treeNodes.extractDirectories(item); // 提取目录结构
+```
+
+## 响应式更新
+
+所有的节点方法操作都会自动触发 `version` 更新，确保 Svelte 组件能够响应数据变化：
+
+```svelte
+<TreeView
+  nodes={treeNodes.nodes}
+  version={treeNodes.version}  ← 自动更新
+  ...
+/>
+```
+
+你不需要手动触发更新，节点方法会自动处理。
+
+## 常见问题
+
+### Q: 如何获取节点实例？
+
+```typescript
+// 方式1: 通过 activeNode（选中节点）
+let activeNode: TreeNode | null = null;
+<TreeView bind:activeNode />
+
+// 方式2: 通过 nodeMap（需要保留 TreeNodes 引用）
+const node = treeNodes.nodeMap.get(nodeId);
+```
+
+### Q: 如何遍历子节点？
+
+```typescript
+if (node.children) {
+  node.children.forEach(child => {
+    console.log(child.item.name);
+  });
+}
+```
+
+### Q: 如何查找特定子节点？
+
+```typescript
+function findChild(node: TreeNode, childId: number) {
+  if (!node.children) return null;
+  return node.children.find(child => child.item.id === childId) || null;
+}
+```
+
+### Q: Lazy-loaded 节点如何工作？
+
+对于使用 lazyLoader 的节点（`children === null`）：
+
+```typescript
+// ✅ 当节点被选中时，TreeView 会自动触发加载
+// 点击节点或设置 activeNode 时：
+// - 如果是 lazy 节点且未加载
+// - 自动调用 lazyLoader.load()
+// - children 被设置，节点转为 branch
+
+// 手动添加子节点
+lazyNode.append(childItem);     // 初始化 children 数组并添加子节点
+                                // 节点转为 branch，显示 branch 图标
+
+lazyNode.moveTo(parentId);      // 移动到该节点会自动初始化 children
+
+// removeChild() 和 removeChildren() 在加载前无效果
+lazyNode.removeChild(id);       // children 为 null 时无效果
+lazyNode.removeChildren();      // children 为 null 时无效果
+```
+
+### Q: 如何递归操作所有子孙节点？
+
+```typescript
+function traverse(node: TreeNode, callback: (node: TreeNode) => void) {
+  callback(node);
+  if (node.children) {
+    node.children.forEach(child => traverse(child, callback));
+  }
+}
+
+// 使用
+traverse(rootNode, (node) => {
+  console.log(node.item.name);
+  node.expand = true;  // 展开所有节点
+});
+```
+
+## 最佳实践
+
+1. **优先使用节点方法**：当你有节点实例时，直接调用节点方法更直观
+
+2. **保持 ID 不变**：使用 `replace()` 时，确保 `id` 字段保持不变
+
+3. **检查 children 存在性**：操作子节点前，先检查 `node.children` 是否存在
+
+4. **处理 lazy 节点**：对于 lazy-loaded 节点，先等待加载完成再操作
+
+5. **版本管理**：不需要手动管理版本，节点方法会自动更新
+
+6. **类型安全**：使用 TypeScript 泛型确保类型安全
+
+```typescript
+// ✅ 推荐：使用泛型
+const treeNodes = new TreeNodes<MyData>({ ... });
+
+// 节点会自动推断类型
+node.append({ id: 1, name: "..." });  // 类型检查
+```
+
+## 性能考虑
+
+- 所有节点方法的时间复杂度都是 O(1) 或 O(n)，其中 n 是子节点数量
+- 删除操作会同时从内部映射表中移除，保持一致性
+- 大批量操作时，考虑直接使用 `setData()` 重建树结构
+
+## 相关组件
+
+- `TreeNodes` - 树管理类
+- `TreeView` - 树视图组件
+- `LazyLoader` - 延迟加载接口

package/dist/lib/TreeNodes.d.ts

@@ -17,22 +17,105 @@ export interface TreeNodeOptions<T> {
     compareFun?: CompareFun<T>;
     expendDepth?: number;
 }
+export type TreeNodeWithMethods<T> = TreeNode<T> & {
+    /**
+     * 添加子节点到当前节点
+     * @param childItem 子节点的数据（直接传入数据对象，不需要包装成 TreeNode）
+     *
+     * @example
+     * // 直接传入数据对象
+     * parentNode.append({ id: 1, name: "子节点" });
+     */
+    append: (childItem: T) => void;
+    /**
+     * 删除当前节点（从父节点中移除）
+     *
+     * @example
+     * node.remove();
+     */
+    remove: () => void;
+    /**
+     * 替换当前节点的数据
+     * @param newItem 新的数据对象（直接传入数据对象，不需要包装成 TreeNode）
+     *
+     * @example
+     * node.replace({ id: 1, name: "新名称", ...otherFields });
+     */
+    replace: (newItem: T) => void;
+    /**
+     * 将当前节点移动到另一个父节点下
+     * @param newParentId 新父节点的 ID（根据 keyField 指定的字段）
+     *
+     * @example
+     * node.moveTo("parent-123");
+     */
+    moveTo: (newParentId: string) => void;
+    /**
+     * 删除指定的子节点
+     * @param childId 子节点的 ID（根据 keyField 指定的字段）
+     *
+     * @example
+     * node.removeChild(123);
+     */
+    removeChild: (childId: any) => void;
+    /**
+     * 删除所有子节点
+     *
+     * @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, TreeNode<T>>;
+    protected nodeMap: Map<any, TreeNodeWithMethods<T>>;
     protected compareFun: any | undefined;
     protected expendDepth: number;
-    protected _nodes: Array<TreeNode<T>>;
+    protected _nodes: Array<TreeNodeWithMethods<T>>;
+    protected _version: number;
     constructor(options: TreeNodeOptions<T>);
+    protected touch(): void;
+    /**
+     * 创建带有方法的节点
+     */
+    protected createNodeWithMethods(item: T): TreeNodeWithMethods<T>;
+    /**
+     * 添加子节点到指定节点
+     */
+    protected addNodeToNode(parentNode: TreeNodeWithMethods<T>, childItem: T): void;
+    /**
+     * 删除指定节点
+     */
+    protected removeNode(node: TreeNodeWithMethods<T>): void;
+    /**
+     * 替换节点的数据
+     */
+    protected replaceNodeItem(node: TreeNodeWithMethods<T>, newItem: T): void;
+    /**
+     * 将节点移动到新的父节点下
+     */
+    protected moveNodeTo(node: TreeNodeWithMethods<T>, newParentId: string): void;
+    /**
+     * 删除指定节点的某个子节点
+     */
+    protected removeChildNode(parentNode: TreeNodeWithMethods<T>, childId: any): void;
+    /**
+     * 删除指定节点的所有子节点
+     */
+    protected removeChildrenNodes(parentNode: TreeNodeWithMethods<T>): void;
     setData(list: Array<T>): void;
     /**
      * 获取节点
      */
     get nodes(): Array<TreeNode<T>>;
+    /**
+     * 获取版本号，用于触发 Svelte 响应式更新
+     */
+    get version(): number;
     /**
      * 设置展开层级
      * @param nodes
@@ -46,7 +129,7 @@ export declare class CommonTreeNodes<T> {
      * @param doSort
      * @protected
      */
-    protected appendNode(node: TreeNode<T>, doSort?: boolean): void;
+    protected appendNode(node: TreeNodeWithMethods<T>, doSort?: boolean): void;
 }
 export default class TreeNodes<T> extends CommonTreeNodes<T> {
     /**
@@ -54,26 +137,10 @@ export default class TreeNodes<T> extends CommonTreeNodes<T> {
      */
     getHierarchyList(): Array<TreeNode<T>>;
     /**
-     * 给treeview设定数据，根据数据构建树结构
-     * @param list
-     */
-    /**
-     * 增加一个新节点
-     * @param item
+     * 增加一个新节点（便捷方法，会自动根据 parentKeyField 找到父节点）
+     * @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