在 React 和 Vue 项目中正确集成与封装 Fabric.js 组件

一、集成中的三大底层冲突与规避策略

Fabric.js 是一个成熟的基于命令式调用的 HTML5 Canvas 库，其内部维护着复杂的对象树（Display Tree）、双向事件发射器、变换矩阵计算栈以及私有渲染上下文。在将其接入 React 或 Vue 时，有三个必须首先解决的技术断层。

1. 响应式系统深层代理引发的灾难

Vue 3 的 reactive() 或深度 ref() 会通过 ES6 Proxy 递归包装目标对象及其所有属性。Fabric 实例包含大量内部属性（例如 _objects、canvas.contextContainer、原型链事件监听器等）。一旦这些对象被 Proxy 包裹，Fabric 内部原生的引用全等判断（例如 target === this 或在事件冒泡时比对原始 DOM 事件）将全部失真，不仅引发频繁的多余渲染，还会造成拖拽失灵或控制点计算报错。

在 React 中，如果错误地将 Fabric 实例存放在 useState 中，每次操作画布调用 setCanvas(instance) 不仅毫无意义，而且会频繁触发 React 树的全量重新渲染（re-render）。更严重的是，React 组件重新渲染时闭包内捕获的事件回调容易错位，导致引用到已经被解绑的旧实例。

2. 虚拟 DOM 脱节与 DOM 双重嵌套泄漏

Fabric 在初始化时，会以宿主 <canvas> 标签为基准，在外部动态创建一个名为 .canvas-container 的包装容器，并生成上下两层 Canvas（一层承载实际图像，另一层负责用户鼠标选区与控制点交互）。

当虚拟 DOM 树由于路由跳转或条件渲染（如 v-if）将原有的 <canvas> 卸载时，Fabric 动态注入的外部 DOM 节点以及挂载在全局 window 上的键盘、鼠标事件监听器并不会自动清除。如果再次挂载，Fabric 会在旧容器内或同级位置再次创建一组新包装层，最终导致画布层层叠加、内存持续飙升。

3. 高分屏（Retina）物理像素与 CSS 逻辑像素校准

直接通过 CSS 给 <canvas> 设置宽高的做法是完全错误的。CSS 仅改变画布在屏幕上的显示拉伸比，而不会调整其底层绘图缓冲区的物理像素大小，最终会导致绘制出的文字、线条模糊发虚。必须通过 Fabric 提供的 API，将设备像素比（window.devicePixelRatio）与容器逻辑像素严格同步。

二、标准化生命周期与集成步骤

要保证 Fabric.js 在组件生命周期内稳定运行，必须遵循一套严格的流水线操作流程。无论使用哪种框架，以下五个步骤都必须依次执行并形成闭环：

1. 准备挂载容器与 Ref 绑定：在模板中声明原生 <canvas> 标签，并将其包裹在拥有明确宽高计算规则的父级容器中。
2. 初始化实例并隔离响应式：在 DOM 挂载就绪的回调中执行 new fabric.Canvas()，并立即将返回的实例存入非响应式容器。
3. 注入底层事件与建立数据管道：监听画布内部的关键交互事件（如 object:modified、selection:created），并将画布产出的纯业务数据（而非 Fabric 对象本身）向外抛出。
4. 接入视口尺寸观察器（ResizeObserver）：动态感知父容器的尺寸缩放，防抖调用 setDimensions 重新校准画布视口。
5. 组件注销时的完整清理（Dispose）：在卸载钩子中显式执行 canvas.dispose()，销毁 Fabric 生成的 DOM 结构，解除全部事件挂载，将引用重置为 null。

三、在 React 项目中的正确封装实践

在 React（18 及以上版本）中，由于引入了 StrictMode 双重挂载机制（开发环境下组件会经历 mount -> unmount -> mount），如果生命周期清理不彻底，第一遍创建的 Canvas 实例会被第二遍覆盖，留下无法回收的幽灵事件监听。

针对这一机制，我们封装一个专用的自定义 Hook useFabric，并在此基础上构建通用的 FabricCanvas 组件。

1. 自定义 Hook：useFabric.ts

import { useRef, useEffect, useCallback } from 'react';
import { fabric } from 'fabric';

interface UseFabricOptions {
  width?: number;
  height?: number;
  backgroundColor?: string;
  onObjectModified?: (e: fabric.IEvent) => void;
  onSelectionCreated?: (e: fabric.IEvent) => void;
}

