JSZip如何正确嵌入图片到Excel文件？

Question

在使用 JSZip 将图片嵌入 Excel 文件（.xlsx）时，一个常见问题是：**图片已写入 zip 包的 `media/` 目录，但在 Excel 中无法显示**。该问题通常源于未正确更新 Excel 的 XML 关系文件（如 `worksheets/_rels/sheet1.xml.rels`）或缺少对应的 `` 引用与 `drawings/drawing1.xml` 配置。JSZip 虽可打包图片二进制数据，但必须手动构造 OPC 规范所要求的结构化关系和绘图对象引用，否则 Excel 无法识别图片资源。如何通过 JSZip 正确维护这些 XML 映射关系，成为动态插入图片的关键难点。

Answer 1

1. 问题初探：JSZip 写入图片后 Excel 不显示的表象

在使用 JSZip 动态生成或修改 .xlsx 文件时，开发者常通过 zip.file("xl/media/image1.png", imageData, { base64: true }) 将图片写入 media/ 目录。尽管文件结构看似完整，但打开 Excel 时图片并未呈现。

• 图片存在于 ZIP 包中
• Excel 客户端无法识别该资源
• 无报错提示，仅“空白”单元格

这表明问题不在数据写入本身，而在于资源与工作表之间的“引用链”断裂。

2. 深层机制：OPC 规范与 Excel 的关系模型

.xlsx 实质是基于 OPC（Open Packaging Conventions）的 ZIP 容器，其内部组件通过 XML 关系（.rels）文件建立连接。图片要被渲染，需满足以下三个条件：

1. 图片存于 xl/media/
2. 工作表关联一个绘图部件（drawing）
3. 绘图部件通过 rels 引用图片资源

组件	路径	作用
Image File	xl/media/image1.png	存储图像二进制
Drawing Part	xl/drawings/drawing1.xml	定义图形布局
Drawing Rel	xl/drawings/_rels/drawing1.xml.rels	映射图片 ID
Sheet Rel	xlsx/worksheets/_rels/sheet1.xml.rels	绑定 drawing 到 sheet

3. 核心难点：手动维护 XML 映射关系

JSZip 仅提供 ZIP 操作能力，不解析或生成 Office Open XML 结构。因此，插入图片必须手动构造以下内容：

// 示例：向 sheet1.xml.rels 添加 drawing 引用
{
  "Id": "rId2",
  "Type": "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
  "Target": "drawings/drawing1.xml"
}

同时需确保 sheet1.xml 中包含 <drawing r:id="rId2"/> 节点。

4. 解决方案设计：构建完整的图片注入流程

实现步骤如下：

1. 解压原始 xlsx 模板（使用 JSZip）
2. 分析现有 rels 编号，避免冲突
3. 生成新的 drawing 和 image rel ID
4. 创建 drawings/drawing1.xml 描述形状与锚点
5. 更新 _rels/drawing1.xml.rels 指向 media 图片
6. 修改 worksheets/_rels/sheet1.xml.rels 添加 drawing 引用
7. 在 sheet1.xml 插入 <drawing> 节点
8. 重新打包为 blob 并导出

5. 代码示例：动态添加图片关系引用

function addImageToSheet(zip, imageName, imageData) {
  const mediaPath = `xl/media/${imageName}`;
  const drawingRelPath = 'xl/drawings/_rels/drawing1.xml.rels';
  const sheetRelPath = 'xl/worksheets/_rels/sheet1.xml.rels';

  // 写入图片
  zip.file(mediaPath, imageData, { base64: true });

  // 获取或初始化 drawing rels
  let drawingRels = zip.file(drawingRelPath)?.asText();
  let relsJson = drawingRels ? JSON.parse(drawingRels) : { Relationships: [] };
  
  const newId = `rId${relsJson.Relationships.length + 1}`;
  relsJson.Relationships.push({
    Id: newId,
    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
    Target: `../media/${imageName}`
  });
  zip.file(drawingRelPath, JSON.stringify(relsJson));

  return newId;
}

6. 流程图：图片嵌入全流程逻辑

graph TD A[开始] --> B{读取xlsx模板} B --> C[解析ZIP结构] C --> D[写入图片至xl/media/] D --> E[生成drawing1.xml] E --> F[更新drawing1.xml.rels] F --> G[修改sheet1.xml.rels] G --> H[在sheet1.xml插入drawing节点] H --> I[重新打包ZIP] I --> J[输出Blob供下载]

7. 常见陷阱与调试建议

• ID 冲突：重复使用 rId 导致解析失败
• 路径错误：相对路径层级不正确（如未使用 ../media）
• 缺少命名空间：XML 中未声明 xmlns:a="..." 等前缀
• 未更新 content_types.xml：应添加 <Override PartName="/xl/media/image1.png" ContentType="image/png"/>
• Excel 缓存：关闭重开文件，避免缓存旧结构

推荐使用 Open XML SDK Tool 分析生成文件结构。

8. 高级优化：支持多图、位置控制与缩放

可通过调整 twoCellAnchor 中的 from 与 to 坐标实现精确定位：

<xdr:from>
  <xdr:col>2</xdr:col>
  <xdr:colOff>0</xdr:colOff>
  <xdr:row>5</xdr:row>
  <xdr:rowOff>0</xdr:rowOff>
</xdr:from>

结合列宽行高换算像素偏移，可实现像素级对齐。