Zion无代码画布核心架构技术总结文档#

1.1 核心数据与渲染管道#

graph TB
    subgraph State_Management ["数据层 (State Management)"]
        direction TB
        A["CanvasStore (MobX)"] -->|"扁平化存储"| B("metas: Record<ID, Meta>")
        A -->|"路由状态"| C("boardsRecord 路由栈")
        A -->|"派生与变异"| D("CanvasAction 接口")
    end

    subgraph Render_Engine ["渲染引擎 (Render Engine)"]
        direction TB
        E["MetaRenderTree"] -->|"递归入口"| F{"按需解析"}
        F -->|"编辑态"| G["MetaEditableRenderTree"]
        F -->|"预览态"| H["MetaPreviewRenderTree"]
        G -.精确订阅.-> B
        G -->|"异常隔离"| J["CanvasErrorBoundary"]
    end

    A -.- E

1.2 视口事件与拖拽碰撞体系#

graph TB
    subgraph Viewport_Event ["无限画布与事件层 (Viewport)"]
        direction LR
        K["react-infinite-viewer"] --> L("Transform 偏移矩阵")
        M["CanvasEventEmitter"] -->|"无状态分发"| L
        O["GlobalEventMonitor"] -->|"统一拦截"| M
    end

    subgraph DnD_Engine ["拖拽引擎 (DnD Engine)"]
        direction LR
        Q["DndContextWrapper"] --> R("碰撞检测 (Collision Detection)")
        R --> S("useInsertTarget 计算落点")
        S --> T["触发 DOM 高亮占位"]
    end

• 核心状态驱动 (State Management)：基于 MobX (mobx-react) 构建核心状态库 CanvasStore。所有页面组件数据（metas）、画板路由（boards）、选中状态、断点信息等均收敛于此。
• 渲染引擎 (Render Engine)：基于 React 递归渲染，通过 MetaRenderTree 动态解析元数据并生成真实的 DOM 节点。
• 拖拽引擎 (DnD Engine)：基于 @dnd-kit/core 二次封装，提供了组件级别的拖拽节点映射。
• 无限画布 (Infinite Viewport)：基于 react-infinite-viewer，结合自定义的全局事件总线，实现画布丝滑的平移与缩放。

2.1 状态管理：平面化与响应式 (CanvasStore)#

在无代码应用中，组件树的层级往往极其深邃。若采用传统的 React Context 或纯层级 State，任何叶子节点的修改都会引发自顶向下的重渲染。

• 结构解耦的强类型分层：在 CanvasStore/types/index.ts 中，Store 被严格划分为 CanvasState (核心源数据)、CanvasComputedState (派生与缓存数据，如 metaByComponentId 索引字典) 以及 CanvasAction (状态突变接口)。
• 平面化存储 (Flattening)：组件树被扁平化，以 id 为键存放在 Record<Meta['id'], Meta> (metas) 中，彻底避免了深度嵌套引发的更新困难。

Before vs After: 状态降维的视觉直观对比 如果不做扁平化，一个组件树的更新是灾难性的（需要层层递归寻找节点）：

1
// ❌ 传统树形 State (深层嵌套，更新困难)
2
{
3
  "id": "root",
4
  "children": [
5
    {
6
      "id": "container_1",
7
      "children": [ { "id": "button_1", "text": "Click" } ]
8
    }
9
  ]
10
}

但在 Zion 的 CanvasStore 中，我们将其彻底拍平，所有的节点无论层级多深，都变成了 O(1) 复杂度的字典寻址：

1
// ✅ Zion 的扁平化 State (O(1) 更新与读取)
2
{
3
  "metas": {
4
    "root": { "id": "root", "childIds": ["container_1"] },
5
    "container_1": { "id": "container_1", "childIds": ["button_1"], "parentId": "root" },
6
    "button_1": { "id": "button_1", "text": "Click", "parentId": "container_1" }
7
  }
8
}

• 精确粒度订阅 (Granular Reactivity)：结合底层通用的 memoWithObserver 高阶组件。通过闭包按需读取具体的 Meta 数据，只有当该 Meta 对应的数据变更时，才会触发对应 DOM 的 Re-render。

平面化存储缓存字典示例：

1
export interface CanvasComputedState {
2
  metaKeys: Array<Meta['id']>;
3
  // O(1) 复杂度的组件反查字典
4
  metaByComponentId: Record<Component['id'], Record<string, Meta>>;
5
}