export function useFabric(options: UseFabricOptions = {}) {
  // 宿主 DOM 的引用容器
  const canvasElRef = useRef<HTMLCanvasElement | null>(null);
  // Fabric 实例持久引用容器（绝不使用 useState）
  const fabricRef = useRef<fabric.Canvas | null>(null);

  useEffect(() => {
    if (!canvasElRef.current) return;

    // 1. 创建 Fabric 画布实例
    const canvas = new fabric.Canvas(canvasElRef.current, {
      width: options.width || 800,
      height: options.height || 600,
      backgroundColor: options.backgroundColor || '#FFFFFF',
      enableRetinaScaling: true,
      preserveObjectStacking: true,
    });

    fabricRef.current = canvas;

    // 2. 绑定必要事件
    if (options.onObjectModified) {
      canvas.on('object:modified', options.onObjectModified);
    }
    if (options.onSelectionCreated) {
      canvas.on('selection:created', options.onSelectionCreated);
    }

    // 3. 严格的清理函数（React 18 StrictMode 关键）
    return () => {
      canvas.off(); // 解绑全部 Fabric 内部事件
      canvas.dispose(); // 销毁 DOM 包装层与全局监听
      fabricRef.current = null; // 释放引用协助 GC
    };
  }, []); // 空依赖项，只在挂载和卸载时执行

  // 封装向外部暴露的受控 API
  const addRect = useCallback((rectOptions: fabric.IRectOptions = {}) => {
    const canvas = fabricRef.current;
    if (!canvas) return;

    const rect = new fabric.Rect({
      width: 100,
      height: 80,
      fill: '#456581',
      left: 100,
      top: 100,
      ...rectOptions,
    });
    canvas.add(rect);
    canvas.setActiveObject(rect);
    canvas.requestRenderAll();
  }, []);

  const clear = useCallback(() => {
    const canvas = fabricRef.current;
    if (!canvas) return;
    canvas.clear();
    canvas.setBackgroundColor(options.backgroundColor || '#FFFFFF', canvas.renderAll.bind(canvas));
  }, [options.backgroundColor]);

  const exportJSON = useCallback(() => {
    const canvas = fabricRef.current;
    if (!canvas) return {};
    return canvas.toJSON();
  }, []);

  return {
    canvasElRef,
    fabricRef,
    addRect,
    clear,
    exportJSON,
  };
}

2. 画板组件封装：FabricCanvas.tsx

在 UI 组件层面，我们只需要将 canvasElRef 赋给底层的 <canvas>，并将操作函数通过 props 或 Ref 向上透出：

import React from 'react';
import { useFabric } from './useFabric';

export const FabricCanvas: React.FC = () => {
  const { canvasElRef, addRect, clear, exportJSON } = useFabric({
    width: 720,
    height: 400,
    backgroundColor: '#F7F9FB',
    onObjectModified: (e) => {
      console.log('图形发生变更:', e.target);
    },
  });

  const handleExport = () => {
    const data = exportJSON();
    console.log('画布纯数据序列化:', data);
  };

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
      <div style={{ display: 'flex', gap: '8px' }}>
        <button onClick={() => addRect()}>添加矩形</button>
        <button onClick={clear}>清空画布</button>
        <button onClick={handleExport}>导出 JSON</button>
      </div>
      <div style={{ border: '1px solid #D9E2EC', borderRadius: '6px', overflow: 'hidden' }}>
        <canvas ref={canvasElRef} />
      </div>
    </div>
  );
};

四、在 Vue 3 项目中的正确封装实践

Vue 3 的 Composition API 提供了更自然的方式将生命周期与状态封装在可复用的组合式函数中。在 Vue 3 中封装 Fabric 的关键是运用 shallowRef 严格约束响应式边界，并通过 watch 同步外部 props 变更。

1. 组合式函数：useFabric.ts

import { shallowRef, onMounted, onBeforeUnmount, type Ref } from 'vue';
import { fabric } from 'fabric';

export interface UseFabricVueOptions {
  width?: number;
  height?: number;
  backgroundColor?: string;
}

export function useFabricVue(
  canvasEl: Ref<HTMLCanvasElement | null>,
  options: UseFabricVueOptions = {}
) {
  // 极其关键：必须使用 shallowRef，避免 Proxy 递归深度拦截
  const fabricCanvas = shallowRef<fabric.Canvas | null>(null);

  onMounted(() => {
    if (!canvasEl.value) return;

    // 初始化 Fabric 画布
    const canvas = new fabric.Canvas(canvasEl.value, {
      width: options.width ?? 800,
      height: options.height ?? 600,
      backgroundColor: options.backgroundColor ?? '#FFFFFF',
      enableRetinaScaling: true,
    });

    fabricCanvas.value = canvas;
  });

  onBeforeUnmount(() => {
    if (fabricCanvas.value) {
      fabricCanvas.value.off();
      fabricCanvas.value.dispose(); // 销毁 DOM 与全部监听器
      fabricCanvas.value = null;
    }
  });

  // 业务方法
  const addText = (text: string) => {
    if (!fabricCanvas.value) return;
    const textObj = new fabric.IText(text, {
      left: 150,
      top: 150,
      fontFamily: 'sans-serif',
      fontSize: 20,
      fill: '#2C3E50',
    });
    fabricCanvas.value.add(textObj);
    fabricCanvas.value.setActiveObject(textObj);
    fabricCanvas.value.requestRenderAll();
  };

  const clear = () => {
    if (!fabricCanvas.value) return;
    fabricCanvas.value.clear();
    fabricCanvas.value.setBackgroundColor(options.backgroundColor ?? '#FFFFFF', () => {
      fabricCanvas.value?.requestRenderAll();
    });
  };

  return {
    fabricCanvas,
    addText,
    clear,
  };
}

