React 驱动的批量图片合成：利用 Canvas 协调器处理工业级排版

各位早上好，各位前端工程师，各位追求极致体验的艺术家们。

今天我们要聊的话题有点“硬核”，也有点“性感”。想象一下，你的用户上传了 100 张照片，想要把它们拼成一张巨大的海报，或者生成 500 个带有不同二维码和名字的证件照。如果你直接在 React 里写个 for 循环，把所有图片 ctx.drawImage 画上去，然后等着浏览器崩溃，那显然不是我们“资深编程专家”该干的事。

今天，我们要探讨的是：React 驱动的批量图片合成：利用 Canvas 协调器处理工业级排版。

我们要构建的东西，不仅仅是一堆图片的堆砌，而是一个像流水线一样的工业级加工厂。

第一部分：当 Canvas 冻结浏览器时——我们需要一个“工头”

让我们先从一个常见的前端噩梦开始。很多初学者，甚至是工作几年的老鸟，喜欢在 useEffect 里干这种事：

// 禁止这种写法，这会直接让页面变成一坨死肉
const handleProcess = () => {
  for (let i = 0; i < 100; i++) {
    const img = new Image();
    img.src = `...${i}.jpg`;
    img.onload = () => {
      ctx.drawImage(img, x, y);
    };
  }
};

你可能会问：“这有什么问题？画出来不就行了吗？”

问题大了去了。JavaScript 是单线程的，主线程负责 UI 渲染，顺便还要听你发号施令。当你把 100 张图片塞进 for 循环，并且假设这些图片都是高清大图（比如 4K 分辨率），每一张图片的处理、解码、绘制，都需要消耗大量的 CPU 时间。

这时候，你的浏览器就卡住了。鼠标转圈，滚动条不动，用户开始疯狂点击“取消”按钮，心里骂娘：“这网页是不是死了？”

这就是我们需要“协调器”的原因。

协调器，就是那个站在工厂流水线最上面的工头。它的职责不是亲自去画每一张画，而是：

1. 排队：把 100 张图片变成一个有序的队列。
2. 派单：根据 CPU 的承受能力，每次只派发 5 张任务给 Canvas。
3. 监控：看着任务进度，一旦有图片加载失败，立刻报警，而不是把后面所有的图都卡住。
4. 回调：任务全部做完后，通知 React 更新 UI（比如显示一个漂亮的进度条，最后放出一个“下载”按钮）。

第二部分：React 的角色——它是 UI 的指挥官

在这个架构里，React 不负责“画”。React 负责的是“看”和“管”。

React 是个乖孩子，它负责管理状态：currentStep（当前是第几张），progress（进度百分比），statusMessage（显示“正在处理图片 45/100…”）。

而“画”这个脏活累活，交给 Canvas。但是，Canvas 和 React 之间必须有一个解耦层。如果 React 的状态更新直接触发 Canvas 绘制，那还是回到了单线程阻塞的老路。

我们需要一种机制，让 React 告诉协调器：“嘿，我传了 100 张图，你看着办。” 然后协调器默默地在后台跑，跑完了告诉 React：“搞定，给我结果。”

第三部分：工业级排版的核心逻辑

既然是“工业级排版”，光把图贴上去是不够的。我们需要考虑像素级的对齐、缩放和留白。

这就像盖楼一样。你不能随便把砖头扔上去，你得有承重墙，有窗户，有门。

1. 智能缩放与裁剪

图片的尺寸千奇百怪。有的宽，有的高，有的长宽比是 16:9，有的是 1:1。
在工业级排版中，我们需要一套算法。

• Cover 模式：把图片塞进框里，把多余的部分切掉。适合做拼图。
• Contain 模式：把图片塞进去，留白。适合做展示。
• Contain + Background：如果图片小，背景涂什么颜色？这决定了最终产品的视觉风格。

2. 自动换行与网格计算