2.2 渲染树引擎 (MetaRenderTree & Hooks)#

渲染树是画布的“血肉”。入口通过传入 rootId 开始，进行组件级别的递归渲染。

硬核踩坑：React Render 的性能黑洞与 Immutable 优化 在画布最初的版本中，由于 MetaRenderTree 是一个巨大的递归组件，当用户在画布顶部拖动一个按钮时，顶层 root 的 state 发生改变，导致整个画布（包含几千个嵌套节点）瞬间触发自顶向下的 React Render，整个浏览器直接卡死。

工业级解法：细粒度订阅 + React.memo + ID 指针传递 为了彻底阻断无意义的渲染，我们对 MetaRenderTree 进行了极其严苛的优化：

1. 父组件只传递 ID，绝不传递 Object：父节点在渲染子节点时，只传 childId 字符串，而不是完整的 childMeta 对象。这样即使父节点的属性变了，由于子组件接收的 id 没变，配合 React.memo，子树的渲染被完美拦截。
2. 子组件按需自订阅 (Self-Subscription)：子组件拿到 childId 后，利用 MobX 的 observer 在自己内部去 CanvasStore 里精确订阅自己的状态。

1
// ❌ 灾难写法：每次父级更新，整个子树全部重渲染
2
function RenderTree({ meta }) {
3
  return (
4
    <div>
5
      {meta.children.map(childMeta => <RenderTree key={childMeta.id} meta={childMeta} />)}
6
    </div>
7
  );
8
}
9

10
// ✅ 极致优化写法：只传 ID，阻断 Render 瀑布流
11
const RenderTree = observer(({ metaId }) => {
12
  // 子组件只精确订阅自己的数据
13
  const meta = canvasStore.metas[metaId];
14

15
  return (
16
    <div style={meta.style}>
17
      {meta.childIds.map(id => <RenderTree key={id} metaId={id} />)}
18
    </div>
19
  );
20
});

通过这套机制，画布内无论拖拽、变色、修改文字，真正触发 React 重渲染的永远只有被修改的那一个具体 DOM 节点，渲染性能提升了成百上千倍。

引擎层渲染策略与可视区裁剪（虚拟化）伪代码：

1
const childTrees = useMemo(() => {
2
  if (!childMetas || !childMetas.length) {
3
    return <MetaPlaceholder meta={meta} />;
4
  }
5
  return map(childMetas, (childMeta) => (
6
    <MetaEditableRenderTree meta={childMeta} key={childMeta.id} />
7
  ));
8
}, [childMetas, meta]);
9

10
// 核心：基于可视区进行裁剪
11
const showShadow = useMemo(() => {
12
  if (isForceVisible) return false;
13
  return isOutOfView && type !== CONDITIONAL_VIEW; // 如果越界则显示 Shadow 占位
14
}, [isOutOfView, isForceVisible]);
15

16
if (showShadow) {
17
  // 退化渲染以保证滚动条高度不塌陷
18
  return <MetaShadow size={sizeRef.current} />;
19
}

2.3 无限视口与高性能事件 (Viewport & EventEmitter)#

画布场景下，缩放和平移是最高频的操作。如果在这一层频繁修改 React State，会导致整个画布（几千个节点）进入 Diff 流程。

完全绕过 VDOM 的高性能处理方案：

1
// 触发缩放时，不调用 setState，而是通过全局单例的 EventBus 抛出
2
const onZoomIn = useCallback(() => {
3
  const newZoom = getViewportLegalZoom(curZoom + rate);
4
  // 这里直接操作单例事件总线，原生修改 DOM Transform，彻底切断 React Render 管线！
5
  CanvasEventEmitter.emit(CanvasEmitterEventType.VIEWPORT_SET_ZOOM, newZoom);
6
}, []);

• 通过 CanvasEventEmitter.emit 分发事件，单例闭包直接截获并修改底层节点 Transform 矩阵，保障了 60fps 的交互体验。

2.4 独立的高亮与辅助线层 (Tools Overlay)#

为了防止业务组件被画布的编辑器状态污染，所有的选中高亮（Select）、悬浮边框（Hover）、以及拖拽插入的辅助线（InsertGuideLine），均被抽离至 Tools/views 下独立渲染。