2. Vue 3 组件封装：FabricCanvas.vue

通过 <script setup lang="ts"> 搭配 defineExpose，让外部父组件能够以标准 Ref 的方式控制画板：

<template>
  <div class="fabric-wrapper">
    <div class="toolbar">
      <button @click="addText('示例文本')">添加文字</button>
      <button @click="clear">清空画布</button>
    </div>
    <div class="canvas-container-box">
      <canvas ref="canvasEl" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { useFabricVue } from './useFabricVue';

const props = defineProps<{
  width?: number;
  height?: number;
  bgColor?: string;
}>();

const canvasEl = ref<HTMLCanvasElement | null>(null);
const { fabricCanvas, addText, clear } = useFabricVue(canvasEl, {
  width: props.width ?? 720,
  height: props.height ?? 400,
  backgroundColor: props.bgColor ?? '#F7F9FB',
});

// 监听外部属性，通过受控命令式方法同步画布属性
watch(() => props.bgColor, (newColor) => {
  if (fabricCanvas.value && newColor) {
    fabricCanvas.value.setBackgroundColor(newColor, () => {
      fabricCanvas.value?.requestRenderAll();
    });
  }
});

// 向父组件暴露操作指令
defineExpose({
  addText,
  clear,
  getCanvasInstance: () => fabricCanvas.value,
});
</script>

五、实战中的高级处理与避坑指南

在企业级低代码平台或在线海报设计系统中，画板组件不仅需要画得出，更需要应对多屏幕自适应、缩放平移以及操作历史管理。

1. 结合 ResizeObserver 实现自适应流式布局

多数编辑器页面包含侧边栏折叠或视口拖拽缩放。如果直接用 CSS 对 <canvas> 赋予 width: 100%，会导致整个绘制内容拉伸变形。正确做法是在组件挂载后，用 ResizeObserver 观察画板的外层包裹容器，并在回调中调用 setDimensions：

const resizeObserver = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const { width, height } = entry.contentRect;
    if (canvas && width > 0 && height > 0) {
      // 必须通过 setDimensions 更新物理绘制缓冲像素
      canvas.setDimensions({ width, height });
      canvas.requestRenderAll();
    }
  }
});

if (containerEl) {
  resizeObserver.observe(containerEl);
}

2. 撤销（Undo）与重做（Redo）的历史栈设计

实现撤销重做时，初学者常犯的错误是把每个历史时刻的整个 Fabric 实例保留在数组中。这会瞬间导致几十兆甚至上百兆的内存消耗。正确做法是利用 canvas.toJSON() 保存纯序列化对象，利用双栈（Undo Stack / Redo Stack）管理快照：

• 序列化定制字段：默认的 toJSON() 只序列化 Fabric 标准字段。若业务中为图形挂载了 id、name 或 locked 等自定义属性，必须显式声明传参：canvas.toJSON(['id', 'name', 'locked'])。
• 防抖入栈：在监听 object:modified 或 object:added 时，用户连续拖动会触发大量事件，必须设置 200~300ms 的防抖时间，防止瞬间将撤销栈占满。
• 回放更新：撤销时弹出栈顶 JSON 字符串，通过 canvas.loadFromJSON(jsonString, canvas.renderAll.bind(canvas)) 恢复画面。

3. 状态管理分界（Pinia / Redux）

在全局 Store 中，绝对不能存储任何 Fabric 实例或 Fabric.Object 对象。Store 仅负责存储纯数据层（例如当前选中的图层 ID、画布层级配置、纯属性 JSON）。当用户在属性面板调整颜色时，由组件触发 Store 更新，再通过 Watcher 或 useEffect 调用 activeObject.set('fill', newColor) 命令式同步给 Fabric 画布。

六、总结

在 React 和 Vue 项目中集成 Fabric.js 并不复杂，关键在于建立清晰的技术边界：

一方面，将 Fabric.js 视为一个完全自治的命令式绘图沙箱，用 useRef 或 shallowRef 将其严密隔离在框架响应式系统之外；另一方面，在组件卸载时坚决执行 canvas.dispose() 闭环销毁全部 DOM 与事件监听。只要坚守“浅引用隔离”、“受控指令导出”与“数据单向同步”这三条准则，就能在保持框架现代工程体验的同时，充分享受 Fabric.js 带来的强大图形编辑能力。