想象一下，你有一堆拼图碎片（图片），你想把它们拼在一个大画布上。怎么排？第一行放 4 张，第二行放 5 张？这涉及到数学计算。

我们需要一个布局算法。在 DOM 里，这是 CSS Grid 的事；但在 Canvas 里，这就是数学。我们需要计算 (x, y) 坐标。

// 简单的网格计算逻辑伪代码
const calculateLayout = (images, rows, cols) => {
  const cellWidth = canvasWidth / cols;
  const cellHeight = canvasHeight / rows;

  return images.map((img, index) => {
    const col = index % cols;
    const row = Math.floor(index / cols);

    return {
      img: img,
      x: col * cellWidth,
      y: row * cellHeight,
      width: cellWidth,
      height: cellHeight
    };
  });
};

这还不够“工业级”。工业级意味着要处理动态尺寸。比如，有些图片特别大，有些特别小。简单的网格会留下很多空隙。

这时候，我们需要流式布局算法或者动态网格算法，甚至要引入 Bounding Box（包围盒）的概念来计算最佳的排版位置。但这已经超出了“Canvas 协调器”的范畴，更多是排版算法的领域。作为协调器，我们要保证这些复杂的排版逻辑能被异步执行，不会阻塞主线程。

第四部分：编写协调器——代码实战开始

现在，让我们来写点真正的代码。我们将构建一个基于 Worker 的协调器。

1. 调度器

我们需要一个 Worker 来处理繁重的图像操作。我们可以通过 Blob URL 在单文件中动态创建 Worker，这样就不需要额外的文件。

// worker.js 的内容，我们把它当做字符串
const workerCode = `
  self.onmessage = async function(e) {
    const { taskId, images, layoutConfig, canvasWidth, canvasHeight } = e.data;

    // 创建离屏 Canvas
    const canvas = new OffscreenCanvas(canvasWidth, canvasHeight);
    const ctx = canvas.getContext('2d');

    // 遍历布局配置
    for (let item of layoutConfig) {
      // 1. 绘制背景
      ctx.fillStyle = item.bgColor || '#ffffff';
      ctx.fillRect(item.x, item.y, item.width, item.height);

      // 2. 加载并绘制图片 (异步操作)
      const img = new Image();
      img.src = item.img;

      // 等待图片加载
      await new Promise(resolve => {
        img.onload = resolve;
        img.onerror = () => {
          console.error('图片加载失败', item.img);
          resolve(); // 即使失败也继续，避免死锁
        };
      });

      // 3. 图像处理逻辑 (Cover/Center)
      // 简单的居中绘制逻辑
      const scale = Math.min(item.width / img.width, item.height / img.height);
      const x = item.x + (item.width / 2) - (img.width / 2) * scale;
      const y = item.y + (item.height / 2) - (img.height / 2) * scale;

      ctx.drawImage(img, x, y, img.width * scale, img.height * scale);

      // 4. 绘制边框（为了工业级效果）
      ctx.strokeStyle = '#ddd';
      ctx.lineWidth = 2;
      ctx.strokeRect(item.x, item.y, item.width, item.height);
    }

    // 5. 导出结果
    const bitmap = canvas.transferToImageBitmap();
    self.postMessage({ taskId, result: bitmap }, [bitmap]);
  };
`;

// 将 Worker 代码转为 Blob URL
const blob = new Blob([workerCode], { type: 'application/javascript' });
const workerUrl = URL.createObjectURL(blob);

2. 协调器类

现在，我们需要一个类来管理这些 Worker。这就好比理发店那个拿着剪刀的理发师，他同时只能服务 3 个顾客。

class ComposerCoordinator {
  constructor(maxConcurrency = 4) {
    this.maxConcurrency = maxConcurrency;
    this.queue = [];
    this.activeTasks = 0;
    this.onProgress = null;
    this.onComplete = null;

    // 实例化 Worker
    this.worker = new Worker(workerUrl);
    this.worker.onmessage = this.handleWorkerMessage.bind(this);
  }

