手写无限画布4 —— 从视觉图元到元数据对象

画布上的每一个像素都是稍纵即逝的，真正永恒的，是背后那套被精心设计的元数据（Metadata）规范。

尽管在前面的篇章中，我们一路披荆斩棘，搞定了坐标系、渲染层和基本交互，让演示工程初具雏形。但 Canvas 本质上只是一块没有记忆的像素面板。

要想从理论走向工程落地，实现支持持久化与多人协同的业务，最核心的架构法则在于：必须将画布上的任意元素，都抽象并定义为可传输、可持久化的元数据对象（Metadata Object）。

元数据定义 (Metadata Definition)

我们要彻底抛弃"直接在画布里 new Konva.Rect()" 的思维惯性。

在一个成熟的白板应用架构中，画布引擎只是一个"读报机器"，它读的报纸，就是我们定义的元数据规范（Metadata Schema）。

为了达到我们最终建立一个类似 Excalidraw 的既定目标，我们在规范数据结构时，绝不能只停留在纯粹的"几何图形"定义上。我们必须在其之上，附加明确的预制业务概念 。我们不仅要描述它是一个 Rect（矩形），更要描述它在业务里是一张 StickyNote（便利贴），还是一根 Connector（连接线）。

如下代码，这就是我们实际落地的元数据规范：

// src/schema/types.ts

// 所有图元共享的基因------它们必须遵守的基础契约
export interface BaseElementData {
  id: string; // 唯一宇宙编号，协同与更新的基石
  type: ElementType; // 业务大类
  x: number;
  y: number;
  width: number;
  height: number;
  hitColor: string; // 上一篇的命中测试色值，也要元数据化
  strokeColor: string;
  backgroundColor: string;
  opacity: number;
  zIndex: number; // 层级控制，决定覆盖关系
  isLocked: boolean; // 业务属性：用户是否锁定了该元素
  // ...
}

// 业务派生：形状、文字、线条各有自己的专属字段
export interface ShapeElementData extends BaseElementData {
  type: "rectangle" | "ellipse" | "diamond";
}

export interface LinearElementData extends BaseElementData {
  type: "arrow" | "line";
  points: number[][]; // 途经的折点
  startArrowhead: "arrow" | "triangle" | "none";
  endArrowhead: "arrow" | "triangle" | "none";
  startBindingId: string | null; // 线头绑定的元素 ID
  endBindingId: string | null;
}

// 终极联合类型：无限画布的唯一真理对象
export type CanvasElementData =
  | ShapeElementData
  | TextElementData
  | LinearElementData;

注意一个关键细节：上一篇讲到的命中测试色值 hitColor ，也被我们收编进了元数据定义。从此刻起，一个图形的一切------它在哪、它多大、它长什么样、它怎么被点中------全部由这颗 JSON 树的一个节点来描述。再也没有游离在数据结构之外的"野状态"了。

纯元数据驱动带来的红利

当你把屏幕上所有花里胡哨的图形，都严格浓缩成上述哪怕只有几百 KB 大小的纯 JSON 文本时，奇迹发生了：

1. 绝对纯净的持久化与协同 ：现在保存用户作品，不过就是做一次 JSON.stringify。而做多人协同，也不过是当某个 Node 的 x 发生改变时，通过 WebSocket 向房间里的其他人广播一个极小的 Diff 补丁 {"id": "node_1", "x": 250}。
2. 极其廉价的时间机器 ：撤销（Undo）与重做（Redo）再也不是什么黑科技。因为数据被极度抽象了，你只需要使用类似 Immer.js 等不可变数据结构工具，把每一步操作的 JSON 快照（或者 Delta 片段）保存在数组里，指针前后移动，就是时间倒流。
3. 彻底的跨端解耦：这套 Metadata 甚至都不知道 Canvas 的存在。你可以把同一团 JSON 丢给 Web 端用 Konva 渲染，扔给 iOS 用 CoreGraphics 渲染，或者丢给后端 Node 帮你无头渲染出一张 PDF。

---

接入状态管理：Zustand

有了元数据定义，接下来的问题是：这颗 JSON 树放在哪？谁来读它、写它、通知别人它变了？

绝不能让 Konva 本身（View 层）既当爹又当妈地去存储这些业务数据，这会导致视图状态和业务逻辑严重耦合。我们引入现代轻量级状态管理库 zustand 作为单一事实来源（Single Source of Truth），对整个工程做一次严格的分层。

打开 src/store.ts，这是整个工程的心脏：

// src/store.ts

