在 React 中使用 JavaScript 将 HTML 转换为图片

缺点内向
23 阅读5分钟

在前端开发中，将 HTML 内容渲染为图片是一个常见的需求，例如生成分享海报、导出报表截图、保存富文本内容为图片等。传统方案多依赖 html2canvas 或后端服务，但在某些场景下，借助文档处理库也能实现类似效果。本文以一款基于 WebAssembly 的文档处理库为例，介绍在 React 项目中把 HTML 转换为图片的实现思路，并讨论其中的注意事项。

为什么需要 HTML 转图片

在实际项目中，这类需求通常来自以下几个方面：

  • 内容分享：将页面中的某个区域（如卡片、表格、富文本）导出为图片，便于在社交媒体传播。
  • 报表导出：将数据可视化结果或表格保存为图片，嵌入到文档或邮件中。
  • 存档与快照：记录某个时间点的页面渲染结果，作为凭证或历史记录。
  • 跨平台兼容：图片格式在各种设备和系统中都能一致显示，避免字体、布局差异。

前端常用的 html2canvas 通过遍历 DOM 并模拟绘制到 Canvas 来实现，但它对 CSS 的支持有限，复杂布局或跨域资源容易出问题。而使用文档处理库，则是另一条思路：先将 HTML 解析为文档对象，再渲染为图片。

基于 WebAssembly 的文档处理库简介

这里使用的库基于 WebAssembly，主要用于在浏览器中创建、编辑和转换 Word 文档。它支持将 HTML 内容加载为文档，并导出为多种格式，包括图片。由于底层是 WebAssembly，运行在浏览器中时无需后端参与，适合纯前端场景。

在 React 中使用时，需要注意它的加载方式与生命周期管理，避免重复初始化或内存泄漏。

在 React 中集成的基本步骤

1. 加载 WASM 模块

这类库的 WASM 模块体积通常较大，示例代码采用动态导入的方式，在组件挂载后异步加载。这样既能避免阻塞首屏渲染，也便于配合打包工具做代码分割：

import React, { useState, useEffect } from 'react';

function App() {
  const [wasmModule, setWasmModule] = useState(null);

  useEffect(() => {
    (async () => {
      try {
        const publicUrl = process.env.PUBLIC_URL || '';
        const spireModule = await import(/* webpackIgnore: true */ `${publicUrl}/spire.doc.js`);
        const rawModule = spireModule.default || spireModule;
        window.wasmModule = typeof rawModule === 'function'
          ? await rawModule({ locateFile: p => p.endsWith('.wasm') ? `${publicUrl}/${p}` : p })
          : rawModule;
        setWasmModule(window.wasmModule);
      } catch (error) {
        console.error('Failed to load WASM module:', error);
      }
    })();
  }, []);

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert HTML to Image Using JavaScript in React</h1>
      <button disabled={!wasmModule}>Convert</button>
    </div>
  );
}

export default App;

这里通过 window.wasmModule 挂载模块，主要是为了方便在后续的转换函数中访问。按钮在模块未加载完成时保持禁用状态，避免用户提前点击导致错误。

需要注意的是，spire.doc.js 和 .wasm 文件通常需要放在 public 目录下，或通过 CDN 引入，因为动态导入的路径是基于运行时 URL 解析的，而不是打包器的模块解析。

2. 将 HTML 文件转换为图片

如果 HTML 内容以文件形式存在，可以将其放入虚拟文件系统（VFS），再加载为文档：

const HtmlToImage = async () => {
  const wasmModule = window.wasmModule.spiredoc;
  if (!wasmModule) return;

  // 加载字体文件到虚拟文件系统
  await window.spire.FetchFileToVFS('CALIBRI.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);

  const inputFileName = 'sample.html';

  // 将 HTML 文件加载到 VFS
  await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

  // 创建 Document 实例
  const doc = new wasmModule.Document();

  // 加载 HTML 文件
  doc.LoadFromFile({ fileName: inputFileName, fileFormat: wasmModule.FileFormat.Html, validationType: wasmModule.XHTMLValidationType.None });

  // 将第一页保存为图片流
  let image = doc.SaveImageToStreams({ pageIndex: 0, type: wasmModule.ImageType.Bitmap });

  const outputFileName = 'HtmlToImage.png';
  image.Save(outputFileName);

  // 从 VFS 读取生成的图片
  const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
  const modifiedFile = new Blob([modifiedFileArray], { type: 'image/png' });
  const url = URL.createObjectURL(modifiedFile);

  // 触发下载
  const a = document.createElement('a');
  a.href = url;
  a.download = outputFileName;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);

  // 释放资源
  doc.Dispose();
};