graph LR
    A[用户操作] --> B(CanvasStore 更新 selectedMetaIds)
    B --> C[Tools Overlay]
    C -->|计算绝对坐标| D(绘制高亮边框/辅助线)

2.5 事件监控与快捷键系统 (Shortcut Monitor)#

利用 ShortcutMonitor 在全局顶层拦截键盘事件。无论是复制（Cmd+C）、撤销重做（Cmd+Z），都在该系统内统一转化为 CanvasAction，防止浏览器的默认行为与画布内部逻辑发生冲突。

1
// 统一监听与事件代理
2
useEventEmitterSubscription(CanvasEmitterEventType.SHORTCUT_TRIGGERED, (param) => {
3
  const { event, type, target } = param;
4
  event.preventDefault();
5
  executeShortcutAction(type); // 派发至专门的处理管线
6
});

2.6 组件元数据转译管道 (Transpile Pipeline)#

不同类型的组件拥有不同的 Schema 结构。在 useTranspile 系列钩子中，服务端下发的基础 JSON 会根据当前的视口断点（Breakpoint）被动态转译成标准的 Meta 数据结构。

graph LR
    A[服务端 Component JSON] -->|匹配 Breakpoint| B(useTranspile 管道)
    B -->|动态挂载特定属性| C(规范化 Meta 结构)
    C --> D[存入 CanvasStore]

2.7 多层级画板路由栈 (Boards & Routing)#

无代码搭建经常需要“下钻”编辑（例如双击一个列表组件，进入列表项的独立编辑环境）。通过维护 boardsRecord 路由栈，画布支持无缝的上下文切换。

1
// 记录进入下钻模式前的状态
2
export interface BoardConfig {
3
  type: BoardConfigType;
4
  componentId: string;
5
  viewConfig: BoardViewConfig; // 包含此层级记录的视角和缩放比例
6
}

2.8 动态上下文菜单体系 (Context Menu System)#

封装了 MetaContextMenu 与 PageContextMenu，在用户右键点击不同节点时，通过计算触发位置的 DOM Dataset 信息，动态唤起不同的菜单项。

1
// 右键菜单按需判定策略
2
const isIllegalType = includes(
3
  [ComponentRefactorComponentType.TAB_VIEW, ComponentRefactorComponentType.CONDITIONAL_VIEW],
4
  meta.type,
5
);
6
if (isIllegalType) return false;
7
// 根据不同类型的 meta 唤起对应的操作组（组合、分离、绑定数据源等）

2.9 异步组件与渲染沙箱 (Canvas Error Boundary)#

无代码平台中的配置数据常常存在脏数据。通过在树节点的特定层级包裹 CanvasErrorBoundary，一旦某个子组件因为异常参数崩溃，错误边界会将其捕获并渲染为错误提示块（ErrorTips）。

沙箱隔离机制:

1
<CanvasErrorBoundary fallbackRender={({ error }) => <ErrorTips error={error} />}>
2
  <MetaEditableRenderTree meta={childMeta} />
3
</CanvasErrorBoundary>

2.10 响应式与变体样式合成 (Responsive & Variants)#

通过 useComputedMetaStyles Hook，在渲染管线中实时对基础样式（Styles）和变体样式（Variants）进行深度合并。

1
// 核心：基于当前环境动态混合样式表
2
let targetStyles = toJS(styles);
3
if (variantStyles) {
4
  // 当命中变体时（如断点/状态变化），将变体样式覆盖至基础样式之上
5
  targetStyles = mergeDeep(targetStyles, variantStyles);
6
}

2.11 只读模式与沙箱拦截 (Readonly & Permission)#

通过底层的 ReadonlyMonitor 与状态树的 readonly 标识，可以在查看历史版本、无权限访问时，彻底锁死拖拽引擎（设置 Dnd 为 disabled）、拦截双击以及右键菜单，实现查看与编辑态的同构复用。

只读态锁定示例：

1
const draggableConfig = useMemo<UseDraggableArguments>(
2
  () => ({
3
    id,
4
    disabled: readonly || !isDraggable(id), // 核心鉴权拦截
5
    data: draggableData,
6
  }),
7
  [id, readonly, isDraggable, draggableData],
8
);

2.12 拖拽物料抽象与起源判定 (Drag Origin Calculation)#

