前端导出 Excel 支持签名图片功能记录

背景

体检报告管理页面有一个"报告领取人签名"列，数据以 base64 图片格式存储在数据库中。最初导出 Excel 时使用了 xlsx 库，签名列只能输出[签名图片]占位文本，无法渲染为真实的图片。本文记录如何通过 exceljs 库实现前端导出含签名图片的 Excel 文件。

导出效果

技术选型

exceljs是一个支持在单元格中插入图片的 Excel 操作库，允许通过 workbook-level 的 API 精确控制图片的位置和尺寸。相较于 xlsx（SheetJS）仅支持纯文本表格的构建，exceljs 更适合需要包含图片资源导出的场景。

核心思路

导出含图片的 Excel 流程如下：

1. 从表格数据中提取列配置和行数据
2. 使用 exceljs 构建 workbook，将 base64 图片作为图像资源注册到 workbook
3. 通过坐标将图片叠加到对应单元格位置
4. 通过workbook.xlsx.writeBuffer()导出为 ArrayBuffer，包装为 Blob 后下载

关键做法：签名列的单元格填入空字符串，图片通过worksheet.addImage叠加在该单元格位置，两者互不干扰。

关键代码

buildExceljsWithImages — exceljs 构建含图片 workbook

这个方法接收原始表格数据和签名列的索引，构建一个 exceljs workbook。签名列对应的单元格填入空字符串，图片通过 exceljs 的 Image API 叠加在单元格之上。