几个关键点值得说明：

  • 字体加载：由于文档渲染依赖字体，如果不提前将字体文件放入 VFS，文本可能无法正确显示。示例中使用 CALIBRI.ttf，实际项目中可根据需要替换。
  • pageIndex: 0：只导出第一页。如果 HTML 内容较长，可以根据页数循环导出多张图片。
  • VFS 读写：库运行在 WebAssembly 沙箱中，生成的文件先写入虚拟文件系统，再通过 window.dotnetRuntime.Module.FS.readFile 读出为字节数组。
  • Dispose()：每次转换完成后需要调用，释放 WASM 堆内存，否则多次转换可能导致内存持续增长。

3. 将 HTML 字符串转换为图片

如果 HTML 内容不是文件，而是运行时拼接的字符串，可以直接通过 AppendHTML 方法追加到段落中：

const HtmlStringToImage = async () => {
  const wasmModule = window.wasmModule.spiredoc;
  if (!wasmModule) return;

  // 加载字体
  await window.spire.FetchFileToVFS('CALIBRI.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);

  const doc = new wasmModule.Document();
  const outputFileName = 'HtmlStringToImage.png';

  // 构造 HTML 字符串
  let HTML = "<html><head><style>";
  HTML += "body { font-family: 'Calibri'; }";
  HTML += "h1 { color: #FF5733; font-size: 24px; margin-bottom: 20px; }";
  HTML += "p { color: #333333; font-size: 16px; margin-bottom: 10px; }";
  HTML += "ul { list-style-type: disc; margin-left: 20px; }";
  HTML += "table { border-collapse: collapse; width: 100%; }";
  HTML += "th, td { border: 1px solid #CCCCCC; padding: 8px; }";
  HTML += "</style></head><body>";
  HTML += "<h1>This is a Heading</h1>";
  HTML += "<p>This is a paragraph demonstrating the conversion.</p>";
  HTML += "<ul><li>Item 1</li><li>Item 2</li></ul>";
  HTML += "<table><tr><th>Product</th><th>Price</th></tr>";
  HTML += "<tr><td>Jacket</td><td>$150</td></tr></table>";
  HTML += "</body></html>";

  // 添加节和段落
  let section = doc.AddSection();
  let paragraph = section.AddParagraph();

  // 将 HTML 字符串追加到段落
  paragraph.AppendHTML(HTML.toString('utf8', 0, HTML.length));

  // 导出第一页为图片
  let image = doc.SaveImageToStreams({ pageIndex: 0, type: wasmModule.ImageType.Bitmap });

  // 从 VFS 读取并生成下载链接
  const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
  const modifiedFile = new Blob([modifiedFileArray], { type: 'image/png' });
  const url = URL.createObjectURL(modifiedFile);

  const a = document.createElement('a');
  a.href = url;
  a.download = outputFileName;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);

  doc.Dispose();
};

与文件方式相比，字符串方式更灵活，适合内容动态生成的场景。不过需要注意，AppendHTML 是将 HTML 追加到段落中，而不是替换整个文档内容，因此复杂布局可能需要多次调用或调整结构。

注意事项与局限性

在实际使用中，有几个问题值得留意：

  1. 包体积：WebAssembly 模块通常较大，首次加载可能较慢，建议配合代码分割和懒加载。
  2. 内存管理：每次转换后应及时调用 Dispose() 释放文档对象，避免内存累积。
  3. 样式还原度：文档库对 CSS 的支持有一定边界，内联样式和简单选择器兼容性较好，Flex/Grid 等复杂布局可能无法完全还原。
  4. 字体依赖：需要提前将字体文件放入 VFS，否则文本渲染可能异常。
  5. 路径配置：spire.doc.js 和 .wasm 文件需要放在可访问的静态路径下，动态导入的 URL 与打包器的模块解析机制不同，需要特别注意。

与其他方案的对比

方案优点缺点
html2canvas纯前端、使用广泛CSS 支持有限、跨域问题
后端截图服务还原度高、可控性强需要服务器、增加延迟
基于 WebAssembly 的文档库纯前端、文档处理能力强包体积大、样式支持有边界
SVG foreignObject原生、无需额外库兼容性差、样式限制多

选择哪种方案，取决于具体需求：如果只是简单卡片导出，html2canvas 可能更轻量；如果需要与 Word 文档处理结合，或对文档结构有要求，基于 WebAssembly 的文档库会更有优势。

总结

本文介绍了在 React 中把 HTML 转换为图片的两种方式：从 HTML 文件加载和从 HTML 字符串追加。整体流程可以概括为：加载 WASM 模块 → 准备字体与文件 → 创建 Document 实例 → 加载或追加 HTML → 导出为图片流 → 从 VFS 读取并下载 → 释放资源。

HTML 转图片没有银弹，不同方案各有取舍。理解其原理和边界，才能根据项目场景做出合适的选择。希望本文能为你在 React 中处理类似需求时提供一些参考。

avatar
文章
阅读
粉丝