export const canvasStore = createStore<CanvasState>((set) => ({
  // 全部元素的 Record 字典，key 为 id
  elements: initialElements,
  // 应用运行时状态（当前工具、缩放、视口偏移、选中态...）
  appState: defaultAppState,

  // --------- 以下全是纯函数式的 Actions ---------
  updateElementProps: (id, props) =>
    set((state) => ({
      elements: {
        ...state.elements,
        [id]: { ...state.elements[id], ...props },
      },
    })),

  addElement: (el) =>
    set((state) => ({
      elements: { ...state.elements, [el.id]: el },
    })),

  selectElement: (id) =>
    set((state) => ({
      appState: { ...state.appState, selectedElementIds: id ? [id] : [] },
    })),
  // ...
}));

值得反复品味的是：无论是创建元素、更新坐标、还是切换选中态，Store 里执行的全部都是浅拷贝替换 （{ ...state.elements, [id]: ... }）。没有任何副作用，没有任何直接 DOM 操作。这意味着前面说的 Undo/Redo "时间机器"，你只需要把这些 Immutable 快照存进一个栈里就好了------就是这么廉价。

---

引擎订阅：一个极致的"哑巴渲染器"

Store 管数据，那谁管画面？答案是 src/engine/index.ts------我们的引擎总控 EngineFacade。它做的事情极其克制：只读数据，只画画面。

// src/engine/index.ts --- 订阅逻辑

this.unsubscribe = canvasStore.subscribe((state) => {
  // 图元变更 → 重新渲染
  if (state.elements !== prevState.elements) {
    this.shapeRenderer.render(state.elements);
  }
  // 选中态变更 → 同步 Transformer 控制框
  if (state.appState.selectedElementIds !== prevState.appState.selectedElementIds) {
    this.selectionManager.syncSelection(state.appState.selectedElementIds);
  }
  // 视口变更 → 同步 Stage 缩放/平移
  if (state.appState.zoom !== prevState.appState.zoom || ...) {
    this.viewportManager.syncViewport(zoom, scrollX, scrollY);
  }
});

请注意这里的引用相等性比较（!==）。Zustand 的不可变数据范式保证了：只有当数据真正改变时，引用才会不同。所以引擎的每一次重绘都是精确触发的------不多画一帧，不少画一帧。

整个数据流形成了一个干净的单向环路：

用户操作 → Store 更新元数据 → Engine 监听到变更 → Konva 重绘画面
                ↑                                      │
                └──────── 用户拖拽，Engine 回写坐标 ────┘

Konva 永远不私自修改任何数据 。当用户拖拽一个图形时，Engine 层拦截 Konva 的 dragmove 事件，取得新坐标，然后调用 store.updateElementProps(id, { x, y }) 把新位置"汇报"回 Store。Store 更新后触发订阅回调，Engine 再根据新数据重绘------一切都是单向、可追溯的。

而浮在画布之上的 React UI（工具栏、属性面板）也是同一个 Store 的消费者：

// src/App.tsx --- 属性面板（精简）
const PropertiesPanel = () => {
  const selectedIds = useCanvasStore(
    (state) => state.appState.selectedElementIds,
  );
  const elements = useCanvasStore((state) => state.elements);
  const updateElementProp = useCanvasStore((state) => state.updateElementProp);

  const el = elements[selectedIds[0]];
  // 从 store 读数据，渲染颜色选择器、描边样式按钮...
  // 用户点击后，直接调用 updateElementProp() 回写 store
};

我们常说，前端框架 React 的核心公式是 UI = f(State)。 而无限白板的架构真谛就是：Canvas = Konva(Metadata)。

---

回望：四层地基已就位

至此，我们用四篇文章，自底向上地垒完了无限画布系统的四层地基：

层级	解决的核心问题	关键技术
坐标系	"无限"与"缩放"的数学本质	世界坐标 ↔ 屏幕坐标变换
渲染层	高性能绘制大量图形	Konva Scene Graph, 局部重绘
交互层	重建事件感知	离屏 Color Picking, Hit Testing
对象层	让画布拥有序列化的组织	元数据 Schema, Zustand 单向数据流

历经四篇文章的打磨，我们从最底层的数学坐标系起步，最终构筑起这套'可协同、可撤销、可跨端'的数据驱动画布架构。这段工程演进之路的破局关键，其实就是两个字：克制。清晰划定架构的分层边界，想透每一层该做什么，并坚决杜绝越界。

本系列 实例项目已上传GitHub github.com/Seanshi2025... 项目上有完整的架构组织文档。