如何使用ExcelJS插入指定单元格图片并实现尺寸适配

原代码的问题根源 #

• 没有给数据行设置固定行高，Excel 默认行高远小于产品图片的原始尺寸，图片会溢出覆盖相邻单元格内容
• 调用addImage时直接传入C${position}:C${position}这类单单元格范围字符串，ExcelJS 会直接把图片按原始尺寸锚定在单元格左上角，不会自动拉伸适配单元格的实际大小

实现步骤调整 #

1. 先明确Excel尺寸的固定换算关系 #

很多人做适配时卡壳是因为没搞懂Excel的单位和像素的映射规则，提前算好对应值就行：

• 列宽（单位：字符）转像素：对应像素宽 = 列宽值 * 7 + 5
  例子里设置的C列宽度是50，算下来像素宽度就是355px
• 行高（单位：磅）转像素：对应像素高 = 行高值 * 1.333
  比如设置数据行行高为90磅，换算下来就是120px左右的实际高度

2. 手动给每一行设置固定行高 #

Excel自带的自动行高对插入的浮动图片完全不生效，每新增一条产品数据行，直接给该行赋值固定行高值。

3. 改用对象锚点传参插入图片 #

放弃字符串形式的范围参数，改用对象形式定义锚点位置，同时手动指定图片的拉伸宽高，完全匹配单元格的实际像素尺寸。

调整后的可运行代码 #

// 统一配置尺寸参数，后续调整大小只需要改这里就行
const IMAGE_COL_WIDTH = 50;  // C列的宽度配置
const DATA_ROW_HEIGHT = 90;  // 数据行的行高配置，单位磅

result.map(order => {
  const worksheet = workbook.addWorksheet(order.branch_code);

  worksheet.columns = [
    { header: 'Id', key: 'id', width: 10 },
    { header: 'Product Code', key: 'pcode', width: 20 },
    { header: 'Image', key: 'image', width: IMAGE_COL_WIDTH },
  ];

  // position初始值要设为2，因为第1行是表头，第一个数据行在第2行
  let position = 2;

  order.products.map(product => {
    // 加载本地图片到工作簿
    const imageId = workbook.addImage({
      filename: `${PRODUCT_IMAGE_PATH}/${product.image}`,
      extension: 'jpeg',
    });

    // 新增数据行
    const currentRow = worksheet.addRow({ 
      id: product.products.id, 
      pcode: product.products.product_code 
    });
    // 给当前行设置固定行高
    currentRow.height = DATA_ROW_HEIGHT;

    // 计算单元格对应的实际像素尺寸
    const cellPixelWidth = IMAGE_COL_WIDTH * 7 + 5;
    const cellPixelHeight = DATA_ROW_HEIGHT * 1.333;

    // 按单元格尺寸插入并缩放图片
    worksheet.addImage(imageId, {
      // 左上角锚点：列索引从0开始，C列是第3列所以是2；行索引要和Excel行号对应，第2行对应索引1
      tl: { col: 2, row: position - 1 },
      // 右下角锚点：刚好锚定到单元格的右边界、下边界
      br: { col: 3, row: position },
      // 强制指定图片宽高，覆盖图片原始尺寸
      ext: {
        width: cellPixelWidth,
        height: cellPixelHeight
      }
    });

    position++;
  });
});

await workbook.xlsx.writeFile('export.xlsx');

注意事项 #

• ExcelJS 内部的行、列索引都是从0开始计数的，写锚点位置时不要和Excel界面显示的行号、列字母混淆
• ext参数的优先级高于锚点自动计算的尺寸，按这个参数设置的宽高缩放图片后，不管原始图片尺寸多大，都会刚好填满对应的单元格区域，不会出现溢出变形的问题
• 如果需要图片和单元格保留一点内边距，只需要在计算目标宽高时适当减去几像素的内边距值就行

内容的提问来源于stack exchange，提问作者Thorin