  // 添加任务到队列
  enqueue(task) {
    this.queue.push(task);
    this.processQueue();
  }

  processQueue() {
    while (this.queue.length > 0 && this.activeTasks < this.maxConcurrency) {
      const task = this.queue.shift();
      this.activeTasks++;
      this.worker.postMessage(task);
    }
  }

  handleWorkerMessage(e) {
    const { taskId, result } = e.data;
    this.activeTasks--;

    // 通知 React 任务完成
    if (this.onComplete) {
      this.onComplete(taskId, result);
    }

    // 继续处理下一个
    this.processQueue();
  }

  // 错误处理与取消
  cancel() {
    this.queue = [];
    this.worker.terminate();
  }
}

3. React Hook 的封装

最后，我们将这一切封装进 React 的 Hook 里。这是工业级产品中最常用的模式。

import React, { useState, useRef, useCallback } from 'react';

const useBatchComposer = () => {
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState('idle');
  const [resultUrl, setResultUrl] = useState(null);

  // 使用 ref 存储协调器，避免重复创建
  const coordinatorRef = useRef(null);

  // 初始化协调器（带防抖，避免组件重新挂载时重复初始化）
  useEffect(() => {
    if (!coordinatorRef.current) {
      coordinatorRef.current = new ComposerCoordinator(4); // 开启 4 个并发
    }

    coordinatorRef.current.onProgress = (current, total) => {
      setProgress(Math.round((current / total) * 100));
      setStatus(`正在合成第 ${current}/${total} 张...`);
    };

    coordinatorRef.current.onComplete = (taskId, bitmap) => {
      // 将 ImageBitmap 转换为 DataURL 以供 React 显示
      const url = URL.createObjectURL(bitmap);
      setResultUrl(url);
      setStatus('合成完成！');
      setProgress(100);
    };

    return () => {
      // 组件卸载时清理资源
      if (coordinatorRef.current) {
        coordinatorRef.current.cancel();
        coordinatorRef.current = null;
      }
    };
  }, []);

  const startCompose = useCallback(async (images, config) => {
    setStatus('准备开始...');

    // 1. 计算布局 (这部分逻辑可以放在主线程或 Worker，这里为了演示放在主线程)
    const layoutConfig = calculateIndustrialLayout(images, config);

    // 2. 构建任务对象
    const task = {
      taskId: Date.now(),
      images: images, // 传图片数据
      layoutConfig: layoutConfig,
      canvasWidth: config.width,
      canvasHeight: config.height
    };

    // 3. 投递给协调器
    coordinatorRef.current.enqueue(task);
  }, []);

  return {
    progress,
    status,
    resultUrl,
    startCompose,
    isProcessing: status.includes('正在')
  };
};

// 辅助函数：工业级布局计算
function calculateIndustrialLayout(images, config) {
  // 这里可以加入复杂的算法：如自动换行、按高度排序、按重要性排序等
  const { rows, cols, padding } = config;
  const cellWidth = (config.width - (cols - 1) * padding) / cols;
  const cellHeight = (config.height - (rows - 1) * padding) / rows;

  return images.map((img, index) => {
    const col = index % cols;
    const row = Math.floor(index / cols);

    return {
      img: img, // 这里的 img 应该是一个对象 { url: '...', id: '...' }
      bgColor: index % 2 === 0 ? '#f5f5f5' : '#ffffff', // 交替背景色，提升视觉层次
      x: col * (cellWidth + padding),
      y: row * (cellHeight + padding),
      width: cellWidth,
      height: cellHeight
    };
  });
}

第五部分：工业级排版的“那些坑”与“黑魔法”

光有上面的代码还不够，生产环境里到处都是坑。作为一名资深专家，我必须告诉你那些文档里不会写的细节。

1. 内存泄漏的幽灵

