react-extjs 0.0.1

package/src/components/Tree.tsx

@@ -0,0 +1,809 @@
+/**
+ * Ext.tree.TreePanel / TreeNode 保真复刻（来源 src/widgets/tree/TreePanel.js、TreeNode.js、TreeNodeUI.js）。
+ *
+ * 保真契约（DOM/class 严格对齐源码）：
+ *  - 面板根：ul.x-tree-root-ct（+ x-tree-lines / x-tree-arrows / x-tree-no-lines），外层 x-tree 落在 panel body 上。
+ *  - 节点 li.x-tree-node
+ *      > div.x-tree-node-el
+ *          > span.x-tree-node-indent（祖先缩进：祖先非末位→x-tree-elbow-line，末位→x-tree-icon）
+ *          > img.x-tree-ec-icon（自身展开/折叠柄：elbow[-end][-plus/-minus]）
+ *          > img.x-tree-node-icon（folder/folder-open/leaf 由 CSS 按 x-tree-node-* 状态取背景图）
+ *          > [可选] input.x-tree-node-cb（复选框）
+ *          > a.x-tree-node-anchor > span（文字）
+ *      > ul.x-tree-node-ct（子节点；展开 block / 折叠 none）
+ *  - 节点 el 状态 class：x-tree-node-leaf / x-tree-node-expanded / x-tree-node-collapsed / x-tree-node-over / x-tree-selected / x-tree-node-disabled
+ *  - ec-icon：自身末位→x-tree-elbow-end，否则 x-tree-elbow；有子或 expandable 时追加 -plus(折叠)/-minus(展开)
+ *
+ * 交互（行为契约）：
+ *  - 展开/折叠：点击 ec-icon 切换 expanded（翻转 el 的 expanded/collapsed、ec-icon 的 plus/minus、ct 的 display）
+ *  - 选中：点击节点 → 加 x-tree-selected（同级唯一），移除兄弟选中 —— CSS 给 #d9e8fb 背景
+ *  - 悬停：onMouseEnter 加 x-tree-node-over，onMouseLeave 移除 —— CSS 给 #eee 背景
+ *  - 禁用：x-tree-node-disabled 灰字 + 图标半透明，不可选中/展开
+ * 说明：over/selected 背景是 CSS 对 class 的着色，与 combo 一样靠 JS 切 class（非 :hover 默认），此处复刻为 React 状态。
+ */
+import { useState, useRef, useMemo, forwardRef, useImperativeHandle, type CSSProperties } from 'react';
+
+const BLANK_IMG = '/extjs-assets/images/default/s.gif';
+
+export interface TreeNodeData {
+  id: string;
+  text: string;
+  /** 自定义图标 class（加到 node-icon 上，由 CSS 提供背景图） */
+  iconCls?: string;
+  /** 图标图片路径（覆盖默认 folder/leaf 图标） */
+  icon?: string;
+  /** 初始是否展开 */
+  expanded?: boolean;
+  /** 强制显示 +/- 展开柄（即使无子节点） */
+  expandable?: boolean;
+  /** 初始是否禁用 */
+  disabled?: boolean;
+  /** 复选框：true 渲染选中框，false 渲染未选框，undefined 不渲染 */
+  checked?: boolean;
+  /** 附加 class（落在 x-tree-node-el 上） */
+  cls?: string;
+  /** 子节点 */
+  children?: TreeNodeData[];
+}
+
+export interface TreePanelProps {
+  /** 是否显示根节点，默认 true（与 Ext 默认一致）。false 时直接渲染 root.children。 */
+  rootVisible?: boolean;
+  /** 是否显示连接线，默认 true（x-tree-lines）。false 且无 useArrows → x-tree-no-lines。 */
+  lines?: boolean;
+  /** 使用箭头样式替代 +/-（x-tree-arrows） */
+  useArrows?: boolean;
+  /** 根节点数据（rootVisible:false 时仅用其 children） */
+  root?: TreeNodeData;
+  /** 顶层节点（与 root 二选一；提供时等效于 rootVisible:false） */
+  nodes?: TreeNodeData[];
+  /** 选中回调 */
+  onSelect?: (node: TreeNodeData) => void;
+  /** 展开/折叠回调 */
+  onExpand?: (node: TreeNodeData, expanded: boolean) => void;
+  /**
+   * 异步子节点加载器：当展开一个 expandable 但尚无子节点的节点时调用，
+   * 返回的子节点将在 resolve 后写入并展开（等价于 Ext AsyncTreeNode / TreeLoader）。
+   */
+  loader?: (node: TreeNodeData) => Promise<TreeNodeData[]>;
+  /**
+   * 启用节点拖拽重排（对齐 Ext TreePanel enableDD）。拖动节点可在同级间「上方/下方」移动，
+   * 拖到文件夹节点的中部区域则「作为其子节点」插入。仅对静态树生效（含异步加载的树不重排异步子树）。
+   */
+  enableNodeReorder?: boolean;
+  /** 节点重排完成回调（dragId, targetId, mode） */
+  onNodeMove?: (dragId: string, targetId: string, mode: 'above' | 'below' | 'append') => void;
+  /** 允许内联改名（双击节点或命令式 startEdit 触发，等价 Ext.tree.TreeEditor） */
+  editable?: boolean;
+  /** 内联改名提交回调（等价 TreeEditor 的 onComplete） */
+  onRename?: (id: string, text: string) => void;
+  style?: CSSProperties;
+}
+
+interface RenderCtx {
+  lines: boolean;
+  useArrows: boolean;
+  selectedId: string | null;
+  expandedIds: Record<string, boolean>;
+  ancestorsLast: boolean[];
+  onSelect: (node: TreeNodeData) => void;
+  onToggle: (id: string, node: TreeNodeData) => void;
+  /** 取节点的有效子节点（含异步加载后写入的子节点覆盖） */
+  getChildren: (node: TreeNodeData) => TreeNodeData[] | undefined;
+  /** 节点是否正在异步加载子节点 */
+  isLoading: (id: string) => boolean;
+  /** 取节点的勾选状态（含级联后写入的覆盖） */
+  getChecked: (node: TreeNodeData) => boolean;
+  /** 勾选切换（含父子级联） */
+  onCheck: (node: TreeNodeData, checked: boolean) => void;
+  /** 是否启用节点拖拽重排 */
+  enableNodeReorder: boolean;
+  /** 当前拖拽落点高亮节点 id（append 模式） */
+  dropTargetId: string | null;
+  /** 当前拖拽落点模式 */
+  dropMode: 'above' | 'below' | 'append' | null;
+  /** 当前拖拽插入落点（above/below 模式）：供节点 el 挂原生 x-tree-drag-insert-* 类 */
+  insertTarget: { id: string; mode: 'above' | 'below' } | null;
+  /** 节点 el 鼠标按下：发起拖拽 */
+  onNodeMouseDown: (id: string, e: React.MouseEvent) => void;
+  /** 是否允许内联改名 */
+  editable: boolean;
+  /** 当前正在改名的节点 id（null 表示无） */
+  editingId: string | null;
+  /** 进入改名态（传入 '' 取消当前改名） */
+  startEdit: (id: string) => void;
+  /** 提交改名（写回并退出改名态） */
+  commitRename: (id: string, text: string) => void;
+}
+
+// ---- 节点拖拽重排：树结构操作工具（纯函数，返回新树，不修改入参） ----
+function findNode(nodes: TreeNodeData[], id: string): TreeNodeData | null {
+  for (const n of nodes) {
+    if (n.id === id) return n;
+    if (n.children) {
+      const f = findNode(n.children, id);
+      if (f) return f;
+    }
+  }
+  return null;
+}
+
+function cloneTree(nodes: TreeNodeData[]): TreeNodeData[] {
+  return nodes.map((n) => ({ ...n, children: n.children ? cloneTree(n.children) : n.children }));
+}
+
+function removeNode(nodes: TreeNodeData[], id: string): TreeNodeData | null {
+  for (let i = 0; i < nodes.length; i++) {
+    if (nodes[i].id === id) {
+      const [r] = nodes.splice(i, 1);
+      return r;
+    }
+    if (nodes[i].children) {
+      const r = removeNode(nodes[i].children!, id);
+      if (r) return r;
+    }
+  }
+  return null;
+}
+
+function getSiblingsAndIndex(
+  nodes: TreeNodeData[],
+  id: string,
+): { siblings: TreeNodeData[]; index: number } | null {
+  for (const n of nodes) {
+    const idx = n.children?.findIndex((c) => c.id === id);
+    if (idx !== undefined && idx >= 0) return { siblings: n.children!, index: idx };
+    if (n.children) {
+      const r = getSiblingsAndIndex(n.children, id);
+      if (r) return r;
+    }
+  }
+  return null;
+}
+
+/** 将 dragId 节点移动到 targetId 节点的上方/下方（同级重排） */
+function moveSibling(
+  tree: TreeNodeData[],
+  dragId: string,
+  targetId: string,
+  mode: 'above' | 'below',
+): TreeNodeData[] {
+  const t = cloneTree(tree);
+  // 不能拖入自身子树
+  const dragNode = findNode(t, dragId);
+  if (!dragNode) return tree;
+  if (dragId === targetId) return tree;
+  const targetNode = findNode(t, targetId);
+  if (!targetNode) return tree;
+  // 判断 target 是否位于 drag 子树内
+  if (dragNode.children && findNode(dragNode.children, targetId)) return tree;
+  const drag = removeNode(t, dragId);
+  if (!drag) return tree;
+  const si = getSiblingsAndIndex(t, targetId);
+  const siblings = si ? si.siblings : t;
+  const idx = siblings.findIndex((s) => s.id === targetId);
+  const insertAt = mode === 'above' ? idx : idx + 1;
+  siblings.splice(insertAt, 0, drag);
+  return t;
+}
+
+/** 将 dragId 节点作为 targetId 文件夹节点的子节点追加 */
+function moveInto(tree: TreeNodeData[], dragId: string, targetId: string): TreeNodeData[] {
+  const t = cloneTree(tree);
+  const dragNode = findNode(t, dragId);
+  if (!dragNode || dragId === targetId) return tree;
+  if (dragNode.children && findNode(dragNode.children, targetId)) return tree;
+  const drag = removeNode(t, dragId);
+  if (!drag) return tree;
+  const target = findNode(t, targetId);
+  if (!target) return tree;
+  target.children = target.children ?? [];
+  target.expanded = true;
+  target.expandable = true;
+  target.children.push(drag);
+  return t;
+}
+
+/** 纯函数：将 node 追加为 parentId（null = 根层）的子节点，返回新树 */
+function appendChildPure(tree: TreeNodeData[], parentId: string | null, node: TreeNodeData): TreeNodeData[] {
+  if (parentId === null) return [...tree, node];
+  const t = cloneTree(tree);
+  const p = findNode(t, parentId);
+  if (!p) return tree;
+  p.children = p.children ?? [];
+  p.children.push(node);
+  p.expandable = true;
+  return t;
+}
+
+/** 纯函数：删除 id 对应节点，返回新树（不修改入参） */
+function removeNodePure(nodes: TreeNodeData[], id: string): TreeNodeData[] {
+  const out: TreeNodeData[] = [];
+  for (const n of nodes) {
+    if (n.id === id) continue;
+    const kids = n.children ? removeNodePure(n.children, id) : n.children;
+    out.push({ ...n, children: kids });
+  }
+  return out;
+}
+
+/** 纯函数：在 targetId 之前插入 node，返回新树 */
+function insertBeforePure(nodes: TreeNodeData[], targetId: string, node: TreeNodeData): TreeNodeData[] {
+  const out: TreeNodeData[] = [];
+  for (const n of nodes) {
+    if (n.id === targetId) out.push(node);
+    const kids = n.children ? insertBeforePure(n.children, targetId, node) : n.children;
+    out.push({ ...n, children: kids });
+  }
+  return out;
+}
+
+/** 纯函数：合并 partial 到 id 节点，返回新树 */
+function updateNodePure(nodes: TreeNodeData[], id: string, partial: Partial<TreeNodeData>): TreeNodeData[] {
+  return nodes.map((n) => {
+    if (n.id === id) return { ...n, ...partial };
+    const kids = n.children ? updateNodePure(n.children, id, partial) : n.children;
+    return { ...n, children: kids };
+  });
+}
+
+function collectInitialExpanded(nodes: TreeNodeData[], acc: Record<string, boolean>) {
+  for (const n of nodes) {
+    if (n.expanded) acc[n.id] = true;
+    if (n.children) collectInitialExpanded(n.children, acc);
+  }
+}
+
+function collectInitialChecked(nodes: TreeNodeData[], acc: Record<string, boolean>) {
+  for (const n of nodes) {
+    if (n.checked !== undefined) acc[n.id] = !!n.checked;
+    if (n.children) collectInitialChecked(n.children, acc);
+  }
+}
+
+function TreeBranch({ node, isLast, ctx }: { node: TreeNodeData; isLast: boolean; ctx: RenderCtx }) {
+  const [hovered, setHovered] = useState(false);
+
+  const effectiveChildren = ctx.getChildren(node);
+  const hasChildren = !!(effectiveChildren && effectiveChildren.length);
+  const loading = ctx.isLoading(node.id);
+  const expandable = hasChildren || node.expandable === true || loading;
+  const expanded = !!ctx.expandedIds[node.id];
+  const selected = ctx.selectedId === node.id;
+  const disabled = !!node.disabled;
+
+  // 拖拽落点：append → 原生 x-tree-drag-append 类（节点高亮）；above/below → 原生
+  // x-tree-drag-insert-above/below 类（点状主题色边框）。均复用原生树拖拽落点机制，不写死颜色。
+  const isDropAppendTarget =
+    ctx.enableNodeReorder && ctx.dropTargetId === node.id && ctx.dropMode === 'append';
+  const isDropInsertTarget = ctx.enableNodeReorder && ctx.insertTarget?.id === node.id;
+
+  // 节点 el 状态 class：可展开（有子或显式 expandable）即为 folder，否则 leaf
+  const elCls = [
+    'x-tree-node-el',
+    expandable ? (expanded ? 'x-tree-node-expanded' : 'x-tree-node-collapsed') : 'x-tree-node-leaf',
+    hovered && !disabled ? 'x-tree-node-over' : '',
+    selected ? 'x-tree-selected' : '',
+    disabled ? 'x-tree-node-disabled' : '',
+    loading ? 'x-tree-node-loading' : '',
+    'x-unselectable',
+    node.cls || '',
+    isDropAppendTarget ? 'x-tree-drag-append' : '',
+    isDropInsertTarget ? `x-tree-drag-insert-${ctx.insertTarget!.mode}` : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // ec-icon（展开/折叠柄）：自身末位决定 elbow / elbow-end，有子或 expandable 决定 +/- 后缀
+  const ecBase = isLast ? 'x-tree-elbow-end' : 'x-tree-elbow';
+  const ecSuffix = expandable ? (expanded ? '-minus' : '-plus') : '';
+  const ecCls = ['x-tree-ec-icon', `${ecBase}${ecSuffix}`].join(' ');
+
+  // 图标 class
+  const iconCls = [
+    'x-tree-node-icon',
+    node.icon ? 'x-tree-node-inline-icon' : '',
+    node.iconCls || '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 祖先缩进：每一个祖先贡献一张图，末位祖先→x-tree-icon（空白），否则→x-tree-elbow-line
+  const indentImgs = ctx.ancestorsLast.map((aLast) =>
+    aLast ? 'x-tree-icon' : 'x-tree-elbow-line',
+  );
+
+  const handleSelect = () => {
+    if (disabled) return;
+    ctx.onSelect(node);
+  };
+
+  const isEditing = ctx.editable && ctx.editingId === node.id;
+  const handleRenameKey = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      ctx.commitRename(node.id, e.currentTarget.value);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      ctx.startEdit(''); // 取消改名
+    }
+  };
+
+  const handleEcClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (disabled || !expandable || loading) return;
+    ctx.onToggle(node.id, node);
+  };
+
+  // 拖拽落点为 append 模式时，由 elCls 上的原生 x-tree-drag-append 类表达高亮（零新增 CSS、不写死色）
+
+  return (
+    <li className="x-tree-node">
+      <div
+        className={elCls}
+        unselectable="on"
+        data-node-id={node.id}
+        onMouseDown={(e) => ctx.onNodeMouseDown(node.id, e)}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        onClick={handleSelect}
+        onDoubleClick={() => {
+          if (ctx.editable && !disabled) ctx.startEdit(node.id);
+        }}
+      >
+        <span className="x-tree-node-indent">
+          {indentImgs.map((c, i) => (
+            <img key={i} src={BLANK_IMG} className={c} alt="" />
+          ))}
+        </span>
+        <img
+          src={BLANK_IMG}
+          className={ecCls}
+          alt=""
+          onClick={handleEcClick}
+        />
+        <img
+          src={node.icon || BLANK_IMG}
+          className={iconCls}
+          unselectable="on"
+          alt=""
+        />
+        {node.checked !== undefined && (
+          <input
+            className="x-tree-node-cb"
+            type="checkbox"
+            checked={ctx.getChecked(node)}
+            disabled={disabled}
+            onChange={(e) => ctx.onCheck(node, e.target.checked)}
+          />
+        )}
+        {isEditing ? (
+          <input
+            className="x-form-text x-small-editor x-tree-node-edit"
+            autoFocus
+            defaultValue={node.text}
+            onMouseDown={(e) => e.stopPropagation()}
+            onBlur={(e) => ctx.commitRename(node.id, e.currentTarget.value)}
+            onKeyDown={handleRenameKey}
+            style={{
+              width: '70%',
+              fontSize: 12,
+              marginRight: 4,
+              boxSizing: 'border-box',
+            }}
+          />
+        ) : (
+          <a
+            className="x-tree-node-anchor"
+            href="#"
+            tabIndex={1}
+            onClick={(e) => e.preventDefault()}
+          >
+            <span unselectable="on">{node.text}</span>
+          </a>
+        )}
+      </div>
+      {(hasChildren || loading) && (
+        <ul
+          className="x-tree-node-ct"
+          style={{ display: expanded || loading ? 'block' : 'none' }}
+        >
+          {loading && !hasChildren && (
+            <li className="x-tree-node">
+              <div className="x-tree-node-el x-tree-node-loading">
+                <span className="x-tree-node-indent">
+                  {indentImgs.map((c, i) => (
+                    <img key={i} src={BLANK_IMG} className={c} alt="" />
+                  ))}
+                </span>
+                <a className="x-tree-node-anchor" href="#" onClick={(e) => e.preventDefault()}>
+                  <span unselectable="on">Loading…</span>
+                </a>
+              </div>
+            </li>
+          )}
+          {hasChildren && (
+            <TreeBranchList
+              nodes={effectiveChildren!}
+              ctx={{
+                ...ctx,
+                ancestorsLast: [...ctx.ancestorsLast, isLast],
+              }}
+            />
+          )}
+        </ul>
+      )}
+    </li>
+  );
+}
+
+function TreeBranchList({ nodes, ctx }: { nodes: TreeNodeData[]; ctx: RenderCtx }) {
+  return (
+    <>
+      {nodes.map((n, i) => (
+        <TreeBranch
+          key={n.id}
+          node={n}
+          isLast={i === nodes.length - 1}
+          ctx={ctx}
+        />
+      ))}
+    </>
+  );
+}
+
+export interface TreePanelHandle {
+  /** 追加子节点到 parentId（null = 根层），并自动展开该父节点 */
+  appendChild: (parentId: string | null, node: TreeNodeData) => void;
+  /** 删除指定 id 节点（含其子树） */
+  removeNode: (id: string) => void;
+  /** 在 targetId 之前插入节点（同级） */
+  insertBefore: (targetId: string, node: TreeNodeData) => void;
+  /** 合并更新指定 id 节点的字段 */
+  updateNode: (id: string, partial: Partial<TreeNodeData>) => void;
+  /** 读取指定 id 节点的当前数据（找不到返回 null） */
+  getNode: (id: string) => TreeNodeData | null;
+  /** 读取当前根层节点数组（实时快照） */
+  getNodes: () => TreeNodeData[];
+  /** 展开节点 */
+  expand: (id: string) => void;
+  /** 折叠节点 */
+  collapse: (id: string) => void;
+  /** 选中节点 */
+  select: (id: string) => void;
+  /** 进入内联改名态（等价 TreeEditor.startEdit）；传入 '' 取消 */
+  startEdit: (id: string) => void;
+}
+
+export const TreePanel = forwardRef<TreePanelHandle, TreePanelProps>(function TreePanel(
+  {
+    rootVisible = true,
+    lines = true,
+    useArrows = false,
+    root,
+    nodes,
+    onSelect,
+    onExpand,
+    loader,
+    enableNodeReorder = false,
+    onNodeMove,
+    editable = false,
+    onRename,
+    style,
+  },
+  ref,
+) {
+  // 内部可变树（仅在 enableNodeReorder 时被拖拽改写；其余特性仍依赖 topNodes 读取原始结构）
+  const [treeState, setTreeState] = useState<TreeNodeData[]>(() => {
+    if (nodes) return nodes;
+    if (root) return rootVisible ? [root] : root.children ?? [];
+    return [];
+  });
+  const topNodes = treeState;
+  // 镜像最新树，供命令式句柄同步读取（避免闭包捕获旧快照）
+  const treeStateRef = useRef<TreeNodeData[]>(treeState);
+  treeStateRef.current = treeState;
+
+  useImperativeHandle(ref, () => ({
+    appendChild: (parentId, node) => {
+      setTreeState((prev) => appendChildPure(prev, parentId, node));
+      if (parentId) setExpandedIds((prev) => ({ ...prev, [parentId]: true }));
+    },
+    removeNode: (id) => {
+      setTreeState((prev) => removeNodePure(prev, id));
+    },
+    insertBefore: (targetId, node) => {
+      setTreeState((prev) => insertBeforePure(prev, targetId, node));
+    },
+    updateNode: (id, partial) => {
+      setTreeState((prev) => updateNodePure(prev, id, partial));
+    },
+    getNode: (id) => findNode(treeStateRef.current, id),
+    getNodes: () => treeStateRef.current,
+    expand: (id) => setExpandedIds((prev) => ({ ...prev, [id]: true })),
+    collapse: (id) => setExpandedIds((prev) => ({ ...prev, [id]: false })),
+    select: (id) => {
+      setSelectedId(id);
+      const n = findNode(treeStateRef.current, id);
+      if (n) onSelect?.(n);
+    },
+    startEdit: (id) => setEditingId(id),
+  }));
+
+  // 拖拽状态
+  const treeRef = useRef<HTMLDivElement>(null);
+  const dragRef = useRef<{ id: string; x: number; y: number; started: boolean } | null>(null);
+  const didDragRef = useRef(false);
+  const dropCtxRef = useRef<{ targetId: string; mode: 'above' | 'below' | 'append' } | null>(null);
+  const [, setDragId] = useState<string | null>(null);
+  const [insertTarget, setInsertTarget] = useState<{ id: string; mode: 'above' | 'below' } | null>(null);
+  const [dropTarget, setDropTarget] = useState<{ id: string; mode: 'append' } | null>(null);
+  const [ghost, setGhost] = useState<{ x: number; y: number; text: string } | null>(null);
+
+  const computeDrop = (ev: MouseEvent, dragNodeId: string) => {
+    const rootEl = treeRef.current;
+    if (!rootEl) return;
+    const els = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-node-id]'));
+    let overEl: HTMLElement | null = null;
+    for (const el of els) {
+      const r = el.getBoundingClientRect();
+      if (ev.clientY >= r.top && ev.clientY <= r.bottom) {
+        overEl = el;
+        break;
+      }
+    }
+    if (!overEl) {
+      dropCtxRef.current = null;
+      setInsertTarget(null);
+      setDropTarget(null);
+      return;
+    }
+    const targetId = overEl.getAttribute('data-node-id')!;
+    if (targetId === dragNodeId) {
+      dropCtxRef.current = null;
+      setInsertTarget(null);
+      setDropTarget(null);
+      return;
+    }
+    const r = overEl.getBoundingClientRect();
+    let mode: 'above' | 'below' | 'append';
+    if (ev.clientY < r.top + r.height * 0.25) mode = 'above';
+    else if (ev.clientY > r.bottom - r.height * 0.25) mode = 'below';
+    else {
+      const node = findNode(topNodes, targetId);
+      mode = node && (node.children?.length || node.expandable) ? 'append' : 'below';
+    }
+    // 不能拖入自身子树
+    const dragNode = findNode(topNodes, dragNodeId);
+    if (mode === 'append' && dragNode && dragNode.children && findNode(dragNode.children, targetId)) {
+      dropCtxRef.current = null;
+      setInsertTarget(null);
+      setDropTarget(null);
+      return;
+    }
+    dropCtxRef.current = { targetId, mode };
+    if (mode === 'append') {
+      setDropTarget({ id: targetId, mode: 'append' });
+      setInsertTarget(null);
+    } else {
+      setInsertTarget({ id: targetId, mode });
+      setDropTarget(null);
+    }
+  };
+
+  const onNodeMouseDown = (id: string, e: React.MouseEvent) => {
+    if (!enableNodeReorder) return;
+    const t = e.target as HTMLElement;
+    if (t.closest('.x-tree-ec-icon') || t.closest('.x-tree-node-cb') || t.closest('a')) return;
+    if (e.button !== 0) return;
+    e.preventDefault();
+    dragRef.current = { id, x: e.clientX, y: e.clientY, started: false };
+    didDragRef.current = false;
+    const move = (ev: MouseEvent) => {
+      const d = dragRef.current;
+      if (!d) return;
+      if (!d.started) {
+        if (Math.abs(ev.clientX - d.x) < 4 && Math.abs(ev.clientY - d.y) < 4) return;
+        d.started = true;
+        didDragRef.current = true;
+        const node = findNode(topNodes, d.id);
+        setDragId(d.id);
+        if (node) setGhost({ x: ev.clientX, y: ev.clientY, text: node.text });
+      }
+      computeDrop(ev, d.id);
+      setGhost((g) => (g ? { ...g, x: ev.clientX, y: ev.clientY } : g));
+    };
+    const up = () => {
+      window.removeEventListener('mousemove', move);
+      window.removeEventListener('mouseup', up);
+      const d = dragRef.current;
+      dragRef.current = null;
+      const ctx = dropCtxRef.current;
+      if (d && d.started && ctx) {
+        let next = topNodes;
+        if (ctx.mode === 'append') next = moveInto(topNodes, d.id, ctx.targetId);
+        else next = moveSibling(topNodes, d.id, ctx.targetId, ctx.mode);
+        if (next !== topNodes) {
+          setTreeState(next);
+          onNodeMove?.(d.id, ctx.targetId, ctx.mode);
+        }
+      }
+      didDragRef.current = false;
+      setDragId(null);
+      setInsertTarget(null);
+      setDropTarget(null);
+      setGhost(null);
+      dropCtxRef.current = null;
+    };
+    window.addEventListener('mousemove', move);
+    window.addEventListener('mouseup', up);
+  };
+
+  // 防止拖拽误触选中
+  const handleSelectWithGuard = (node: TreeNodeData) => {
+    if (didDragRef.current) {
+      didDragRef.current = false;
+      return;
+    }
+    setSelectedId(node.id);
+    onSelect?.(node);
+  };
+
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  /** 内联改名：当前正在编辑的节点 id（null 表示无） */
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [expandedIds, setExpandedIds] = useState<Record<string, boolean>>(() => {
+    const acc: Record<string, boolean> = {};
+    if (root) collectInitialExpanded([root], acc);
+    if (nodes) collectInitialExpanded(nodes, acc);
+    return acc;
+  });
+  /** 异步加载后写入的子节点覆盖（key = 节点 id） */
+  const [childMap, setChildMap] = useState<Record<string, TreeNodeData[]>>({});
+  /** 已成功加载过子节点的节点 id */
+  const [loadedIds, setLoadedIds] = useState<Record<string, boolean>>({});
+  /** 正在异步加载子节点的节点 id */
+  const [loadingIds, setLoadingIds] = useState<Record<string, boolean>>({});
+  /** 勾选状态覆盖（key = 节点 id），初始取自数据中的 checked */
+  const [checkedIds, setCheckedIds] = useState<Record<string, boolean>>(() => {
+    const acc: Record<string, boolean> = {};
+    if (root) collectInitialChecked([root], acc);
+    if (nodes) collectInitialChecked(nodes, acc);
+    return acc;
+  });
+
+  // 父子映射（用于勾选级联向上传播）；随异步加载的 childMap 变化而重建
+  const { parentMap, nodeById } = useMemo(() => {
+    const pMap: Record<string, string | null> = {};
+    const byId: Record<string, TreeNodeData> = {};
+    const walk = (ns: TreeNodeData[], parentId: string | null) => {
+      for (const n of ns) {
+        byId[n.id] = n;
+        pMap[n.id] = parentId;
+        const kids = childMap[n.id] ?? n.children;
+        if (kids) walk(kids, n.id);
+      }
+    };
+    walk(topNodes, null);
+    return { parentMap: pMap, nodeById: byId };
+  }, [topNodes, childMap]);
+
+  const rootCls = useArrows
+    ? 'x-tree-arrows'
+    : lines
+      ? 'x-tree-lines'
+      : 'x-tree-no-lines';
+
+  const ctx: RenderCtx = {
+    lines,
+    useArrows,
+    selectedId,
+    expandedIds,
+    ancestorsLast: [],
+    onSelect: handleSelectWithGuard,
+    onToggle: (id, node) => {
+      const willExpand = !expandedIds[id];
+      // 异步加载：展开一个尚无子节点的 expandable 节点时触发 loader
+      if (
+        willExpand &&
+        loader &&
+        !loadedIds[id] &&
+        !(childMap[id] && childMap[id].length) &&
+        !(node.children && node.children.length)
+      ) {
+        setLoadingIds((prev) => ({ ...prev, [id]: true }));
+        loader(node)
+          .then((children) => {
+            setChildMap((prev) => ({ ...prev, [id]: children }));
+            setLoadedIds((prev) => ({ ...prev, [id]: true }));
+            setLoadingIds((prev) => ({ ...prev, [id]: false }));
+            setExpandedIds((prev) => ({ ...prev, [id]: true }));
+          })
+          .catch(() => {
+            setLoadingIds((prev) => ({ ...prev, [id]: false }));
+          });
+        onExpand?.(node, true);
+        return;
+      }
+      setExpandedIds((prev) => {
+        const next = { ...prev };
+        next[id] = !next[id];
+        onExpand?.(node, next[id]);
+        return next;
+      });
+    },
+    getChildren: (node) => childMap[node.id] ?? node.children,
+    isLoading: (id) => !!loadingIds[id],
+    getChecked: (node) => {
+      const v = checkedIds[node.id];
+      return v !== undefined ? v : !!node.checked;
+    },
+    enableNodeReorder,
+    dropTargetId: dropTarget?.id ?? null,
+    dropMode: dropTarget ? 'append' : insertTarget ? insertTarget.mode : null,
+    insertTarget,
+    onNodeMouseDown,
+    editable,
+    editingId,
+    startEdit: (id: string) => setEditingId(id || null),
+    commitRename: (id: string, text: string) => {
+      setEditingId(null);
+      if (text && text.trim()) {
+        setTreeState((prev) => updateNodePure(prev, id, { text: text.trim() }));
+        onRename?.(id, text.trim());
+      }
+    },
+    onCheck: (node, checked) => {
+      setCheckedIds((prev) => {
+        const next = { ...prev };
+        // 1) 自身及其所有（已知）后代统一置为新值
+        const apply = (n: TreeNodeData) => {
+          next[n.id] = checked;
+          const kids = childMap[n.id] ?? n.children;
+          if (kids) kids.forEach(apply);
+        };
+        apply(node);
+        // 2) 向上传播：祖先 checked = 其全部已知子节点均 checked
+        let pid = parentMap[node.id];
+        while (pid != null) {
+          const pNode = nodeById[pid];
+          if (!pNode) break;
+          const kids = childMap[pid] ?? pNode.children;
+          const allChecked =
+            !!kids && kids.length > 0 && kids.every((k) => next[k.id] ?? !!k.checked);
+          next[pid] = allChecked;
+          pid = parentMap[pid];
+        }
+        return next;
+      });
+    },
+  };
+
+  return (
+    <div className="x-tree" style={style} ref={treeRef}>
+      <ul className={`x-tree-root-ct ${rootCls}`}>
+        <TreeBranchList nodes={topNodes} ctx={ctx} />
+      </ul>
+      {/* 拖拽落点指示：above/below 由 TreeBranch 给目标节点 el 挂原生 x-tree-drag-insert-above/below
+          类（点状主题色边框，见 ext-all.css），append 由 x-tree-drag-append 类表达——均复用原生
+          树拖拽落点机制，不写死颜色、不画浮动 div。 */}
+      {/* 拖影（复用 ext-all.css 的 .x-dd-drag-ghost） */}
+      {ghost && (
+        <div
+          className="x-dd-drag-ghost"
+          style={{
+            position: 'fixed',
+            left: ghost.x + 12,
+            top: ghost.y + 8,
+            pointerEvents: 'none',
+            zIndex: 15000,
+          }}
+        >
+          {ghost.text}
+        </div>
+      )}
+    </div>
+  );
+});
+
+TreePanel.displayName = 'TreePanel';