并非所有的拖拽行为都是相同的。在 useDraggableConfig 中，系统会根据组件的 CSS 定位属性预计算出 DragOrigin：

1
const draggableOrigin = useMemo(() => {
2
  if (recordedShortcut?.mode === RecordedShortcutType.CROSS_LEVEL) {
3
    return DragOrigin.CROSS_LEVEL; // 跨层级降维打击拖拽
4
  }
5
  const isWrapperAbsOrFixed = isAbsoluteOrFixed(wrapperStyle);
6
  // 如果是绝对定位，其拖拽逻辑为单纯移动；如果是文档流，则判定为弹性流式排序
7
  return isWrapperAbsOrFixed ? DragOrigin.ABS_OR_FIXED_MOVE : DragOrigin.FLEX_SORT;
8
}, [wrapperStyle, recordedShortcut?.mode]);

2.13 批量选取与框选机制 (Canvas Selecto)#

深度整合了 Selecto.js，用户在画布空白处拖动鼠标可拉出多选框。通过几何交集算法匹配节点坐标，将多选的 ID 批量写入 selectedMetaConfigs。

框选算法代理事件:

1
<Selecto
2
  dragContainer={`#${VIEWPORT_ID}`}
3
  selectableTargets={selectedTargets}
4
  hitRate={0}
5
  selectByClick={false}
6
  {...selectoEvents} // 将框选边界事件代理回 Store
7
/>

难点 1：巨型 DOM 树下的渲染性能 (Visibility Optimization)#

场景：当用户搭建了上千个组件，画布渲染将变得极其卡顿，拖拽也会存在巨大的延迟。 解法：视口外节点裁剪（虚拟化画布）。

在无代码编辑器的无限画板中，节点并不是排列成一维数组的，无法使用常规的虚拟列表。因此，我引入了基于 IntersectionObserver 和 MetaShadow (影子占位符) 的递归剔除算法。

graph TD
    subgraph Browser_Window ["用户可见视窗 (Viewport)"]
        A["[真实的 React 节点] Container"] --> B["[真实的 React 节点] Image"]
        A --> C["[真实的 React 节点] List"]
    end
    
    subgraph Out_Of_View ["视窗之外的不可见区域"]
        C -.->|"斩断递归树，卸载真实 DOM"| D("👻 MetaShadow 占位符")
        D -.->|"保留 sizeRef (width/height)"| E("防止父级容器高度塌陷")
    end

• 在 MetaEditableRenderTree 中，深度应用了 useMetaVisibilityState 技术。
• 采用 startTransition 降级判断优先级。基于底层的 IntersectionObserver 监控元素的交叉状态。如果为 isOutOfView（不在可视区），就立刻斩断子树的递归渲染，这意味着藏在某个超长列表底部的成百上千个复杂组件，在滚出视口的一瞬间就会被彻底卸载。
• 为了防止剔除渲染导致父容器塌陷，利用闭包中的 sizeRef 记录退出可视区前的宽高，并用轻量级的 MetaShadow 幽灵组件去撑开原本的物理骨架尺寸。这使得滚动条、绝对定位和 Flex 布局等都完全不会因为 DOM 树的卸载而错乱。

难点 2：极其复杂的协同与撤销重做 (Diff Apply)#

场景：多人协同编辑或 Undo/Redo 时，全量替换 Meta 树代价极其高昂，会导致焦点丢失。 解法：细粒度 Diff 补丁分发机制 (useDiffApply)。

graph LR
    A[协同事件 / Undo指令] --> B(解析 Diff 快照 operation: 'add')
    B --> C[useAddOrDeleteComponentDiffApply]
    C --> D[useTranspile 转译为 Meta]
    D --> E[MobX Transaction 开启]
    E --> F[定点更新 CanvasStore.metas]

• 单独抽象了 useDiffApply 机制作为增量构建引擎。服务端传入的并非整棵树，而是属性操作快照（如 operation: 'add'）。

基于 MobX 事务的无闪烁补丁机制：

