简介面向需要在H5页面中嵌入PDF阅读并完成手写签名的前端开发者和业务团队这份压缩包围绕“在线预览电子签名”给出可参考的页面实现适用于合同签署、表单填写、移动端文档确认等场景。包内共15个文件以10个JavaScript脚本和2个CSS样式为主另含1个HTML入口页、1个PDF示例文档及1个系统隐藏文件压缩包约711KB体量轻便便于快速查阅与本地调试。已有420人学习说明该主题在文档处理与前端交互方向具有一定关注度。内容组织上可看到PDF渲染、手势与触屏事件、页面适配、样式布局以及签名画布相关实现线索读者能据此理解预览层与签名层如何协同并参考依赖引入、移动端点击处理与基础交互等细节为自建PDF签署页面或改造现有文档流程提供较完整的示例基础。1. PDF 签名在线预览不是“预览 签名”的拼装题PDF 签名在线预览这个需求第一次接的人容易把它拆成两个功能左边把 PDF 画出来右边让用户签个名。真到手机上跑一遍就会发现难点不在“画出来”而在“画出来的坐标”和“写回 PDF 的坐标”必须是同一套。用户手指按在第三页右下角松手后签名框偏两厘米后面下载、打印、归档全得返工。这套链路适合做 H5 合同、报价单、审批单的前端同学也适合接私活的独立开发者。下面按一条能跑通的顺序拆渲染管线、坐标换算、签名写入、现场排查、签后自校验。每一步都给可抄的代码和参数最后说清楚哪些页能签、哪些页最好别碰。2. 渲染管线canvas 分层把首屏从 3 秒压到 1 秒内PDF 预览在 H5 里常见的做法有三种iframe直接指向文件地址、embed、用渲染库把每页画到 canvas。前两种在“只看不签”的场景够用但在签名场景基本直接出局。原因不是性能而是控制权原生预览是浏览器或系统接管的一层黑匣子你拿不到页面尺寸、拿不到滚动位置也没法在页面上覆盖一个可拖拽的签名框。2.1 选型iframe 原生预览为什么在签名场景出局iframe srcxxx.pdf在桌面 Chrome 上会调起内置 PDF 阅读器iOS Safari 会调起系统预览Android WebView 则取决于厂商内核。表面看省事实际有三个硬伤第一签名层没法精准叠到某一页的某个位置因为拿不到 PDF 页面的渲染尺寸第二不同端的内置阅读器工具栏会改变可视区域高度签名框坐标完全不可控第三文件地址需要跨域时内置阅读器对Content-Disposition: inline、CORS 响应头的要求比 fetch 更苛刻经常出现“浏览器能打开、iframe 里空白”的玄学现场。我一般用pdf.js做渲染理由很实际它把页面拆成PDFDocumentProxy和PDFPageProxy两层页面尺寸、旋转角度、视口变换都能拿到渲染结果是标准 canvas签名层用绝对定位盖上去就行。代价是要自己管 worker、字体和内存这部分后面会讲。2.2 页面骨架三层结构和 devicePixelRatio每页 DOM 我固定三层底层canvas画 PDF中间sign-layer放已确认的签名图最上层hit-layer接手势和点击。三层用同一个父容器position: relative子层全部position: absolute; inset: 0这样签名框的百分比坐标只依赖父容器不会被 padding 或 border 带偏。!-- 单页容器三层必须同尺寸、同定位基准 -- div classpdf-page>import * as pdfjsLib from pdfjs-dist; // worker 必须显式指定打包器无法自动推导 pdfjsLib.GlobalWorkerOptions.workerSrc /static/pdf.worker.min.js; const DPR Math.min(window.devicePixelRatio || 1, 2); // 上限 2别让 iPhone 把面积撑爆 export async function renderPage(pdf, pageNumber, canvas, scale 1.2) { const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale }); // canvas 的像素尺寸 CSS 尺寸 × DPRCSS 尺寸单独设置 canvas.width Math.floor(viewport.width * DPR); canvas.height Math.floor(viewport.height * DPR); canvas.style.width ${viewport.width}px; canvas.style.height ${viewport.height}px; const ctx canvas.getContext(2d, { alpha: false }); ctx.setTransform(DPR, 0, 0, DPR, 0, 0); // 只在这里乘一次 DPR await page.render({ canvasContext: ctx, viewport, transform: DPR ! 1 ? [DPR, 0, 0, DPR, 0, 0] : null, }).promise; return { page, viewport }; }这段代码有两个参数最容易被改错。scale是 PDF 用户空间到 CSS 像素的缩放比viewport.width已经是缩放后的 CSS 宽度DPR只影响 canvas 的物理像素不影响布局。ctx.setTransform(DPR, 0, 0, DPR, 0, 0)和render里的transform二选一即可重复乘会让页面看起来“变大了一圈”这也是后面坐标偏移的常见源头。alpha: false能省一点合成开销但前提是页面背景必须是不透明的白色否则透明 PDF 会变黑底。2.3 按需渲染IntersectionObserver 加页缓存一份 30 页的合同如果进页面就Promise.all全量渲染手机端大概率在第 8 页左右开始掉帧。pdf.js 的渲染任务走 worker但 canvas 绘制仍在主线程同时存在十几个大 canvas 还会触发内存回收表现就是滑动时突然白屏。我一般把并发压到 2用IntersectionObserver观察每页容器进入视口前 200px 才开始渲染const queue []; let running 0; const MAX_CONCURRENT 2; const observer new IntersectionObserver((entries) { entries.forEach((entry) { if (!entry.isIntersecting) return; const el entry.target; if (el.dataset.rendered 1 || el.dataset.queued 1) return; el.dataset.queued 1; queue.push(el); pump(); }); }, { root: scrollContainer, rootMargin: 200px 0px }); function pump() { while (running MAX_CONCURRENT queue.length) { const el queue.shift(); running; renderPage(pdf, Number(el.dataset.page), el.querySelector(canvas)) .then(() { el.dataset.rendered 1; }) .catch((err) { console.error(render fail, el.dataset.page, err); }) .finally(() { running--; pump(); }); } } // 离屏超过 6 页就释放 canvas避免 iOS 白屏 function releaseFarPages(currentPage) { document.querySelectorAll(.pdf-page[data-rendered1]).forEach((el) { const p Number(el.dataset.page); if (Math.abs(p - currentPage) 6) { const canvas el.querySelector(canvas); canvas.width 0; // 关键置 0 才会真正释放显存 canvas.height 0; el.dataset.rendered 0; el.dataset.queued 0; } }); }这里的关键参数是rootMargin和释放半径。200px适合手机竖屏平板或桌面可以放到400px释放半径 6 页是经验值太小会导致来回滑动反复重绘太大则内存压不住。还有一点pdf.getPage()返回的 page 对象不用手动 destroy但PDFDocumentProxy要复用别每次翻页重新getDocument否则 worker 里会堆一串文档实例。3. 坐标换算把手指落点映射到 PDF 用户空间的 4 个变量签名错位是这类需求里返工率最高的问题而且往往不是“差很多”是差 2 到 5 个像素用户说不清、测试也不好复现。根因通常不是算法错而是三套坐标系混着用屏幕坐标、canvas 的 CSS 像素坐标、PDF 用户空间坐标。把这三种坐标的边界定死问题会少一大半。3.1 三套坐标系屏幕、canvas 像素、PDF 点屏幕坐标是clientX/clientY原点在视口左上角单位是 CSS 像素。canvas 的 CSS 像素坐标是相对页面容器的原点在容器左上角canvas 的物理像素还要再乘 DPR但签名框定位只用 CSS 像素不要碰物理像素。PDF 用户空间的单位是点pt1/72 英寸原点在页面左下角y 轴向上这是和 DOM 坐标最大的区别。我一般不在渲染时记录像素坐标而是在用户确认签名框的那一刻把框换算成相对页面容器的百分比// 从指针事件得到相对页面容器的百分比框 function pointerToBox(event, pageEl, start) { const rect pageEl.getBoundingClientRect(); // 已包含滚动和缩放 const x (event.clientX - rect.left) / rect.width; const y (event.clientY - rect.top) / rect.height; return { xPct: Math.min(start.xPct, x), yPct: Math.min(start.yPct, y), wPct: Math.abs(x - start.xPct), hPct: Math.abs(y - start.yPct), }; }getBoundingClientRect()返回的是视口坐标已经扣掉了滚动容器的影响所以不需要再减scrollTop。很多人在这里多减一次桌面端看不出来手机上滑到第二页就开始整体上移。另一个参数是rect.width它取的是容器当前的 CSS 宽度横竖屏切换后会变这也是为什么要存百分比而不是存像素。3.2 百分比签名框跨屏幕尺寸不漂移的存法签名框的数据结构我固定成四个 0 到 1 的小数外加页码和旋转后的显示宽高比{ pageIndex: 2, xPct: 0.62, yPct: 0.71, wPct: 0.22, hPct: 0.09, }不存left/top像素的理由很直接同一份合同在 iPhone 13 和 iPad 上打开页面容器宽度差一倍像素坐标必然漂移。存百分比后渲染层用当前rect.width/height乘回去签名框永远贴着页面右下角。还有一个细节百分比要相对“页面内容区”算不要相对整个滚动容器算否则页面两侧留白变化时又会偏。3.3 旋转页与 MediaBox被忽视的宽高交换PDF 页面有一个/Rotate属性常见值是 0、90、180、270。pdf.js的viewport已经应用了旋转显示宽高可能和page.getSize()返回的宽高互换。如果签名页恰好是扫描件横版、/Rotate 90你按未旋转的宽高去算签名会整体偏到页面外。写入时pdf-lib的drawImage使用的是页面未旋转的用户空间所以需要把“显示空间的百分比框”映射回去。下面这个函数覆盖四个角度返回{ x, y, width, height, rotate }其中x/y是图片锚点rotate是图片需要额外转的角度import { degrees } from pdf-lib; export function pdfBoxFromDisplay(box, page) { const { width: pw, height: ph } page.getSize(); const angle ((page.getRotation().angle % 360) 360) % 360; const swap angle 90 || angle 270; const dispW swap ? ph : pw; // 显示宽高已应用旋转 const dispH swap ? pw : ph; const u0 box.xPct * dispW; // 显示空间左上角y 向下 const v0 box.yPct * dispH; const wD box.wPct * dispW; const hD box.hPct * dispH; if (angle 0) { return { x: u0, y: ph - v0 - hD, width: wD, height: hD, rotate: 0 }; } if (angle 90) { // 显示 (u,v) (y,x)图片顺时针转 90 才能在显示时保持水平 return { x: v0, y: u0 wD, width: hD, height: wD, rotate: -90 }; } if (angle 180) { return { x: pw - u0, y: ph - v0, width: wD, height: hD, rotate: 180 }; } // angle 270 return { x: pw - v0, y: ph - u0 - wD, width: hD, height: wD, rotate: 90 }; }这段函数里最容易看晕的是 90 度和 270 度的width/height互换显示空间里宽是wD映射回未旋转的用户空间后图片的宽对应的是页面高度方向所以width传hD。rotate: -90也不是随便写的pdf-lib的旋转是绕图片锚点逆时针转90 度页需要反向转 90 度才能和页面旋转抵消。如果业务允许我的建议是签名页只开放/Rotate 0的页面旋转页走“先转正再签”的流程。这样能省掉一整类坐标问题产品上也好解释横版扫描件先旋转保存再进入签名。4. 签名落盘pdf-lib 增量写入与图片压平的 3 个参数预览层做完下一步是把签名图写进 PDF。这里选pdf-lib的原因是它在浏览器里能直接改Uint8Array不依赖服务端代价是它不会帮你处理已有数字签名域也不会自动压缩图片。签名图如果直接按 canvas 原始尺寸写入一份合同能膨胀十几 MB。4.1 手写签名采集canvas 转 PNG 与透明底处理手写签名我一般用一个独立的全屏 canvas 采集背景透明线宽 3px颜色#1a1a1a。导出时按显示尺寸导出不乘 DPR否则一张签名图能到 2000px 宽写进 PDF 纯属浪费。function exportSignature(canvas) { // 裁掉四周空白签名图越小写入后文件越干净 const ctx canvas.getContext(2d); const { width, height } canvas; const img ctx.getImageData(0, 0, width, height); let minX width, minY height, maxX 0, maxY 0; for (let y 0; y height; y) { for (let x 0; x width; x) { const alpha img.data[(y * width x) * 4 3]; if (alpha 10) { if (x minX) minX x; if (x maxX) maxX x; if (y minY) minY y; if (y maxY) maxY y; } } } if (maxX minX || maxY minY) throw new Error(签名区域为空); const pad 8; const out document.createElement(canvas); out.width maxX - minX pad * 2; out.height maxY - minY pad * 2; out.getContext(2d).drawImage( canvas, minX - pad, minY - pad, out.width, out.height, 0, 0, out.width, out.height ); return out.toDataURL(image/png); // 透明底写入后不遮正文 }alpha 10是去噪阈值太低会把抗锯齿边缘也算进边界太高会裁掉浅色笔迹。pad 8是给签名留一点呼吸空间避免写入 PDF 后贴边。返回dataURL是为了方便预览真正写入前还要转成Uint8Array因为pdf-lib的embedPng不接 dataURL 字符串。如果用户上传的是白底签名照片直接drawImage会盖住合同正文。常见做法是用一个离屏 canvas 读像素把接近白色的像素 alpha 置 0边缘保留一点过渡function whiteToTransparent(imageData, threshold 238) { const d imageData.data; for (let i 0; i d.length; i 4) { const r d[i], g d[i 1], b d[i 2]; if (r threshold g threshold b threshold) { d[i 3] 0; // 纯白转透明 } } return imageData; }这个阈值别设太低否则签名笔画的浅灰边缘会被吃掉打印出来像断墨。238是我试过比较稳的值具体还要看扫描件背景。4.2 写入签名的完整代码从 Uint8Array 到 Blob写入流程分三步加载原 PDF、逐页drawImage、保存成Uint8Array。下面这段是主链路参数后面逐条说import { PDFDocument, degrees } from pdf-lib; function dataUrlToUint8(dataUrl) { const base64 dataUrl.split(,)[1]; const bin atob(base64); const bytes new Uint8Array(bin.length); for (let i 0; i bin.length; i) bytes[i] bin.charCodeAt(i); return bytes; } export async function signPdf(srcBytes, signatures) { // srcBytes 必须是 Uint8Array不能传 Blob 或 base64 字符串 const pdfDoc await PDFDocument.load(srcBytes, { ignoreEncryption: false, // 加密 PDF 直接抛错别静默放行 updateMetadata: false, }); const pages pdfDoc.getPages(); for (const s of signatures) { const page pages[s.pageIndex]; if (!page) throw new Error(页码越界: ${s.pageIndex}); const pngBytes dataUrlToUint8(s.dataUrl); const png await pdfDoc.embedPng(pngBytes); const box pdfBoxFromDisplay(s.box, page); page.drawImage(png, { x: box.x, y: box.y, width: box.width, height: box.height, rotate: degrees(box.rotate), }); } // useObjectStreams: false 提升老阅读器兼容性代价是文件略大 const out await pdfDoc.save({ useObjectStreams: false }); return new Blob([out], { type: application/pdf }); }ignoreEncryption: false是故意的。设成true只是跳过检查保存时遇到加密对象仍然会失败或者更糟生成一份内容缺失但能打开的文件。加密 PDF 应该在入口就拦下来提示用户先去除保护。updateMetadata: false能少改一个对象对“原样签回”的场景更稳。useObjectStreams是兼容性和体积的取舍。设为true时 pdf-lib 会把多个对象压进对象流文件小 10% 到 20%但部分老版本阅读器和某些打印驱动会打不开。合同、发票这类要归档的文件我一般关掉它宁可大一点。4.3 已有签名字段与加密 PDF先判断再动手如果原 PDF 里已经有 AcroForm 签名字段直接drawImage盖上去阅读器可能仍然认为该字段未签或者在验证时把这次覆盖判定为内容篡改。动手前先扫一遍字段const form pdfDoc.getForm(); const fields form.getFields(); const hasSignatureField fields.some( (f) f.constructor.name PDFSignature ); if (hasSignatureField) { // 业务上要么走原字段签名要么先 flatten 再画图 form.flatten(); }form.flatten()会把表单字段变成普通页面内容之后再用drawImage覆盖就不会和签名字段冲突。但 flatten 会丢掉字段的可编辑性这一步要和业务确认。另一个坑是 PDF 的增量保存。pdf-lib默认是重写整个文档不是追加增量所以原文件里的数字签名如果有会失效。这不是 bug是预期行为你在签名后的文件上再画图任何合规的数字签名都会判定文档被修改。遇到这种文件正确做法是让用户下载原件、在业务系统里重新发起签署而不是硬盖一个图片签名。5. 排查清单签名预览最容易翻车的 5 个现场这类需求在开发机上跑通不算数得在 iOS Safari、Android WebView、桌面 Chrome 三端各走一遍。下面五条是我踩过的、并且每次接类似需求都会重新验证的现场按“现象 → 原因 → 解决”记。5.1 现象一iOS 预览白屏Android 正常现象很典型进入页面后容器高度正常但 canvas 全白控制台没有报错Android 上同一份文件正常显示。原因通常有两个。第一canvas 的像素面积超限。iOS Safari 对单个 canvas 的总像素有上限A4 页面在DPR 3时宽度约 1785px、高度约 2526px单页还撑得住但多页 canvas 同时存在就会触发回收表现就是白屏。第二render的transform和ctx.setTransform重复乘了 DPRcanvas 实际绘制区域跑到可视区外看起来也是白的。解决把 DPR 上限压到 2离屏页把canvas.width/height置 0 释放transform和setTransform只保留一处。如果是 PDF 内嵌了 CMap 字体导致中文不显示还要在getDocument时传cMapUrl和cMapPacked: true否则不是白屏是文字空白这两种现象要分开看。5.2 现象二签名位置整体偏移 2 到 5 个像素现象是签名框看起来贴住了但导出 PDF 后整体往左上或右下偏一点放大看才明显。原因多半在容器页面容器有border: 1px或padding: 4pxgetBoundingClientRect()把边框算进去了而 canvas 的实际内容区从边框内侧开始另一个常见原因是缩放用了 CSStransform: scale()视觉放大了但rect.width没变百分比乘出来还是旧尺寸。解决签名层和 canvas 必须放在同一个无 border、无 padding 的定位父容器里边框加在外层缩放时重新计算viewport并重绘不要用 CSS transform 缩放 canvas。还有一个小点clientX是视口坐标rect.left也已经包含滚动别再减scrollLeft。5.3 现象三几十页 PDF 滑到第 10 页就卡死现象是前几页顺滑滑到中间开始掉帧最后整页无响应Android 低端机尤其明显。原因一般是全量渲染进页面就Promise.all渲染所有页pdf.js 的 worker 队列被塞满主线程同时维护十几个大 canvas内存回收跟不上。另一个隐性问题是没有复用PDFDocumentProxy每次翻页重新getDocumentworker 里堆了多份文档实例。解决并发压到 2用IntersectionObserver按需渲染离屏超过 6 页释放 canvas。释放时一定要把width/height置 0只移除 DOM 节点不会立刻释放显存。PDFDocumentProxy在页面初始化时加载一次翻页只调getPage。5.4 现象四签名后的文件在部分阅读器打不开现象是 Chrome 能打开某款老阅读器或手机自带阅读器提示“文件损坏”或者打开后空白。原因通常有三个save({ useObjectStreams: true })生成了对象流老阅读器不认PDFDocument.load传了 base64 字符串或Blobpdf-lib 在浏览器里对输入类型很挑类型不对时可能在保存阶段才炸下载时Blob的 MIME 写成了application/octet-stream某些系统会按未知文件处理。解决归档类文件统一useObjectStreams: falseload只传Uint8Array下载用new Blob([bytes], { type: application/pdf })文件名用encodeURIComponent处理中文。还有一点如果原 PDF 是线性化文件重写后线性化结构会丢失这不是损坏但首屏加载会变慢。5.5 现象五横竖屏切换后签名框错位现象是竖屏签好的框转到横屏后跑到页面中间或者宽度被拉长。原因是你存了像素坐标或者存了百分比但没有在resize后重算容器尺寸。横竖屏切换时页面容器宽度变化viewport也变了旧的像素框不会自动适配。解决框只存 0 到 1 的百分比渲染时用当前rect.width/height乘回去监听orientationchange后不要立刻重绘等resize稳定 200ms 再算避免拿到中间态尺寸。如果签名页有旋转角度横竖屏切换后还要重新跑一遍pdfBoxFromDisplay因为显示宽高互换了。6. 签后自校验三张图加一个字节阈值把返工挡在提交前签名文件生成后我习惯在提交前跑一遍自校验不依赖人工点开看。校验分三层文件层看字节页面层看渲染坐标层看回读。6.1 三层校验与通过阈值校验项方法通过阈值文件头与体积读前 5 个字节是否为%PDF-对比原文件体积文件头正确体积增幅不超过原文件 30%页面数与页尺寸PDFDocument.load后读getPageCount()和每页getSize()页面数与原文件一致宽高误差小于 1pt签名落点用 pdf.js 把签后 PDF 的目标页渲染到 canvas读取签名框区域像素区域非空白像素占比大于 0.5%第一层用 Node 脚本就能跑不需要浏览器import fs from node:fs; import { PDFDocument } from pdf-lib; const src fs.readFileSync(./input.pdf); const out fs.readFileSync(./output.pdf); // 1) 文件头 const head out.subarray(0, 5).toString(); if (head ! %PDF-) throw new Error(文件头异常); // 2) 页面数与页尺寸 const a await PDFDocument.load(src); const b await PDFDocument.load(out); if (a.getPageCount() ! b.getPageCount()) throw new Error(页数不一致); b.getPages().forEach((p, i) { const [w, h] [p.getWidth(), p.getHeight()]; const [aw, ah] [a.getPage(i).getWidth(), a.getPage(i).getHeight()]; if (Math.abs(w - aw) 1 || Math.abs(h - ah) 1) { throw new Error(第 ${i 1} 页尺寸变化过大); } }); // 3) 体积阈值签名图不应该把文件撑大一倍 const ratio out.length / src.length; if (ratio 1.3) console.warn(体积增幅偏高检查签名图分辨率, ratio.toFixed(2));体积阈值我一般卡在 1.3超过就回头查签名图是不是按 DPR 导出了。曾经有一版把canvas.width直接当导出宽度一张手写签名 2400px 宽30 页合同每页盖一个文件从 2MB 涨到 18MB用户下载直接超时。后来改成按显示尺寸导出、裁掉空白边同样的签名图从 180KB 降到 9KB。第三层像素校验适合放进端到端脚本用无头浏览器打开签后 PDF 的预览页等目标页render完成截取签名框区域的getImageData统计 alpha 大于 10 的像素比例。低于 0.5% 基本可以判定签名没画上去常见原因是embedPng拿到了空Uint8Array或者drawImage的x/y算到了页面外。还有一个我每次都做的动作把签前和签后的目标页各截一张图叠在一起看差分。差分图里如果签名区域是干净的、正文区域没有大面积变化说明只加了签名、没动原内容如果正文也花了八成是whiteToTransparent的阈值把正文浅色底纹吃掉了。从那以后我每次接这类需求都会先把这三层校验脚本跑通再联调 UI宁可多花半小时写脚本也不想在提测前一天晚上对着偏移 3 像素的签名框抓瞎。希望帮到你。本文还有配套的精品资源点击获取
简介面向需要在H5页面中嵌入PDF阅读并完成手写签名的前端开发者和业务团队这份压缩包围绕“在线预览电子签名”给出可参考的页面实现适用于合同签署、表单填写、移动端文档确认等场景。包内共15个文件以10个JavaScript脚本和2个CSS样式为主另含1个HTML入口页、1个PDF示例文档及1个系统隐藏文件压缩包约711KB体量轻便便于快速查阅与本地调试。已有420人学习说明该主题在文档处理与前端交互方向具有一定关注度。内容组织上可看到PDF渲染、手势与触屏事件、页面适配、样式布局以及签名画布相关实现线索读者能据此理解预览层与签名层如何协同并参考依赖引入、移动端点击处理与基础交互等细节为自建PDF签署页面或改造现有文档流程提供较完整的示例基础。1. PDF 签名在线预览不是“预览 签名”的拼装题PDF 签名在线预览这个需求第一次接的人容易把它拆成两个功能左边把 PDF 画出来右边让用户签个名。真到手机上跑一遍就会发现难点不在“画出来”而在“画出来的坐标”和“写回 PDF 的坐标”必须是同一套。用户手指按在第三页右下角松手后签名框偏两厘米后面下载、打印、归档全得返工。这套链路适合做 H5 合同、报价单、审批单的前端同学也适合接私活的独立开发者。下面按一条能跑通的顺序拆渲染管线、坐标换算、签名写入、现场排查、签后自校验。每一步都给可抄的代码和参数最后说清楚哪些页能签、哪些页最好别碰。2. 渲染管线canvas 分层把首屏从 3 秒压到 1 秒内PDF 预览在 H5 里常见的做法有三种iframe直接指向文件地址、embed、用渲染库把每页画到 canvas。前两种在“只看不签”的场景够用但在签名场景基本直接出局。原因不是性能而是控制权原生预览是浏览器或系统接管的一层黑匣子你拿不到页面尺寸、拿不到滚动位置也没法在页面上覆盖一个可拖拽的签名框。2.1 选型iframe 原生预览为什么在签名场景出局iframe srcxxx.pdf在桌面 Chrome 上会调起内置 PDF 阅读器iOS Safari 会调起系统预览Android WebView 则取决于厂商内核。表面看省事实际有三个硬伤第一签名层没法精准叠到某一页的某个位置因为拿不到 PDF 页面的渲染尺寸第二不同端的内置阅读器工具栏会改变可视区域高度签名框坐标完全不可控第三文件地址需要跨域时内置阅读器对Content-Disposition: inline、CORS 响应头的要求比 fetch 更苛刻经常出现“浏览器能打开、iframe 里空白”的玄学现场。我一般用pdf.js做渲染理由很实际它把页面拆成PDFDocumentProxy和PDFPageProxy两层页面尺寸、旋转角度、视口变换都能拿到渲染结果是标准 canvas签名层用绝对定位盖上去就行。代价是要自己管 worker、字体和内存这部分后面会讲。2.2 页面骨架三层结构和 devicePixelRatio每页 DOM 我固定三层底层canvas画 PDF中间sign-layer放已确认的签名图最上层hit-layer接手势和点击。三层用同一个父容器position: relative子层全部position: absolute; inset: 0这样签名框的百分比坐标只依赖父容器不会被 padding 或 border 带偏。!-- 单页容器三层必须同尺寸、同定位基准 -- div classpdf-page>import * as pdfjsLib from pdfjs-dist; // worker 必须显式指定打包器无法自动推导 pdfjsLib.GlobalWorkerOptions.workerSrc /static/pdf.worker.min.js; const DPR Math.min(window.devicePixelRatio || 1, 2); // 上限 2别让 iPhone 把面积撑爆 export async function renderPage(pdf, pageNumber, canvas, scale 1.2) { const page await pdf.getPage(pageNumber); const viewport page.getViewport({ scale }); // canvas 的像素尺寸 CSS 尺寸 × DPRCSS 尺寸单独设置 canvas.width Math.floor(viewport.width * DPR); canvas.height Math.floor(viewport.height * DPR); canvas.style.width ${viewport.width}px; canvas.style.height ${viewport.height}px; const ctx canvas.getContext(2d, { alpha: false }); ctx.setTransform(DPR, 0, 0, DPR, 0, 0); // 只在这里乘一次 DPR await page.render({ canvasContext: ctx, viewport, transform: DPR ! 1 ? [DPR, 0, 0, DPR, 0, 0] : null, }).promise; return { page, viewport }; }这段代码有两个参数最容易被改错。scale是 PDF 用户空间到 CSS 像素的缩放比viewport.width已经是缩放后的 CSS 宽度DPR只影响 canvas 的物理像素不影响布局。ctx.setTransform(DPR, 0, 0, DPR, 0, 0)和render里的transform二选一即可重复乘会让页面看起来“变大了一圈”这也是后面坐标偏移的常见源头。alpha: false能省一点合成开销但前提是页面背景必须是不透明的白色否则透明 PDF 会变黑底。2.3 按需渲染IntersectionObserver 加页缓存一份 30 页的合同如果进页面就Promise.all全量渲染手机端大概率在第 8 页左右开始掉帧。pdf.js 的渲染任务走 worker但 canvas 绘制仍在主线程同时存在十几个大 canvas 还会触发内存回收表现就是滑动时突然白屏。我一般把并发压到 2用IntersectionObserver观察每页容器进入视口前 200px 才开始渲染const queue []; let running 0; const MAX_CONCURRENT 2; const observer new IntersectionObserver((entries) { entries.forEach((entry) { if (!entry.isIntersecting) return; const el entry.target; if (el.dataset.rendered 1 || el.dataset.queued 1) return; el.dataset.queued 1; queue.push(el); pump(); }); }, { root: scrollContainer, rootMargin: 200px 0px }); function pump() { while (running MAX_CONCURRENT queue.length) { const el queue.shift(); running; renderPage(pdf, Number(el.dataset.page), el.querySelector(canvas)) .then(() { el.dataset.rendered 1; }) .catch((err) { console.error(render fail, el.dataset.page, err); }) .finally(() { running--; pump(); }); } } // 离屏超过 6 页就释放 canvas避免 iOS 白屏 function releaseFarPages(currentPage) { document.querySelectorAll(.pdf-page[data-rendered1]).forEach((el) { const p Number(el.dataset.page); if (Math.abs(p - currentPage) 6) { const canvas el.querySelector(canvas); canvas.width 0; // 关键置 0 才会真正释放显存 canvas.height 0; el.dataset.rendered 0; el.dataset.queued 0; } }); }这里的关键参数是rootMargin和释放半径。200px适合手机竖屏平板或桌面可以放到400px释放半径 6 页是经验值太小会导致来回滑动反复重绘太大则内存压不住。还有一点pdf.getPage()返回的 page 对象不用手动 destroy但PDFDocumentProxy要复用别每次翻页重新getDocument否则 worker 里会堆一串文档实例。3. 坐标换算把手指落点映射到 PDF 用户空间的 4 个变量签名错位是这类需求里返工率最高的问题而且往往不是“差很多”是差 2 到 5 个像素用户说不清、测试也不好复现。根因通常不是算法错而是三套坐标系混着用屏幕坐标、canvas 的 CSS 像素坐标、PDF 用户空间坐标。把这三种坐标的边界定死问题会少一大半。3.1 三套坐标系屏幕、canvas 像素、PDF 点屏幕坐标是clientX/clientY原点在视口左上角单位是 CSS 像素。canvas 的 CSS 像素坐标是相对页面容器的原点在容器左上角canvas 的物理像素还要再乘 DPR但签名框定位只用 CSS 像素不要碰物理像素。PDF 用户空间的单位是点pt1/72 英寸原点在页面左下角y 轴向上这是和 DOM 坐标最大的区别。我一般不在渲染时记录像素坐标而是在用户确认签名框的那一刻把框换算成相对页面容器的百分比// 从指针事件得到相对页面容器的百分比框 function pointerToBox(event, pageEl, start) { const rect pageEl.getBoundingClientRect(); // 已包含滚动和缩放 const x (event.clientX - rect.left) / rect.width; const y (event.clientY - rect.top) / rect.height; return { xPct: Math.min(start.xPct, x), yPct: Math.min(start.yPct, y), wPct: Math.abs(x - start.xPct), hPct: Math.abs(y - start.yPct), }; }getBoundingClientRect()返回的是视口坐标已经扣掉了滚动容器的影响所以不需要再减scrollTop。很多人在这里多减一次桌面端看不出来手机上滑到第二页就开始整体上移。另一个参数是rect.width它取的是容器当前的 CSS 宽度横竖屏切换后会变这也是为什么要存百分比而不是存像素。3.2 百分比签名框跨屏幕尺寸不漂移的存法签名框的数据结构我固定成四个 0 到 1 的小数外加页码和旋转后的显示宽高比{ pageIndex: 2, xPct: 0.62, yPct: 0.71, wPct: 0.22, hPct: 0.09, }不存left/top像素的理由很直接同一份合同在 iPhone 13 和 iPad 上打开页面容器宽度差一倍像素坐标必然漂移。存百分比后渲染层用当前rect.width/height乘回去签名框永远贴着页面右下角。还有一个细节百分比要相对“页面内容区”算不要相对整个滚动容器算否则页面两侧留白变化时又会偏。3.3 旋转页与 MediaBox被忽视的宽高交换PDF 页面有一个/Rotate属性常见值是 0、90、180、270。pdf.js的viewport已经应用了旋转显示宽高可能和page.getSize()返回的宽高互换。如果签名页恰好是扫描件横版、/Rotate 90你按未旋转的宽高去算签名会整体偏到页面外。写入时pdf-lib的drawImage使用的是页面未旋转的用户空间所以需要把“显示空间的百分比框”映射回去。下面这个函数覆盖四个角度返回{ x, y, width, height, rotate }其中x/y是图片锚点rotate是图片需要额外转的角度import { degrees } from pdf-lib; export function pdfBoxFromDisplay(box, page) { const { width: pw, height: ph } page.getSize(); const angle ((page.getRotation().angle % 360) 360) % 360; const swap angle 90 || angle 270; const dispW swap ? ph : pw; // 显示宽高已应用旋转 const dispH swap ? pw : ph; const u0 box.xPct * dispW; // 显示空间左上角y 向下 const v0 box.yPct * dispH; const wD box.wPct * dispW; const hD box.hPct * dispH; if (angle 0) { return { x: u0, y: ph - v0 - hD, width: wD, height: hD, rotate: 0 }; } if (angle 90) { // 显示 (u,v) (y,x)图片顺时针转 90 才能在显示时保持水平 return { x: v0, y: u0 wD, width: hD, height: wD, rotate: -90 }; } if (angle 180) { return { x: pw - u0, y: ph - v0, width: wD, height: hD, rotate: 180 }; } // angle 270 return { x: pw - v0, y: ph - u0 - wD, width: hD, height: wD, rotate: 90 }; }这段函数里最容易看晕的是 90 度和 270 度的width/height互换显示空间里宽是wD映射回未旋转的用户空间后图片的宽对应的是页面高度方向所以width传hD。rotate: -90也不是随便写的pdf-lib的旋转是绕图片锚点逆时针转90 度页需要反向转 90 度才能和页面旋转抵消。如果业务允许我的建议是签名页只开放/Rotate 0的页面旋转页走“先转正再签”的流程。这样能省掉一整类坐标问题产品上也好解释横版扫描件先旋转保存再进入签名。4. 签名落盘pdf-lib 增量写入与图片压平的 3 个参数预览层做完下一步是把签名图写进 PDF。这里选pdf-lib的原因是它在浏览器里能直接改Uint8Array不依赖服务端代价是它不会帮你处理已有数字签名域也不会自动压缩图片。签名图如果直接按 canvas 原始尺寸写入一份合同能膨胀十几 MB。4.1 手写签名采集canvas 转 PNG 与透明底处理手写签名我一般用一个独立的全屏 canvas 采集背景透明线宽 3px颜色#1a1a1a。导出时按显示尺寸导出不乘 DPR否则一张签名图能到 2000px 宽写进 PDF 纯属浪费。function exportSignature(canvas) { // 裁掉四周空白签名图越小写入后文件越干净 const ctx canvas.getContext(2d); const { width, height } canvas; const img ctx.getImageData(0, 0, width, height); let minX width, minY height, maxX 0, maxY 0; for (let y 0; y height; y) { for (let x 0; x width; x) { const alpha img.data[(y * width x) * 4 3]; if (alpha 10) { if (x minX) minX x; if (x maxX) maxX x; if (y minY) minY y; if (y maxY) maxY y; } } } if (maxX minX || maxY minY) throw new Error(签名区域为空); const pad 8; const out document.createElement(canvas); out.width maxX - minX pad * 2; out.height maxY - minY pad * 2; out.getContext(2d).drawImage( canvas, minX - pad, minY - pad, out.width, out.height, 0, 0, out.width, out.height ); return out.toDataURL(image/png); // 透明底写入后不遮正文 }alpha 10是去噪阈值太低会把抗锯齿边缘也算进边界太高会裁掉浅色笔迹。pad 8是给签名留一点呼吸空间避免写入 PDF 后贴边。返回dataURL是为了方便预览真正写入前还要转成Uint8Array因为pdf-lib的embedPng不接 dataURL 字符串。如果用户上传的是白底签名照片直接drawImage会盖住合同正文。常见做法是用一个离屏 canvas 读像素把接近白色的像素 alpha 置 0边缘保留一点过渡function whiteToTransparent(imageData, threshold 238) { const d imageData.data; for (let i 0; i d.length; i 4) { const r d[i], g d[i 1], b d[i 2]; if (r threshold g threshold b threshold) { d[i 3] 0; // 纯白转透明 } } return imageData; }这个阈值别设太低否则签名笔画的浅灰边缘会被吃掉打印出来像断墨。238是我试过比较稳的值具体还要看扫描件背景。4.2 写入签名的完整代码从 Uint8Array 到 Blob写入流程分三步加载原 PDF、逐页drawImage、保存成Uint8Array。下面这段是主链路参数后面逐条说import { PDFDocument, degrees } from pdf-lib; function dataUrlToUint8(dataUrl) { const base64 dataUrl.split(,)[1]; const bin atob(base64); const bytes new Uint8Array(bin.length); for (let i 0; i bin.length; i) bytes[i] bin.charCodeAt(i); return bytes; } export async function signPdf(srcBytes, signatures) { // srcBytes 必须是 Uint8Array不能传 Blob 或 base64 字符串 const pdfDoc await PDFDocument.load(srcBytes, { ignoreEncryption: false, // 加密 PDF 直接抛错别静默放行 updateMetadata: false, }); const pages pdfDoc.getPages(); for (const s of signatures) { const page pages[s.pageIndex]; if (!page) throw new Error(页码越界: ${s.pageIndex}); const pngBytes dataUrlToUint8(s.dataUrl); const png await pdfDoc.embedPng(pngBytes); const box pdfBoxFromDisplay(s.box, page); page.drawImage(png, { x: box.x, y: box.y, width: box.width, height: box.height, rotate: degrees(box.rotate), }); } // useObjectStreams: false 提升老阅读器兼容性代价是文件略大 const out await pdfDoc.save({ useObjectStreams: false }); return new Blob([out], { type: application/pdf }); }ignoreEncryption: false是故意的。设成true只是跳过检查保存时遇到加密对象仍然会失败或者更糟生成一份内容缺失但能打开的文件。加密 PDF 应该在入口就拦下来提示用户先去除保护。updateMetadata: false能少改一个对象对“原样签回”的场景更稳。useObjectStreams是兼容性和体积的取舍。设为true时 pdf-lib 会把多个对象压进对象流文件小 10% 到 20%但部分老版本阅读器和某些打印驱动会打不开。合同、发票这类要归档的文件我一般关掉它宁可大一点。4.3 已有签名字段与加密 PDF先判断再动手如果原 PDF 里已经有 AcroForm 签名字段直接drawImage盖上去阅读器可能仍然认为该字段未签或者在验证时把这次覆盖判定为内容篡改。动手前先扫一遍字段const form pdfDoc.getForm(); const fields form.getFields(); const hasSignatureField fields.some( (f) f.constructor.name PDFSignature ); if (hasSignatureField) { // 业务上要么走原字段签名要么先 flatten 再画图 form.flatten(); }form.flatten()会把表单字段变成普通页面内容之后再用drawImage覆盖就不会和签名字段冲突。但 flatten 会丢掉字段的可编辑性这一步要和业务确认。另一个坑是 PDF 的增量保存。pdf-lib默认是重写整个文档不是追加增量所以原文件里的数字签名如果有会失效。这不是 bug是预期行为你在签名后的文件上再画图任何合规的数字签名都会判定文档被修改。遇到这种文件正确做法是让用户下载原件、在业务系统里重新发起签署而不是硬盖一个图片签名。5. 排查清单签名预览最容易翻车的 5 个现场这类需求在开发机上跑通不算数得在 iOS Safari、Android WebView、桌面 Chrome 三端各走一遍。下面五条是我踩过的、并且每次接类似需求都会重新验证的现场按“现象 → 原因 → 解决”记。5.1 现象一iOS 预览白屏Android 正常现象很典型进入页面后容器高度正常但 canvas 全白控制台没有报错Android 上同一份文件正常显示。原因通常有两个。第一canvas 的像素面积超限。iOS Safari 对单个 canvas 的总像素有上限A4 页面在DPR 3时宽度约 1785px、高度约 2526px单页还撑得住但多页 canvas 同时存在就会触发回收表现就是白屏。第二render的transform和ctx.setTransform重复乘了 DPRcanvas 实际绘制区域跑到可视区外看起来也是白的。解决把 DPR 上限压到 2离屏页把canvas.width/height置 0 释放transform和setTransform只保留一处。如果是 PDF 内嵌了 CMap 字体导致中文不显示还要在getDocument时传cMapUrl和cMapPacked: true否则不是白屏是文字空白这两种现象要分开看。5.2 现象二签名位置整体偏移 2 到 5 个像素现象是签名框看起来贴住了但导出 PDF 后整体往左上或右下偏一点放大看才明显。原因多半在容器页面容器有border: 1px或padding: 4pxgetBoundingClientRect()把边框算进去了而 canvas 的实际内容区从边框内侧开始另一个常见原因是缩放用了 CSStransform: scale()视觉放大了但rect.width没变百分比乘出来还是旧尺寸。解决签名层和 canvas 必须放在同一个无 border、无 padding 的定位父容器里边框加在外层缩放时重新计算viewport并重绘不要用 CSS transform 缩放 canvas。还有一个小点clientX是视口坐标rect.left也已经包含滚动别再减scrollLeft。5.3 现象三几十页 PDF 滑到第 10 页就卡死现象是前几页顺滑滑到中间开始掉帧最后整页无响应Android 低端机尤其明显。原因一般是全量渲染进页面就Promise.all渲染所有页pdf.js 的 worker 队列被塞满主线程同时维护十几个大 canvas内存回收跟不上。另一个隐性问题是没有复用PDFDocumentProxy每次翻页重新getDocumentworker 里堆了多份文档实例。解决并发压到 2用IntersectionObserver按需渲染离屏超过 6 页释放 canvas。释放时一定要把width/height置 0只移除 DOM 节点不会立刻释放显存。PDFDocumentProxy在页面初始化时加载一次翻页只调getPage。5.4 现象四签名后的文件在部分阅读器打不开现象是 Chrome 能打开某款老阅读器或手机自带阅读器提示“文件损坏”或者打开后空白。原因通常有三个save({ useObjectStreams: true })生成了对象流老阅读器不认PDFDocument.load传了 base64 字符串或Blobpdf-lib 在浏览器里对输入类型很挑类型不对时可能在保存阶段才炸下载时Blob的 MIME 写成了application/octet-stream某些系统会按未知文件处理。解决归档类文件统一useObjectStreams: falseload只传Uint8Array下载用new Blob([bytes], { type: application/pdf })文件名用encodeURIComponent处理中文。还有一点如果原 PDF 是线性化文件重写后线性化结构会丢失这不是损坏但首屏加载会变慢。5.5 现象五横竖屏切换后签名框错位现象是竖屏签好的框转到横屏后跑到页面中间或者宽度被拉长。原因是你存了像素坐标或者存了百分比但没有在resize后重算容器尺寸。横竖屏切换时页面容器宽度变化viewport也变了旧的像素框不会自动适配。解决框只存 0 到 1 的百分比渲染时用当前rect.width/height乘回去监听orientationchange后不要立刻重绘等resize稳定 200ms 再算避免拿到中间态尺寸。如果签名页有旋转角度横竖屏切换后还要重新跑一遍pdfBoxFromDisplay因为显示宽高互换了。6. 签后自校验三张图加一个字节阈值把返工挡在提交前签名文件生成后我习惯在提交前跑一遍自校验不依赖人工点开看。校验分三层文件层看字节页面层看渲染坐标层看回读。6.1 三层校验与通过阈值校验项方法通过阈值文件头与体积读前 5 个字节是否为%PDF-对比原文件体积文件头正确体积增幅不超过原文件 30%页面数与页尺寸PDFDocument.load后读getPageCount()和每页getSize()页面数与原文件一致宽高误差小于 1pt签名落点用 pdf.js 把签后 PDF 的目标页渲染到 canvas读取签名框区域像素区域非空白像素占比大于 0.5%第一层用 Node 脚本就能跑不需要浏览器import fs from node:fs; import { PDFDocument } from pdf-lib; const src fs.readFileSync(./input.pdf); const out fs.readFileSync(./output.pdf); // 1) 文件头 const head out.subarray(0, 5).toString(); if (head ! %PDF-) throw new Error(文件头异常); // 2) 页面数与页尺寸 const a await PDFDocument.load(src); const b await PDFDocument.load(out); if (a.getPageCount() ! b.getPageCount()) throw new Error(页数不一致); b.getPages().forEach((p, i) { const [w, h] [p.getWidth(), p.getHeight()]; const [aw, ah] [a.getPage(i).getWidth(), a.getPage(i).getHeight()]; if (Math.abs(w - aw) 1 || Math.abs(h - ah) 1) { throw new Error(第 ${i 1} 页尺寸变化过大); } }); // 3) 体积阈值签名图不应该把文件撑大一倍 const ratio out.length / src.length; if (ratio 1.3) console.warn(体积增幅偏高检查签名图分辨率, ratio.toFixed(2));体积阈值我一般卡在 1.3超过就回头查签名图是不是按 DPR 导出了。曾经有一版把canvas.width直接当导出宽度一张手写签名 2400px 宽30 页合同每页盖一个文件从 2MB 涨到 18MB用户下载直接超时。后来改成按显示尺寸导出、裁掉空白边同样的签名图从 180KB 降到 9KB。第三层像素校验适合放进端到端脚本用无头浏览器打开签后 PDF 的预览页等目标页render完成截取签名框区域的getImageData统计 alpha 大于 10 的像素比例。低于 0.5% 基本可以判定签名没画上去常见原因是embedPng拿到了空Uint8Array或者drawImage的x/y算到了页面外。还有一个我每次都做的动作把签前和签后的目标页各截一张图叠在一起看差分。差分图里如果签名区域是干净的、正文区域没有大面积变化说明只加了签名、没动原内容如果正文也花了八成是whiteToTransparent的阈值把正文浅色底纹吃掉了。从那以后我每次接这类需求都会先把这三层校验脚本跑通再联调 UI宁可多花半小时写脚本也不想在提测前一天晚上对着偏移 3 像素的签名框抓瞎。希望帮到你。本文还有配套的精品资源点击获取