/** * 使用 exceljs 构建含签名图片的 workbook * @param {Object[]} tableData - 原始表格数据（每行包含所有字段） * @param {string[]} tableHeader - 表头文本数组 * @param {string[]} dataIndex - 字段名数组，与 tableHeader 一一对应 * @param {number} signColIndex - 签名列在 dataIndex 中的索引 * @returns {ExcelJS.Workbook} - 含图片的 exceljs workbook */asyncbuildExceljsWithImages(tableData,tableHeader,dataIndex,signColIndex){// 1. 创建 exceljs workbook 和 worksheetconstworkbook=newExcelJS.Workbook();constworksheet=workbook.addWorksheet('人员信息');// 设置每列的默认宽度worksheet.columns=dataIndex.map(()=>({width:18}));// 2. 写入表头（加粗）constheaderRow=worksheet.addRow(tableHeader);headerRow.font={bold:true};// 3. 遍历每行数据，写入行内容并插入签名图片for(leti=0;i<tableData.length;i++){constrowData=tableData[i];// 写入行数据：签名列留空，其他列正常填充worksheet.addRow(dataIndex.map((di,idx)=>{if(idx===signColIndex)return'';// 签名列填空字符串，图片独立叠加returnrowData[di];// 非签名列直接取字段值}));// 4. 如果签名列有 base64 图片数据，插入到当前行constbase64Data=rowData[dataIndex[signColIndex]];if(base64Data){try{// exceljs 需要纯 base64，移除 data:image/png;base64, 前缀constpureBase64=base64Data.replace(/^data:image\/\w+;base64,/,'');// 将 base64 图片注册为 workbook 的图像资源constimageId=workbook.addImage({base64:pureBase64,extension:'png',});// 将图片叠加到当前行的签名列单元格位置// row: i + 1，因为第 0 行已被表头占据worksheet.addImage(imageId,{tl:{col:signColIndex,row:i+1},ext:{width:75,height:45}});}catch(e){// 单行图片插入失败不影响其他行，仅打印错误console.error('签名图片插入失败:',e);}}}returnworkbook;}

getWb — 构建含图片的 exceljs workbook

此方法判断当前表格配置中是否包含签名列，若包含则调用buildExceljsWithImages构建含图片的 workbook。

/** * 根据表格数据构建含图片的 exceljs workbook * - 检测表格列配置中是否包含签名列（reportReceiverSignData） * - 包含则构建含图片的 exceljs workbook * - 不包含则返回 null，由调用方降级处理 * * @param {Object[]} tableData - 原始表格数据 * @returns {{ exceljsWb: ExcelJS.Workbook|null }} */asyncgetWb(tableData){// 从组件配置获取列信息，过滤掉 "操作" 列（按钮列不参与导出）constcolumns=JSON.parse(JSON.stringify(this.defaultColumns))consttableHeader=columns.filter(i=>i.title!=='操作').map(i=>i.title);constdataIndex=columns.filter(i=>i.title!=='操作').map(item=>item.dataIndex);// 检查当前列配置中是否包含签名列constsignColIndex=dataIndex.indexOf('reportReceiverSignData');// 只有当表格包含签名列时，才构建含图片的 exceljs workbookletexceljsWb=null;if(signColIndex>-1){try{exceljsWb=awaitthis.buildExceljsWithImages(tableData,tableHeader,dataIndex,signColIndex);}catch(e){// 整体兜底：exceljs 构建失败时返回 null，不阻塞用户console.error('生成带图片Excel失败',e);}}return{exceljsWb}}

exportExcel — 下载入口

用户点击导出按钮后触发此方法。通过 exceljs workbook 的writeBuffer()导出为 ArrayBuffer，包装为 Blob 后触发浏览器下载。

/** * 导出含图片的 Excel 文件 * - 表格包含签名列时，使用 exceljs 导出含图片的 xlsx（Blob 方式下载） * - 不包含签名列时提示用户 */asyncexportExcel(){this.loadingFlag=true;consttableData=awaitthis.renderTableData()if(tableData.length===0){this.loadingFlag=false;returnthis.$message.warn('没有可导出的数据！');}constexcelName='人员信息.xlsx';const{exceljsWb}=awaitthis.getWb(tableData);if(exceljsWb){// 有签名列 → exceljs 导出 Blob 下载（含图片）constbuffer=awaitexceljsWb.xlsx.writeBuffer();constblob=newBlob([buffer],{type:'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'});constlink=document.createElement('a');link.href=URL.createObjectURL(blob);link.download=excelName;link.click();URL.revokeObjectURL(link.href);}else{this.$message.warn('当前表格不包含签名列');}this.loadingFlag=false;}

自定义列兼容说明：表格的列支持用户自定义显隐。当用户隐藏了签名列时，dataIndex中不包含reportReceiverSignData，signColIndex为-1，exceljsWb为null，此时提示用户当前不包含签名列。

注意事项

1. base64 前缀处理

exceljs 的workbook.addImage接收纯 base64 字符串，不能包含data:image/png;base64,前缀。数据库存储的签名数据通常带有此前缀，需要先用正则移除：

constpureBase64=base64Data.replace(/^data:image\/\w+;base64,/,'');

2. 行号偏移：row: i + 1

设置图片坐标时，tl.row从 0 开始计数。由于第 0 行已被表头占据，数据行从第 1 行开始，因此row: i + 1。

3. 行级异常隔离

每行图片插入有独立的 try-catch，单张图片加载失败、base64 格式不正确、或图片尺寸异常时，仅跳过当前行的图片插入，不影响其他行的数据和图片写入。

4. 整体降级兜底

getWb()中 exceljs 的构建有外层 try-catch，即使 exceljs 库加载失败或在构建过程中抛出异常（如 base64 解码错误），也能返回null，让调用方安全降级处理，不阻塞用户操作。

总结

通过 exceljs 实现前端导出含图片的 Excel 文件，核心步骤是：

1. 构建 exceljs workbook，写入表头和行数据（签名列留空）
2. 通过workbook.addImage注册 base64 图片资源
3. 通过worksheet.addImage将图片定位到对应单元格
4. 通过workbook.xlsx.writeBuffer()导出为 buffer 后下载

关键设计要点：整体降级兜底（exceljs 失败时优雅降级）、自定义列兼容（无签名列时自动识别）、行级异常隔离（单行图片失败不影响整体）。这些细节保证了功能的健壮性，避免图片导出成为阻塞用户操作的瓶颈。

对于需要在前端处理图片导出场景的项目，exceljs 是一个值得考虑的选择——它提供了 workbook-level 的 API，能够精确控制图片的插入位置和尺寸。