1
// useAddOrDeleteComponentDiffApply.ts 中处理 Add 补丁
2
case 'add': {
3
  // 1. 获取最新的组件描述信息
4
  const targetComponent = getComponent(id);
5
  // 2. Transpile转译器：将原始 Schema 翻译为 Meta 对象
6
  const pendingTasks = map(canvasStore.breakpoints, (bp) => transpile(targetComponent, bp));
7
  const metas = await Promise.all(pendingTasks);
8

9
  // 3. 通过 transaction 将生成的 metas 直接打入 Store 字典中
10
  return async () => {
11
    transaction(() => {
12
      forEach(metas, (newMeta) => {
13
        canvasStore.addMeta(newMeta);
14
      });
15
    });
16
  };
17
}

• 通过底层事务同步打入状态字典，彻底杜绝了状态不同步引发的白屏与闪烁。

难点 3：多维度灾难恢复机制 (Crash Recovery)#

场景：浏览器内存溢出（OOM）或网络异常退出，会导致用户数小时心血付之东流。 解法：低廉成本的本地快照容灾。

graph TD
    A(编辑画布中) -.静默.-> B[useRecoveryRecord 定时防抖备份]
    B --> C[序列化关键状态 metas/viewport]
    C --> D[(写入 IndexedDB / LocalStorage)]
    E[异常崩溃 / 重新打开页面] --> F[RecoveryMonitor 挂载]
    F --> G{检测到新于服务端的快照碎片?}
    G -- Yes --> H[弹窗提示用户无缝重载恢复]

• 采用了 useRecoveryRecord 机制，这套代码深埋在核心链路外。
• 以极低的性能损耗，通过 ahooks 的 useLocalStorageState 定期对关键状态（Metas、Viewport等）序列化并写入 LocalStorage。
• 重启时平台通过 RecoveryMonitor 捕获上次遗留的数据碎片，并无缝重载恢复。

定时快照备份示例：

1
const [localRecord, setLocalRecord] = useLocalStorageState('CANVAS_RECOVERY_DATA', { defaultValue: null });
2

3
useDebounceEffect(() => {
4
  if (!isCanvasDirty) return;
5
  // 在帧空闲时执行深度序列化，避免阻塞主线程交互
6
  const snapshot = serializeCanvasState(canvasStore);
7
  setLocalRecord({ timestamp: Date.now(), data: snapshot });
8
}, [canvasStore.metas], { wait: 5000 });

难点 4：拖拽的自由度与严谨性 (DnD Collision & Insert Target)#

场景：组件间嵌套规则复杂（如模态框内不允许插入页面组件），需要灵活处理 Drop 边界与精准高亮框。 解法：极致解耦的碰撞算法引擎。

graph TD
    A[拖拽移动 DragMove] --> B{DnD Context 碰撞检测}
    B -->|收集指针下方所有相交的 Dataset ID| C(过滤非法父级白名单)
    C --> D(获取合法容器 containerId)
    D --> E[useInsertTarget 落点算法计算]
    E --> F{判定位置坐标区间}
    F -- 靠上/左 --> G[INSERT_BEFORE]
    F -- 居中 --> H[INSERT_INNER]
    F -- 靠下/右 --> I[INSERT_AFTER]
    G & H & I --> J[更新 Store dispatch 并渲染辅助线]

• 拖拽事件 Listeners 完全与业务组件解耦。组件仅仅透传自身的 id，真正的碰撞检测（Collision Detection）由顶层的 DndContextWrapper 统一代理结算。
• useInsertTarget 预计算落点（基于鼠标指针矩阵的偏移量计算出上插、下插、内嵌），实时派发事件渲染 DropHighlight 或特定的虚线占位符。这保证了底层组件依然纯净无副作用，拖拽体感极其丝滑严谨。

碰撞检测与锚点挂载代码:

1
// 1. Meta.ts: 生成锚点信息用于碰撞反查
2
export const genMetaDataSet = (metaId: string, type: Meta['type']) => {
3
  return {
4
    'data-meta-id': metaId,
5
    'data-meta-type': type,
6
  };
7
};
8

9
// 2. 算法核心：结合当前指针位置与容器盒模型计算精准落点
10
export function calculateInsertTarget(pointerY: number, containerRect: DOMRect) {
11
  const { top, height } = containerRect;
12
  // 如果处于容器上部20%区域 -> 前插
13
  if (pointerY < top + height * 0.2) return InsertPosition.BEFORE;
14
  // 处于中间60%区域 -> 内嵌
15
  if (pointerY < top + height * 0.8) return InsertPosition.INNER;
16
  // 处于下部20%区域 -> 后插
17
  return InsertPosition.AFTER;
18
}