1. 背景与痛点：为什么我们需要重造一棵“树”？#

在开发 Zion 无代码编辑器 时，画布左侧的“图层结构树 (Layers Tree)”以及“页面路由树 (Pages Tree)”是开发者最依赖的视图模块。 起初，我们考虑过使用 Ant Design 的 Tree 或市面上开源的树组件。但在低代码/无代码的真实业务场景下，这些传统组件很快就暴露出了主要的缺陷：

1. DOM 节点溢出：一个复杂的业务页面很容易拥有上千个互相嵌套的 UI 组件。如果不使用虚拟渲染，仅仅是展开整个大树就会导致浏览器主线程严重卡顿。
2. 高度自由的拖放互动 (DnD)：用户可以在树中随意拖拽一个层级极深的子节点，不仅能改变它的同级顺序（排序），还能将其拖拽并跨级放入另外一个父节点中（层级嵌套）。
3. 数据一致性灾难：在拖拽过程中，如果用户试图把一个“父容器”拖进它自己的“子容器”里（引发循环依赖 / 循环引用），或者把不允许包含子元素的组件（如纯文本节点）当做父容器，系统需要毫秒级的精准拦截，否则中间的可视化画布将直接崩溃。

为了解决这些底层难题，我从零开始主导并设计了 LgdTree (Large Graph Data Tree) 这个专门服务于 Zion 画布生态的高性能虚拟树组件。它基于现代化拖拽引擎 @dnd-kit/core 与虚拟列表技术，完美承载了 Zion 百万级组件配置的视图树重任。

2. 核心架构一：多叉树的“1D”虚拟化扁平降维#

要想让一棵拥有上千节点的深层多叉树不卡顿，唯一的解法就是虚拟列表 (Virtual List)。但虚拟列表只能渲染一维数组（1D Array），无法直接理解树的 children 嵌套结构。

在 LgdTree 的架构中，我设计了一个非常高效的实时扁平化管道 (flattenTree)。在每次数据源发生变化或者节点折叠/展开状态改变时，我们会结合 DFS（深度优先遍历）算法，把树形结构扁平化为一个包含 depth (缩进深度) 属性的一维数组。

flowchart LR
    subgraph OriginalTree ["原始多叉树结构"]
        A["Root"] --> B["Container"]
        B --> C["Button"]
        A --> D["Text"]
    end
    
    subgraph Flattening ["实时扁平化管道"]
        DFS["DFS 递归展开"]
        State["检查展开/折叠状态"]
        DFS --> State
    end
    
    subgraph VirtualArray ["一维渲染数组 (VirtualLine)"]
        Line1["[depth: 0] Root"]
        Line2["[depth: 1] Container"]
        Line3["[depth: 2] Button"]
        Line4["[depth: 1] Text"]
    end
    
    OriginalTree --> Flattening
    Flattening --> VirtualArray

核心降维逻辑:

1
function flatten(items: TreeData, parentId: string | null = null, depth = 0, result: TreeNode[] = []): TreeNode[] {
2
  items.forEach((item, index) => {
3
    const children = item.children || [];
4
    const newItem = { ...item, children, parentId, depth, index };
5
    result.push(newItem);
6
    if (children.length > 0) {
7
      flatten(children, item.id, depth + 1, result);
8
    }
9
  });
10
  return result;
11
}

利用生成的 depth，我们在 React 渲染时通过给每行 VirtualLine 加上 padding-left: ${depth * 20}px 的缩进，在视觉上视觉上呈现成了一棵树，但在浏览器的 DOM 树上，它永远只有视窗里可见的那十几行简洁的 <li> 节点。

3. 核心架构二：跨级拖拽与意图投影 (Projected Insertion)#

LgdTree 最复杂的逻辑在于其定制的拖拽引擎。传统的排序库（如 react-sortable-hoc）只能在同层级改变顺序，而我们需要支持跨层级的嵌套拖拽。

为了实现这一点，我在 components/DndMonitor/index.tsx 中深度定制了 dnd-kit 的核心钩子。我们不直接操作真实数据，而是引入了 意图投影 (Projection) 的概念。

1
function onDragMove({ delta }: DragMoveEvent) {
2
  // 利用节流阀实时记录用户的横向拖拽偏移量
3
  // 横向移动的距离决定了用户是想保持同级 (同 depth)，还是想缩进成为子元素 (depth + 1)
4
  handleDragMove(delta.x);
5
}
6

7
function onDragOver({ over, active }: DragOverEvent) {
8
  // 结合当前的 activeId, overId 和 deltaX, 推算出实时投影位置 Projected
9
  const projected = getProjection(
10
    items,
11
    activeId,
12
    overId,
13
    dragOffset,   // Y轴偏移
14
    indentWidth   // 层级缩进单位 (比如 20px)
15
  );
16

17
  // 1. 循环依赖防腐层：一旦查明拖入的是自身的后代节点，立刻终止！
18
  if (isCircularDependency(activeId, projected.parentId)) {
19
     return;
20
  }
21

22
  // 2. 派发渲染层，渲染一条带有目标缩进深度的 "蓝色的拖拽落点指示线"
23
  setProjectedState(projected);
24
}

