简介这是一份面向Vue.js开发者的PDF电子签章功能实现资源包解决合同审批、文档签署等场景中PDF上传、预览、盖章签名与下载的完整流程。压缩包共19个文件约216KB包含5个Vue组件、5个JavaScript脚本、3个JSON配置以及图片、图标等辅助资源目录结构清晰便于直接对照学习。目前已有1455人学习。资源提供基于PDF.js的PDF渲染组件示例、vue-pdf-signature签名插件接入方式以及文件上传/下载的axios与隐藏链接实现代码可以帮助读者快速掌握Vue中集成PDF签章的关键步骤并理解从本地文件到后端交互的完整链路适合正在开发电子合同、审批系统或需要补充前端文档处理能力的中级Vue开发者。 做办公系统、合同管理、审批流这类项目的朋友大概率都接到过这样一个需求用户上传一份PDF在指定位置盖个电子章、签个名最后把盖好的文件下载下来。这个需求听起来简单真正动手实现时才发现PDF在浏览器里就是一块“只读画布”你没法直接把一个div拖上去然后存回去。所以整个方案必须拆成渲染层、交互层、导出层三块来处理。这篇文章把我自己落地这套功能的过程完整梳理一遍从技术选型到坐标换算再到导出时那些让人抓狂的坑一次性讲清楚。1. 需求拆解与方案设计1.1 这个功能到底在解决什么问题这类功能最常出现在三个场景里办公OA里的审批盖章、合同管理系统的电子签署、以及证书/证明类PDF的在线打印。核心功能点其实就四个上传PDF、预览渲染、盖章签名、下载归档。但实际落地时会发现每个点都能展开成不少细节。比如“盖章”这件事是单页盖还是多页盖章能不能拖动要不要支持撤销“签名”到底是手写板还是文本框这些都直接决定前端工作量。我建议先把业务抽象成一句话PDF是背景画布章和签名是可自由叠加的元素所有元素用一份数据数组维护。这样无论是撤回、重定位还是导出都围绕同一份数据进行逻辑会清晰很多。另一个容易被忽略的点是这类功能往往不需要后端参与纯前端就能完成。但如果你接的是正式合同场景要求防篡改、可追溯那还得结合后端的数字证书签名那是另一套方案。本文先把纯前端这条链路走通。1.2 技术选型为什么用 pdf.js pdf-lib 的组合渲染层我选了pdf.js这是Mozilla出品的PDF解析渲染库浏览器原生不支持PDF展示用它把每一页画到canvas上是最成熟的做法。交互层里手写签名用到的是Canvas画板这个不需要额外库原生API就够了。导出层用的是pdf-lib它能直接读取原始PDF的二进制数据在指定页面的指定坐标上绘制图片然后输出新的PDF文件。这里有个关键选择为什么不用jsPDF做导出jsPDF强项是从零生成PDF如果要往已有PDF里精确塞图片它只能通过“把原PDF转成图片再贴进去”这种间接方式这样会丢掉原文件的文字层文件体积也会变大。pdf-lib是原生操作PDF结构保留原始版式和文字清晰度不损失。整体组合就是pdf.js负责“看”Canvas负责“画”pdf-lib负责“写”。2. 文件上传与 PDF 渲染2.1 上传组件与文件校验的细节上传部分如果你用的是Element Plus直接上el-upload如果你不想引组件原生input加change事件也完全够用。真正要注意的是校验acceptapplication/pdf只影响文件选择器里能看到的文件类型不代表用户拖进来的文件一定合法。我一般在change回调里再判断一遍file.type和file.name后缀两者都过才放行。大文件限制也要提前想好。PDF动辄几十上百MB我在实际项目里把上限设成100MB超过直接toast提示。读取文件用file.arrayBuffer()拿到ArrayBuffer这个数据后面要同时传给pdf.js解析也要在导出时传给pdf-lib。预览地址可以另用URL.createObjectURL(file)生成但不要只存这个地址因为pdf-lib需要的是二进制数据不是URL。这里提醒一句如果你用el-upload的auto-upload默认行为它会把文件POST到服务器但我们这套方案不需要上传后端记得关掉自动上传用on-change回调手动拿文件对象。2.2 pdf.js 加载与 Canvas 渲染PDF的渲染流程是固定的拿ArrayBuffer交给getDocument然后一页一页取viewport、创建canvas、调render。我封装了一个核心函数大概长这样import * as pdfjsLib from pdfjs-dist; pdfjsLib.GlobalWorkerOptions.workerSrc /pdfjs/pdf.worker.min.js; async function renderPage(pdf, pageNum, scale 1.5) { const page await pdf.getPage(pageNum); const viewport page.getViewport({ scale }); const canvas document.createElement(canvas); canvas.width viewport.width; canvas.height viewport.height; const ctx canvas.getContext(2d); await page.render({ canvasContext: ctx, viewport }).promise; return canvas; }渲染时我会把scale固定为1.5或2保证高清显示然后用CSS把canvas宽度限制在容器宽度内。千万不要把scale设成3甚至更高去渲染所有页用户电脑风扇会直接起飞。多页PDF建议做懒加载只渲染当前页翻页时再渲染目标页切页时保留上一页的canvas做占位能明显降低卡顿感。2.3 渲染层最容易踩的坑第一个坑是worker路径。pdf.js官方包在打包工具里经常找不到worker文件报错信息是“Setting up fake worker failed”。Vite项目里我这么处理import workerUrl from pdfjs-dist/build/pdf.worker.min.js?url; pdfjsLib.GlobalWorkerOptions.workerSrc workerUrl;Webpack则建议用copy-webpack-plugin把worker文件复制到public目录再指定绝对路径。第二个坑是跨域如果PDF是从CDN或对象存储加载的容器需要配置CORS否则pdf.js拿不到跨域ArrayBuffer。第三个坑是中文PDF字体解析绝大多数现代PDF都内嵌字体正常渲染没问题但如果遇到文字乱码先确认是不是字体子集化导致的这种情况基本只能换文件源。3. 盖章与签名交互的实现3.1 印章素材准备图片叠加是核心电子章的本质是一张透明背景的PNG图片。有两种来源一种是客户直接提供印章图片另一种是用canvas现场画一个圆章。不管哪种我都建议先做一次压缩处理——把最长边压到200到300像素左右。原因有两个一是大图拖起来卡二是pdf-lib嵌入图片时会重新编码原图太大容易撑爆内存甚至导致导出失败。如果你的章是白底的处理时会非常麻烦。白底PNG盖到PDF上会变成一个大白块直接把底下的文字盖住。解决办法是在上传时就做一次背景去除——canvas读取像素把接近白色的像素alpha置为0但这个阈值不好调我也不建议在生产环境里做这种“自杀式”处理。最靠谱的方法是让设计同事输出透明底PNG或者用在线工具先把章抠好。这不是技术偷懒是工程质量问题。3.2 拖拽定位与页面坐标记录章怎么“盖”上去本质就是在PDF上方的透明层里拖拽一个img元素松手时把位置记录下来。我用PointerEvent来做因为mouse事件不支持触摸屏pointer事件一套代码同时覆盖鼠标和触屏。关键代码片段let currentStamp null; canvasWrapper.addEventListener(pointerdown, (e) { currentStamp createStampElement(e.clientX, e.clientY); }); canvasWrapper.addEventListener(pointermove, (e) { if (!currentStamp) return; moveStampElement(currentStamp, e.clientX, e.clientY); }); canvasWrapper.addEventListener(pointerup, () { if (!currentStamp) return; saveStampPosition(currentStamp); currentStamp null; });这里最核心的设计决策是存档时不存像素坐标而是存百分比坐标。也就是把章的矩形位置除以当前PDF显示区域的宽高得到xPercent、yPercent、widthPercent、heightPercent四个值。为什么因为PDF显示区域在不同屏幕、不同缩放比例下尺寸不一样存像素坐标换一个屏幕就对不上了百分比坐标天然适配任意缩放。3.3 手写签名与文字签名手写签名我用一个独立的画板组件实现。原理不复杂监听pointerdown开始路径pointermove不断lineTo并strokepointerup结束路径。这里有个很重要的细节画板容器要加上touch-action: none否则手机上拖动会触发浏览器滚动。画好后通过canvas.toDataURL(image/png)导出同样要保证透明背景。文字签名更简单本质是把输入的姓名画到一个透明canvas上生成PNG。但要注意中文字体问题特别是在iOS上某些字体在canvas里渲染会缺失。稳妥做法是直接用系统默认字体sans-serif或者把字体文件通过font-face加载后再绘制。4. 导出带章 PDF 的完整流程4.1 为什么不用截图合成而是用 pdf-lib我在早期版本里试过html2canvas jsPDF的方案把所有canvas截成图片再拼成一个新PDF。当时确实能跑通但问题很明显生成的文件完全丢了文字层用户拿到PDF后无法搜索、无法复制文字文件体积从几百KB膨胀到几MB而且只要PDF超过两三页导出过程就慢得让人怀疑人生。截图合成只适合“展示用”的伪PDF不适合归档。pdf-lib则完全不一样它是直接在PDF结构层面操作。加载原始文件、嵌入图片、在指定页面的指定位置绘制全程不碰原始内容文字层和矢量信息完整保留导出的文件跟原文件几乎一样大。不过pdf-lib有个局限对中文文字写入支持一般但一般也不需要它写文字因为章和签名都是图片正好绕开这个坑。4.2 屏幕坐标到 PDF 坐标的换算这是整个功能里最容易出错、也最容易让人卡壳的地方。先说结论屏幕上的坐标体系原点在左上角y轴向下pdf-lib的坐标体系原点在页面左下角y轴向上。两者必须做一次翻转。假设我存的是百分比坐标印章矩形的左上角在页面显示区域的位置是(xPct, yPct)宽高百分比是(widthPct, heightPct)。拿到pdf-lib加载的页面后可以得到原始尺寸pageWidth和pageHeight。绘制时const drawWidth widthPct * pageWidth; const drawHeight heightPct * pageHeight; const drawX xPct * pageWidth; // 左上角转左下角原点y轴要翻转再减去图片自身高度 const drawY pageHeight - yPct * pageHeight - drawHeight; page.drawImage(pngImage, { x: drawX, y: drawY, width: drawWidth, height: drawHeight, });很多人的章盖出来位置偏下或者偏上基本都在drawY这一步出了问题。我见过最典型的错误是忘了减drawHeight结果图片整体往页面顶部偏移。另一个坑是混淆了canvas渲染尺寸和PDF原始尺寸canvas的像素宽高不等于PDF点的宽高但比例是恒定的所以用百分比坐标能完美规避这个误差。4.3 图片嵌入与导出下载图片嵌入前必须先embedPng这是pdf-lib的硬性要求import { PDFDocument } from pdf-lib; const pdfDoc await PDFDocument.load(arrayBuffer); const pngImage await pdfDoc.embedPng(stampImageDataUrl); const page pdfDoc.getPage(pageIndex); page.drawImage(pngImage, { x: drawX, y: drawY, width: drawWidth, height: drawHeight, }); const bytes await pdfDoc.save(); const blob new Blob([bytes], { type: application/pdf }); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download fileName; a.click(); URL.revokeObjectURL(url);这里要注意如果有盖章、签名、文字备注等多类元素按顺序分别embedPng再drawImage顺序就是PDF里的图层顺序。导出完成前要保证pdfDoc没有关闭save()之后再用。文件名的中文在现代浏览器里直接用a.download没问题但老的WebKit内核偶尔会乱码可以额外用URL.createObjectURL配合encodeURIComponent处理。5. 实战中的常见问题与排查5.1 盖章签名位置偏移的排查位置偏移最典型的一个原因就是第4节说的坐标翻转出错尤其是忘了减drawHeight。第二个原因是存坐标时用了鼠标事件的offsetX和offsetY但监听器绑在wrapper上而wrapper里可能有滚动条或padding造成计算基准不一致。我的建议是统一用getBoundingClientRect拿PDF显示区域的矩形鼠标位置减去rect的left和top再除以rect的width和height得到百分比。这样无论页面怎么滚动、容器怎么缩放都不会错。排查偏移问题时我通常在页面上画一个半透明的定位网格肉眼能直接看出来章到底是往哪边偏、偏了多少像素比反复看代码日志高效得多。5.2 文件名乱码与跨域问题下载PDF时中文文件名乱码多数情况下是因为直接把原始文件名塞进了下载链路而部分浏览器对URL里非ASCII字符处理不友好。现在Chrome和Edge对a.download的中文支持很好只要不把文件名手动放进URL里基本OK。跨域问题则集中在pdf.js加载远程PDF上如果遭遇“Unexpected server response”先开浏览器控制台看CORS报错让后端在存储服务上把Access-Control-Allow-Origin配好。还有一个隐藏问题PDF用Blob URL导出后revokeObjectURL时机太早会导致下载空白应该等download触发后再回收。5.3 大 PDF 性能优化超过50页的PDF一次性把所有页渲染到canvas里内存直接爆掉。我优化后的策略是两层第一层只渲染当前页翻页时销毁前一页的canvas第二层如果确实要预览多页用IntersectionObserver监听页面进入可视区再渲染离屏的页用占位div兜底。拖拽盖章时如果感觉卡顿检查一下是不是每次pointermove都触发了重渲染正确做法是拖拽过程中只更新DOM的transform或者left/top松手时才计算百分比坐标并触发数据更新。移动端还要留意canvas本身尺寸别超出设备像素限制太宽的canvas在安卓机上有渲染上限。5.4 常见问题速查表我把自己开发过程中踩过的典型问题整理成了表格方便大家对照排查。问题现象原因解决方案章盖出来整体向下偏移y轴未翻转或翻转时忘了减自身高度检查drawY计算确认drawY pageHeight - yPct * pageHeight - drawHeight章在不同屏幕位置不一致存档用了像素坐标统一改成百分比坐标换算基准用getBoundingClientRect导出PDF后章模糊印章原图太小或未压缩准备透明底PNG建议最长边200到300px导出时按比例放大pdf.js 报 fake workerworker路径未配置Vite用?url引入workerWebpack用copy插件复制到public下载文件名乱码编码问题使用a.download属性不要在URL中拼接中文手写签名在手机上拖动页面未禁用默认滚动画板容器加touch-action: none5.5 功能扩展方向如果你只是做内部审批用的盖章签名做到这一步已经够用。但如果业务方后续提出“公章位置要固定不可拖动”“需要多人协同盖章”“操作日志要留痕”这类需求前端方案就撑不住了得引入后端配合。盖章位置固定可以用后端坐标校验操作留痕得靠后端记录每一次盖章的账号、时间、坐标、文件哈希多人协同则要考虑并发冲突和版本管理。前端在这条链路里的职责就是把交互体验做好、坐标数据传准、渲染不出错其余交给后端。我做这套功能最大的体会是前端画章、拖章、签名都只是表面功夫真正决定方案上限的是对坐标体系和导出文件格式的理解。一个章盖得准不准一份PDF导出来文字还能不能选中、体积有没有膨胀这些细节才是一个功能从“能用”到“好用”的分水岭。如果你也在做类似需求建议先把坐标换算和导出流程的demo跑通再回头补交互样式这样整体会稳很多。本文还有配套的精品资源点击获取