当你使用 canvas.transferToImageBitmap() 时，注意，这并不是副本，它是所有权转移！
如果你在 React 的 useEffect cleanup 里只是 worker.terminate()，但如果你的 onComplete 回调里生成的 resultUrl 被某个 DOM 节点引用着，那这个 Bitmap 就不会销毁，内存就会泄漏。

解决方案：一定要在组件卸载时，或者状态更新后，显式地调用 URL.revokeObjectURL(url)。

2. 高 DPI (Retina) 屏幕适配

在手机上，Canvas 画出来的图会模糊。这是因为物理像素和逻辑像素的比例。
工业级排版必须支持 DPR (Device Pixel Ratio)。
计算公式：canvas.width = logicalWidth * dpr;
然后在绘制的时候，所有的 x, y 坐标都要乘以 dpr，大小都要乘以 dpr。最后导出图片时，如果不处理，图片也是高清的（取决于 canvas 的最终尺寸）。这会让你的合成图在视网膜屏上清晰得令人发指。

3. 并发控制的微调

我们设置了 maxConcurrency = 4。这只是一个经验值。
如果你处理的是纯文本合成（比如生成 1000 个 PDF 页面），4 个 Worker 可能不够快。
如果你处理的是 4K 视频截图的缩放，4 个 Worker 可能直接把 CPU 占满导致浏览器主线程（UI 线程）卡死。
监控是关键。最好的协调器会根据 navigator.hardwareConcurrency 自动调整并发数。

4. 错误隔离

在 Worker 的代码里，我写了 img.onerror = () => resolve()。这是一个非常重要的防御性编程策略。
如果队列里有 100 张图，其中第 50 张图片链接失效了。如果你不捕获错误，整个 Worker 会抛出异常，导致队列里的剩余 50 张图全部处理失败。这就是所谓的“一个老鼠屎坏了一锅粥”。

第六部分：性能优化的终极奥义

为了达到真正的工业级标准，我们需要更进一步。我们需要考虑资源预加载和二进制传输。

资源预加载

在点击“开始合成”之前，React 应该先默默地把所有图片的 Blob 对象或者 DataUrl 获取到。这样，当 Worker 队列空出来的时候，不需要再等待网络 I/O，Worker 可以直接处理。这就像在开饭前先把菜都切好放在案板上。

二进制流处理

在 useBatchComposer 的例子中，我们使用了 transferToImageBitmap。这是目前浏览器性能最好的方式之一。它利用了 Shared Memory 的原理，零拷贝地将数据交给主线程。千万不要在 Worker 里把 Canvas 转成 Base64 字符串传回来，那个性能损耗是指数级的！

第七部分：调试策略

当你写好了一套复杂的合成系统，怎么知道它对不对？

1. 控制台日志：在 Worker 里，打印出每一张图的 width 和 height。对比一下，是不是每一张都被正确地裁剪了？
2. 断点调试：Chrome 的 DevTools 支持 Worker 的断点调试。你可以单步执行 Worker 里的代码。
3. 视觉检查：在 React 里，生成一张缩略图，展示给用户看。如果用户觉得丑，你不需要重新合成整张大图，只需要调整 layoutConfig 里的参数，然后再次触发。

结语：代码的艺术

写 React + Canvas 的批量合成，就像是在走钢丝。

左边是 React 的响应式状态管理，右边是 Canvas 的原生像素操作。中间是一个精心设计的“协调器”。

它要求你既懂 React 的闭包、生命周期和状态更新机制，又懂 Canvas 的 2D 绘图上下文、离屏渲染，还要懂 JavaScript 的异步编程模型和 Web Worker。

当你成功运行这段代码，看着进度条从 0% 慢慢跑到 100%，看着生成的合成图清晰、整洁、排版完美地展示在屏幕上时，那种成就感是无可替代的。

这不仅仅是写代码，这是在编写一个“视觉处理器”。希望今天的讲座能帮你构建出属于你自己的工业级图片合成工厂。

现在，拿起你的键盘，去合成第一张图片吧！