1
const sensors = useSensors(
2
  useSensor(PointerSensor, {
3
    activationConstraint: {
4
      distance: 5, // 核心防抖：必须按住并实际移动超过 5 像素，才正式激活拖拽引擎
5
    },
6
  })
7
);

4. 核心难点突破：领域解耦与数据双向同步 (useNodeDnd)#

在 Zion 的编辑器中，左侧的 LayersTree (图层树) 和中间的 CanvasPro (画布) 实际上是对同一份 Schema Meta 数据的两套不同视图的映射。 为了保证拖拽完成后，数据能够安全地同步回 MobX Store 并触发全局重绘，我把具体的落地逻辑抽象成了领域特定的 Hook：useNodeDnd。

1
export const useNodeDnd = (): Pick<LgdTreeProps, 'onReorder' | 'onReparent'> => {
2
  const { onMoveMetaChild } = useMetaChildsUpdate();
3
  const { onUpdateComponentParent } = useUpdateComponentParent();
4

5
  // 1. 同级排序事务
6
  const onReorder = useCallback((params) => {
7
    const parentMeta = getParentMeta(dragItem.id);
8
    // 触发底层画布同级的 Mobx Mutation，并由中间的可视化画布响应刷新
9
    onMoveMetaChild({
10
      metaId: parentMeta.id,
11
      from: params.src.index,
12
      to: params.dst.index,
13
    });
14
  }, [...]);
15

16
  // 2. 跨层级嵌套事务
17
  const onReparent = useCallback((params) => {
18
    const { dragItem, dst } = params;
19
    // 解析树节点 ID 到底层画布 Component ID 的映射
20
    const dragCompId = decodeMetaId(dragItem.id).componentId;
21
    const dropParentId = decodeMetaId(dst.parentId).componentId;
22

23
    // ...组装新的 Schema 数据拓扑，通知后端和画布重绘
24
    onUpdateComponentParent({
25
      componentId: dragCompId,
26
      newParentId: dropParentId,
27
      index: dst.index
28
    });
29
  }, [...]);
30

31
  return { onReorder, onReparent };
32
};

5. 攻克难题四：双向联动视角下的自动展开与精准定位 (Auto-Scroll in Virtual Tree)#

在可视化编辑器中，画布和左侧图层树必须是双向联动的：当用户在画布上点击某个极深层级的子组件时，左侧的图层树需要自动滚动并将该节点高亮显示。

在普通的树组件中，这只需要调用 element.scrollIntoView()。但在 虚拟化树组件 (Virtualized Tree) 中，这是一个技术难点：

1. 节点可能根本不存在：目标节点可能被折叠在某个父级文件夹内，并没有被渲染在 DOM 上。
2. 不知道滚动距离：因为树被折叠，目标节点的全局 Index 是未知的，也就无法计算它的 scrollTop。

为了解决这个痛点，我在 useScrollToNode.ts 中设计了一套非常巧妙的自动追踪与重绘路由算法：

1
// zed/src/zed/components/LgdTree/hooks/useScrollToNode.ts (精简版)
2
export const useScrollToNode = (params: UseScrollToNodeParams) => {
3
  const { listRef, expandTreeNodes, indentationWidth, itemHeight } = params;
4

5
  const onScrollToNode = useCallback(
6
    (key: string) => {
7
      // 1. 业务层首先向上查找目标节点的所有父节点 ID，并更新到 expandedKeys 中
8
      // 2. 这会触发 flattenTree 重新计算 1D 数组 (expandTreeNodes)
9

10
      // 3. 我们利用 requestAnimationFrame 等待全新的 1D 数组生成完毕
11
      requestAnimationFrame(() => {
12
        // 获取目标节点在全新 1D 数组中的真实下标
13
        const idx = expandTreeNodes.findIndex(({ id }) => id === key);
14
        if (idx === -1 || !listRef.current) return;
15

16
        // 计算目标节点的物理 Y 轴高度和 X 轴横向缩进
17
        const offsetLeft = (expandTreeNodes[idx].depth + 1) * indentationWidth;
18
        const scrollTop = idx * itemHeight;
19

20
        // 调用 rc-virtual-list 的底层方法，进行像素级坐标跳跃
21
        listRef.current?.scrollTo({
22
          top: scrollTop,
23
          left: offsetLeft,
24
        });
25
      });
26
    },
27
    [expandTreeNodes, indentationWidth, itemHeight, listRef],
28
  );
29

30
  return { onScrollToNode };
31
};

通过这套算法，无论组件隐藏得有多深，系统都能在毫秒间完成**“祖先节点展开 -> 扁平树重算 -> 像素坐标解算 -> 滚动 API 调用”**的完整链路，实现了所见即所得的双向高亮驱动。

6. 总结：前端重型基建的破局之道#

LgdTree 是我在 Zion 无代码平台中核心前端基建项目之一。 它不仅仅是一个长得好看的左侧菜单，它实际上是一个披着树形外衣的高性能计算引擎。

通过引入 1D 扁平化虚拟渲染、基于 offsetX/offsetY 的投影意图推导算法、以及严格的事务防腐与解耦 Hook 体系，它完美解决了大量 DOM 卡顿、交叉拖拽死循环等痛点。正有了如此坚如磐石的底层树形调度组件，Zion 的可视化画布能够支撑起数以千计的复杂业务节点和随心所欲的用户操作。