前端导出 Excel 支持签名图片功能记录背景体检报告管理页面有一个报告领取人签名列数据以 base64 图片格式存储在数据库中。最初导出 Excel 时使用了 xlsx 库签名列只能输出[签名图片]占位文本无法渲染为真实的图片。本文记录如何通过 exceljs 库实现前端导出含签名图片的 Excel 文件。导出效果技术选型exceljs是一个支持在单元格中插入图片的 Excel 操作库允许通过 workbook-level 的 API 精确控制图片的位置和尺寸。相较于 xlsxSheetJS仅支持纯文本表格的构建exceljs 更适合需要包含图片资源导出的场景。核心思路导出含图片的 Excel 流程如下从表格数据中提取列配置和行数据使用 exceljs 构建 workbook将 base64 图片作为图像资源注册到 workbook通过坐标将图片叠加到对应单元格位置通过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 和 worksheetconstworkbooknewExcelJS.Workbook();constworksheetworkbook.addWorksheet(人员信息);// 设置每列的默认宽度worksheet.columnsdataIndex.map(()({width:18}));// 2. 写入表头加粗constheaderRowworksheet.addRow(tableHeader);headerRow.font{bold:true};// 3. 遍历每行数据写入行内容并插入签名图片for(leti0;itableData.length;i){constrowDatatableData[i];// 写入行数据签名列留空其他列正常填充worksheet.addRow(dataIndex.map((di,idx){if(idxsignColIndex)return;// 签名列填空字符串图片独立叠加returnrowData[di];// 非签名列直接取字段值}));// 4. 如果签名列有 base64 图片数据插入到当前行constbase64DatarowData[dataIndex[signColIndex]];if(base64Data){try{// exceljs 需要纯 base64移除 data:image/png;base64, 前缀constpureBase64base64Data.replace(/^data:image\/\w;base64,/,);// 将 base64 图片注册为 workbook 的图像资源constimageIdworkbook.addImage({base64:pureBase64,extension:png,});// 将图片叠加到当前行的签名列单元格位置// row: i 1因为第 0 行已被表头占据worksheet.addImage(imageId,{tl:{col:signColIndex,row:i1},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){// 从组件配置获取列信息过滤掉 操作 列按钮列不参与导出constcolumnsJSON.parse(JSON.stringify(this.defaultColumns))consttableHeadercolumns.filter(ii.title!操作).map(ii.title);constdataIndexcolumns.filter(ii.title!操作).map(itemitem.dataIndex);// 检查当前列配置中是否包含签名列constsignColIndexdataIndex.indexOf(reportReceiverSignData);// 只有当表格包含签名列时才构建含图片的 exceljs workbookletexceljsWbnull;if(signColIndex-1){try{exceljsWbawaitthis.buildExceljsWithImages(tableData,tableHeader,dataIndex,signColIndex);}catch(e){// 整体兜底exceljs 构建失败时返回 null不阻塞用户console.error(生成带图片Excel失败,e);}}return{exceljsWb}}exportExcel — 下载入口用户点击导出按钮后触发此方法。通过 exceljs workbook 的writeBuffer()导出为 ArrayBuffer包装为 Blob 后触发浏览器下载。/** * 导出含图片的 Excel 文件 * - 表格包含签名列时使用 exceljs 导出含图片的 xlsxBlob 方式下载 * - 不包含签名列时提示用户 */asyncexportExcel(){this.loadingFlagtrue;consttableDataawaitthis.renderTableData()if(tableData.length0){this.loadingFlagfalse;returnthis.$message.warn(没有可导出的数据);}constexcelName人员信息.xlsx;const{exceljsWb}awaitthis.getWb(tableData);if(exceljsWb){// 有签名列 → exceljs 导出 Blob 下载含图片constbufferawaitexceljsWb.xlsx.writeBuffer();constblobnewBlob([buffer],{type:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet});constlinkdocument.createElement(a);link.hrefURL.createObjectURL(blob);link.downloadexcelName;link.click();URL.revokeObjectURL(link.href);}else{this.$message.warn(当前表格不包含签名列);}this.loadingFlagfalse;}自定义列兼容说明表格的列支持用户自定义显隐。当用户隐藏了签名列时dataIndex中不包含reportReceiverSignDatasignColIndex为-1exceljsWb为null此时提示用户当前不包含签名列。注意事项1. base64 前缀处理exceljs 的workbook.addImage接收纯 base64 字符串不能包含data:image/png;base64,前缀。数据库存储的签名数据通常带有此前缀需要先用正则移除constpureBase64base64Data.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 文件核心步骤是构建 exceljs workbook写入表头和行数据签名列留空通过workbook.addImage注册 base64 图片资源通过worksheet.addImage将图片定位到对应单元格通过workbook.xlsx.writeBuffer()导出为 buffer 后下载关键设计要点整体降级兜底exceljs 失败时优雅降级、自定义列兼容无签名列时自动识别、行级异常隔离单行图片失败不影响整体。这些细节保证了功能的健壮性避免图片导出成为阻塞用户操作的瓶颈。对于需要在前端处理图片导出场景的项目exceljs 是一个值得考虑的选择——它提供了 workbook-level 的 API能够精确控制图片的插入位置和尺寸。
