简介面向移动端H5开发者的canvas画板批注PDF预览实现整合PDF.js解析与Canvas触控绘制适合为平板、手机等设备添加PDF标注、手写批注功能的前端工程师学习。压缩包共150个文件约2.4MB包含34个js脚本与10个css样式用于页面逻辑和界面布局75个gif演示直观展示操作效果11个png图标及字体、音频等辅助资源完善演示环境html示例可快速运行查看。已有1750人学习下载。资源从PDF.js的引入与fetch获取PDF说起覆盖PDFDocumentProxy对象加载、页面渲染到Canvas、根据viewport设置画布尺寸等关键步骤在批注环节重点讲解touchstart、touchmove、touchend事件实现连续画笔兼容mousedown等桌面事件并给出通过toDataURL导出Canvas为图片、实现批注持久化保存与回显的方法。整体目录按功能区分方便按模块查阅适合想独立搭建移动端PDF批注画板的中高级前端开发者参考。1. 移动端PDF批注场景与选题价值画板为什么要“叠”在PDF上方移动端里让用户打开一份PDF、用手指直接在页面上画圈做批注结果画出来的笔迹和PDF文字始终对不齐——这是很多H5开发团队踩过的坑。这个项目包装的主题是“canvas移动端画板批注PDF预览”本质是解决一个很具体的问题在移动端H5里既要正常预览PDF又要让用户能在任意一页上划线、圈重点、写备注而且笔迹要贴着PDF内容走缩放不跑偏。这里有个反直觉的设计批注不是“写进”PDF文件而是在PDF上面盖一层透明的canvas画板。PDF只负责渲染底图canvas层负责收集手指轨迹两层通过同一套坐标换算对齐。这样做的直接收益是想撤销就撤销、想清空就清空PDF原文件永远不被污染二次渲染也不会把笔迹烧死。这个项目适合三类人做移动端在线签批工具的开发者、需要给文档预览功能加批注能力的H5团队以及想搞清楚canvas与PDF坐标联动的初中级前端。2. 技术选型与整体架构pdf.js负责显示canvas浮层负责“动手”2.1 三层结构PDF渲染层、画板层、坐标换算层整个项目在逻辑上拆成三个互不耦合的层。最底下是PDF渲染层负责把PDF文件解析成可缩放的页面像素中间是画板层用户所有手指操作都落在这一层最上面这一层其实不是UI层而是坐标换算层它不渲染任何东西但所有层之间的对齐、缩放、位移都靠它算。这种拆法最大的好处是每一层可以独立替换。PDF层想从pdf.js换成服务端渲染的图片流画板层完全不受影响画板层想从canvas换成SVG重构PDF层也不用动。实际开发中我习惯把坐标换算层做成一个纯函数模块输入是PDF原始坐标和当前视口信息输出是canvas上的像素坐标单测覆盖率最容易提上去的就是这一层。// viewer.js 核心初始化 const pdfCanvas document.getElementById(pdf-canvas); const boardCanvas document.getElementById(board-canvas); const pdfCtx pdfCanvas.getContext(2d); const boardCtx boardCanvas.getContext(2d); const coords { scale: 1, // 当前缩放值 offsetX: 0, // 内容区在视口内的水平偏移 offsetY: 0, // 内容区在视口内的垂直偏移 dpr: window.devicePixelRatio || 1 }; async function renderPDFAtScale(page, scale) { const viewport page.getViewport({ scale }); pdfCanvas.width viewport.width * coords.dpr; pdfCanvas.height viewport.height * coords.dpr; boardCanvas.width viewport.width * coords.dpr; boardCanvas.height viewport.height * coords.dpr; pdfCanvas.style.width boardCanvas.style.width viewport.width px; pdfCanvas.style.height boardCanvas.style.height viewport.height px; coords.scale scale; await page.render({ canvasContext: pdfCtx, viewport }).promise; }这段代码里最关键的点在canvas的宽高赋值方式内部尺寸width/height乘以dpr外部样式尺寸style.width/style.height保持CSS像素不变。如果不这么做移动端高分辨率屏上canvas会显得发虚后文避坑章节还会展开说。viewport宽高来自pdf.js的计算结果任何一页的缩放渲染都以它为准后面所有坐标换算都以此为基准。2.2 为什么不用现成的批注库市场上确实有把PDF渲染和批注打包好的库但在这个项目场景下选择自研主要卡在两个点上。第一移动端网络环境复杂很多现成库会把整本PDF的批注状态维护在一个模型里交互重、依赖大H5首屏加载压力明显。第二批注数据最终需要回传业务系统每个团队的数据结构要求不一样用通用库反而要花大量精力在数据映射上不如直接拿一个干净的数据协议。自研方案的依赖只有pdf.js一个重型库画板部分原生canvas实现不引入额外框架。pdf.js专注解决“PDF怎么渲染到像素”画板专注解决“手指轨迹怎么变成笔迹”业务系统要什么格式的批注数据我们自己定义序列化。这个取舍在移动端弱网场景下尤其划算首包体积能省掉不少。2.3 移动端视口初始化移动端H5进入这个页面时第一步不是渲染PDF而是先把viewport设定钉死避免用户双击缩放导致坐标系统崩掉。常见的做法是设置maximum-scale1, user-scalableno因为一旦浏览器介入页面级缩放canvas坐标和手指触点之间就会插入一层不可控的换算。// viewport.js const viewportMeta document.querySelector(meta[nameviewport]); viewportMeta.content [ widthdevice-width, initial-scale1, maximum-scale1, minimum-scale1, user-scalableno ].join(, );注意这里禁用的是页面级缩放不是禁用PDF的双指缩放。PDF内部的缩放由代码控制和浏览器视口缩放是两条路径千万别混为一谈。触控事件采用Pointer Events而不是传统的touch事件。理由是Pointer Events天然统一了鼠标、单指、多指三类输入后续如果要兼容桌面端调试同一套代码不用改。监听对象也直接挂在画板canvas上不去监听整个document避免滚动时事件穿透到无关区域。3. 目录结构与初始化流程从依赖安装到PDF首屏出图3.1 目录结构render、board、bridge分家项目源码的目录组织遵循一条原则凡是直接碰canvas的代码和纯逻辑代码分开。拆成三层之后修改UI时不会误伤坐标换算排查问题时也能快速定位到具体文件。src/ api/ // 后端接口封装比如获取PDF文件、回传批注 bridge/ // 坐标换算纯函数模块 components/ // Perview、DrawCanvas两个核心组件 hooks/ // 自定义HooksusePDF、useDrawBoard、useAnnotation utils/ // dpr处理、canvas裁剪等工具函数 store/ // 批注数据临时存储与撤销栈管理components/Perview负责拿到PDF文件的ArrayBuffer交给pdf.jsDrawCanvas负责挂载canvas画板。hooks层是关键usePDF暴露当前页码、渲染进度、翻页函数useDrawBoard暴露笔迹数据、画笔状态、撤销操作两者通过useAnnotation做联动比如翻页时通知画板清空临时状态。3.2 依赖清单精简到只有一个重型库核心依赖只有两类一类是渲染PDF必需的pdf.js另一类是构建工具链自带的模块。画板部分全部手写没有引入图形处理库。这里给一个最小依赖参考{ dependencies: { pdfjs-dist: ^4.x }, devDependencies: { vite: ^5.x, vitejs/plugin-vue: ^5.x } }之所以演示用Vite是因为pdf.js提供的worker文件在现代构建工具里需要显式配置资源引用Vite的new URL写法能直接拿到worker的最终路径这在移动端部署时少踩一个坑。如果你用Webpack需要额外在config里配worker-loader或copy-webpack-plugin把pdf.worker.min.mjs拷到静态目录。3.3 初始化链路四步走完首屏渲染完整的启动时序是先请求PDF文件流转发给pdf.js的getDocument解析出文档对象拿到当前页后按视口宽度计算初始缩放值最后同时初始化PDF画布和批注画布。这里有一步很容易做错批注画布必须在PDF页面首次渲染完成后才能初始化否则用户肉眼会看到画板先白屏一闪、PDF后出现的错位。// App.jsx 初始化流程 async function initDocument(fileUrl) { loading.value true; const pdfData await fetchPdfArrayBuffer(fileUrl); const doc await pdfjsLib.getDocument(pdfData).promise; currentPage.value 1; await renderPage(doc, 1); boardRef.value.init({ width: viewportWidth, height: viewportHeight }); loading.value false; }fetchPdfArrayBuffer这一步我一般会在请求头里带Cache-Control: no-transform防止某些网关把二进制流转成文本流导致PDF解析失败。这是真踩过的坑后面避坑章节会细说。画板init的时候只传入CSS像素尺寸内部自己乘以dpr外部不需要关心物理像素这也是把dpr封装进utils模块的原因。4. 核心模块拆解一次批注从落笔到落盘的完整链路4.1 PDF渲染层页码缓存与按需渲染移动端内存宝贵整本PDF一次性渲染会直接把低端机打爆。常见做法是只维护当前页和前后一页的缓存翻页时销毁远处的canvas。pdf.js渲染一页A4大小的PDF在手机上大约要占用十几MB内存连续翻十页不释放基本就撑不住了。// renderManager.js const pageCache new Map(); async function getOrRenderPage(doc, pageNum, scale) { if (pageCache.has(pageNum)) return pageCache.get(pageNum); const page await doc.getPage(pageNum); const viewport page.getViewport({ scale }); const canvas document.createElement(canvas); canvas.width viewport.width * coords.dpr; canvas.height viewport.height * coords.dpr; const ctx canvas.getContext(2d); await page.render({ canvasContext: ctx, viewport }).promise; pageCache.set(pageNum, { canvas, viewport, page }); trimCache(pageNum); return pageCache.get(pageNum); } function trimCache(currentPage) { for (const key of pageCache.keys()) { if (Math.abs(key - currentPage) 1) pageCache.delete(key); } }这里pageCache用Map而不是普通对象是因为Map天然支持键值遍历和LRU风格的删除策略。trimCache只保留当前页相邻的两页边界翻页看起来流畅内存又被锁死在一个范围内。渲染完成后的canvas可以直接作为底图绘制到显示画布上不必重新走一遍pdf.js渲染管线。4.2 画板核心Pointer事件采集与笔迹数据结构手指按下的瞬间需要拿到触点坐标并转换成canvas内部像素坐标。因为画板canvas自身尺寸是CSS像素乘以dpr所有画笔绘制都发生在物理像素空间里落笔坐标也要跟着换算。// drawBoard.js let isDrawing false; let currentStroke []; function getTouchPos(e) { const rect boardCanvas.getBoundingClientRect(); const x (e.clientX - rect.left) * coords.dpr; const y (e.clientY - rect.top) * coords.dpr; return { x, y }; } boardCanvas.addEventListener(pointerdown, (e) { isDrawing true; currentStroke [{ ...getTouchPos(e), pressure: e.pressure || 0.5, width: brushWidth * coords.dpr }]; boardCtx.beginPath(); boardCtx.moveTo(currentStroke[0].x, currentStroke[0].y); }); boardCanvas.addEventListener(pointermove, (e) { if (!isDrawing) return; const pos getTouchPos(e); currentStroke.push({ ...pos, pressure: e.pressure || 0.5 }); boardCtx.lineTo(pos.x, pos.y); boardCtx.stroke(); }); boardCanvas.addEventListener(pointerup, () { isDrawing false; strokesStack.push(currentStroke); });stroke的数据结构刻意设计成数组里装点对象每个点都带pressure值。这样导出的时候既可以把整条stroke重绘成矢量线也可以按pressure值还原笔锋粗细。state管理上strokesStack保存所有已完成的笔迹currentStroke只在绘制过程中存在绘制结束立即入栈形成可撤销的闭环。4.3 坐标换算PDF坐标、CSS像素与canvas像素的三角关系这是整个项目里最绕、也最值得花时间理解的部分。PDF文件内部有自己的坐标系原点在左下角单位是ptpdf.js渲染时通过viewport把它转换成了CSS像素画面canvas画板又要按dpr换算成物理像素。所以一次笔触落点其实经历了两次换算。// bridge/pdfCoordinate.js export function pdfToBoard(pdfPoint, viewport, dpr) { return { x: (pdfPoint.x - viewport.viewBox[0]) * (viewport.width / viewport.viewBox[2]) * dpr, y: (pdfPoint.y - viewport.viewBox[1]) * (viewport.height / viewport.viewBox[3]) * dpr }; } export function boardToPdf(boardPoint, viewport, dpr) { return { x: boardPoint.x / dpr * (viewport.viewBox[2] / viewport.width) viewport.viewBox[0], y: boardPoint.y / dpr * (viewport.viewBox[3] / viewport.height) viewport.viewBox[1] }; }这两个函数互为逆运算。导出批注时用boardToPdf把笔迹点换算回PDF坐标系这样批注数据存到哪里都能在相同页面上原样复现。缩放的时候不需要对已有笔迹做几何变换因为笔迹数据里存的是PDF坐标系下的数值每次重绘都重新经过一次pdfToBoard自然跟随缩放。4.4 撤销与橡皮擦两种“后悔药”的实现差别撤销的实现不复杂真正的挑战在怎么避免重绘闪烁。简单粗暴的做法是撤销后把整版笔迹全部重画如果一页上有几十条stroke手机端会有肉眼可见的卡顿。我这里做一个分层处理所有笔迹先画到一个离屏的“笔迹底图”canvas上显示绘制时把笔迹底图一次性贴到画板canvas撤销时从stroke栈里弹掉一条然后重建笔迹底图。// annotationStore.js const strokeStack []; let inkLayer document.createElement(canvas); const inkCtx inkLayer.getContext(2d); function commitStroke(stroke) { strokeStack.push(stroke); redrawInkLayer(); } function undoStroke() { if (strokeStack.length 0) return; strokeStack.pop(); redrawInkLayer(); } function redrawInkLayer() { inkCtx.clearRect(0, 0, inkLayer.width, inkLayer.height); for (const stroke of strokeStack) { inkCtx.beginPath(); stroke.points.forEach((p, i) { i 0 ? inkCtx.moveTo(p.x, p.y) : inkCtx.lineTo(p.x, p.y); }); inkCtx.lineWidth stroke.points[0]?.width || brushWidth * coords.dpr; inkCtx.strokeStyle stroke.color; inkCtx.stroke(); } boardCtx.drawImage(inkLayer, 0, 0); }橡皮擦则分两种流派像素擦除和笔迹擦除。像素擦除实现简单把画板canvas的globalCompositeOperation设为destination-out擦到哪里哪里透明但缺点是一旦导出PNG再导入透明像素丢失擦除就失效了笔迹擦除操作的是strokeStack把和擦除路径相交的笔迹整条剔除然后走redrawInkLayer重绘。这个项目里默认用笔迹擦除因为要保证批注数据在服务端和客户端之间可重放、可还原。4.5 批注导出JSON协议与PNG快照的双通道批注数据最终要落地这里设计了一条双通道的导出策略。一旦用户完成一页批注前端同时生成两种产物一份结构化JSON笔迹数据一份PNG快照。JSON用来做数据回放、二次编辑、跨端同步PNG用来快速预览和在无权加载pdf.js的环境里展示效果。// export/annotation.js function exportAnnotation(pageNo) { const pdfPoints strokesStack.map(stroke ({ color: stroke.color, width: stroke.width / coords.dpr, points: stroke.points.map(p boardToPdf(p, viewport, coords.dpr)) })); const snapshotCanvas document.createElement(canvas); snapshotCanvas.width pdfCanvas.width; snapshotCanvas.height pdfCanvas.height; const ctx snapshotCanvas.getContext(2d); ctx.drawImage(pdfCanvas, 0, 0); ctx.drawImage(inkLayer, 0, 0); return { page: pageNo, version: 1.0, strokes: pdfPoints, snapshotBase64: snapshotCanvas.toDataURL(image/png) }; }snapshotBase64这里有一个隐藏功劳先drawImage pdfCanvas再drawImage inkLayer意味着快照是把PDF底图和批注压在同一张图里后端收到这个字段几乎不需要再做任何处理就能直接存库展示。JSON协议的version字段也建议留下未来批注数据类型扩展时旧版本才能做兼容。5. 避坑记录画布模糊、滚动穿透与笔迹失踪的真实翻车现场5.1 画布模糊canvas像素不等于CSS像素第一个直击灵魂的坑就是canvas模糊。移动端照片级屏幕比比皆是如果canvas.width写的是CSS像素尺寸画出来的线条永远像隔着一层毛玻璃。原因是CSS像素和物理像素之间隔着devicePixelRatio这个倍率canvas默认只能在物理像素里给你一倍的清晰度。解决办法上面已经演示过canvas.width赋值CSS尺寸乘以dprstyle.width保持CSS尺寸。每次重绘都要同步这个换算只要有一处遗漏——比如某些工具函数直接返回CSS像素坐标用于绘制线条就会在部分操作中变糊。建议把dpr换算封装成唯一的canvasResize工具函数杜绝散落各处的手写乘法。5.2 滚动穿透touch-action与pointer事件配合失误某次真机测试用户在画板上画到一半被批注的PDF页面跟着手指上下滚动笔迹画歪了。根因是浏览器认为这次手势是一次滚动操作画板canvas没有明确告诉浏览器“这块区域的触摸事件归我管你别抢”。修复方式是给画板canvas设置CSS属性touch-action: none。与之配合的另一条纪律是不要在canvas上监听touch事件后手动调用preventDefault因为被动事件监听器会吃掉这个调用而且容易导致报错。直接使用Pointer Events加touch-action浏览器层面的手势识别被切断事件分发是干净的。5.3 翻页后笔迹消失PDF重绘把画板层顶掉了翻页时如果直接重绘PDF canvas没有先保存批注画板的状态就会看到满屏笔迹瞬间消失。这背后的逻辑其实不复杂两份canvas是平级元素批注canvas盖在PDF canvas上面但PDF canvas重绘时浏览器可能触发合成层更新把批注canvas暂时盖住或者导致画板上下文被重置。解决方式是把笔迹底图inkLayer全局持有不用的时候保留在存储层显示时通过drawImage贴回去。翻页动作完成后等PDF渲染结束立刻重放当前页的笔迹而不是等用户重新落笔才补画。项目里把这一动作收敛进了useAnnotation的syncInkLayer函数翻页回调里必须调用它。5.4 大PDF卡顿与内存泄漏worker与缓存失控一份几十MB的PDF连续快速翻页后页面变得越来越卡甚至白屏。查下来有两个元凶pdf.js的worker线程没有随页面销毁而释放以及pageCache在边界判断里写漏了一个等于号导致缓存一直不清理。worker泄漏会持续占用内存cache不断增长则直接撑爆canvas资源。解决方式一是页面卸载时显式调用pdfDoc.destroy()和worker.terminate()二是trimCache的保留策略调成左右各1页后停止扩展。还需注意getDocument返回的Promise在页面销毁后resolve会有报错风险初始化时要往AbortController里注册取消信号销毁时主动中断。5.5 橡皮擦擦出“黑边”destination-out的重绘时机问题橡皮擦用destination-out擦除时如果擦除过程中触发了其他操作——比如手指短暂停下触发pointercancel——半透明的像素残留在画板上导出后出现一条条淡黑色的擦痕。原因在于destination-out是破坏性的像素操作它没有“撤销本次擦除”的天然能力一旦像素被擦掉只能靠整个画板重绘恢复。所以真正的橡皮擦实现不建议直接操作显示canvas而是把擦除变成一个“笔迹编辑操作”记录擦除路径后统一对strokeStack做裁剪再重建笔迹底图。这样既不产生残留也能保证任意时刻撤销、回放都不损坏像素内容。如果产品上非要做“像素级橡皮擦”那导出时就必须连底图一起导出并且回放逻辑要同步重建。6. 二次开发方向从单页批注到多页协同6.1 从单页画板升级到多页画板现在代码里一页一个canvas多页化之后要改造成“一页一个画板实例”的Map结构。每条笔迹必须加上page字段翻页时只把对应页的strokes渲染到当前可见的canvas上。业务侧建议加一层pageIndex到stroke数组的索引避免全量遍历。// annotationStore.js 多页改造 const strokesByPage new Map(); function pushStroke(pageNo, stroke) { const list strokesByPage.get(pageNo) || []; list.push(stroke); strokesByPage.set(pageNo, list); redrawPage(pageNo); }多页改造过程中最容易遗漏的是PDF虚拟滚动复用时移出屏幕的页面canvas会被销毁但对应的strokes数据不能跟着销毁否则用户滚回来笔迹就没了。思路是把stroke数据独立于canvas生命周期canvas只负责“把数据画出来”。6.2 笔迹数据协议设计给后端一个可回放的格式批注最终要进业务系统协议里至少包含page、type、color、width、points五个字段。type区分画笔、荧光笔还是矩形框point里的pressure字段建议保留服务端就算不用也不碍事。字段越精简跨端同步越稳不要给协议加不必要的元信息。// 笔迹协议示例 { page: 3, type: pen, color: rgba(255, 0, 0, 0.8), width: 2.5, points: [ { x: 120.5, y: 340.2, pressure: 0.8 }, { x: 121.0, y: 341.0, pressure: 0.6 } ] }回放时前端拿到这份协议逐条调用drawStroke逻辑即可。这一整套流程里最容易让后端同事崩溃的是坐标基准不统一。务必在协议文档里写清楚x和y是PDF原始坐标系的数值不是canvas像素值两边才不会有偏差。6.3 性能优化三板斧离屏缓存、合成层、降采样移动端画板性能的瓶颈通常不在绘制本身而在于频繁的整页重绘和canvas尺寸变换。第一板斧是离屏缓存PDF页面渲染结束后缓存为离屏canvas翻页时不再触发pdf.js重渲染直接drawImage到显示画布。第二板斧是给批注canvas设置独立的合成层用CSSwill-change: transform让浏览器把画板层提升到独立GPU层避免每次重绘都重新参与合成。第三板斧是降采样笔迹点过于密集时按距离阈值抽稀比如相距小于1物理像素的点直接丢弃。我现在接批注类需求都会先画一张坐标换算图把PDF原始坐标系、CSS像素坐标系和canvas物理像素坐标系三者边界标清楚再动手写代码。每写完一个模块就强制走一遍“落笔→缩放→翻页→导出→回放”的完整闭环确认数据不变形才继续下一个功能。这个习惯帮助我在这个项目里少返工了至少三轮希望也能帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/17 3:56:28 · 阅读 1.2k 移动端PDF批注画板实战：canvas叠加层与坐标对齐策略
简介面向移动端H5开发者的canvas画板批注PDF预览实现整合PDF.js解析与Canvas触控绘制适合为平板、手机等设备添加PDF标注、手写批注功能的前端工程师学习。压缩包共150个文件约2.4MB包含34个js脚本与10个css样式用于页面逻辑和界面布局75个gif演示直观展示操作效果11个png图标及字体、音频等辅助资源完善演示环境html示例可快速运行查看。已有1750人学习下载。资源从PDF.js的引入与fetch获取PDF说起覆盖PDFDocumentProxy对象加载、页面渲染到Canvas、根据viewport设置画布尺寸等关键步骤在批注环节重点讲解touchstart、touchmove、touchend事件实现连续画笔兼容mousedown等桌面事件并给出通过toDataURL导出Canvas为图片、实现批注持久化保存与回显的方法。整体目录按功能区分方便按模块查阅适合想独立搭建移动端PDF批注画板的中高级前端开发者参考。1. 移动端PDF批注场景与选题价值画板为什么要“叠”在PDF上方移动端里让用户打开一份PDF、用手指直接在页面上画圈做批注结果画出来的笔迹和PDF文字始终对不齐——这是很多H5开发团队踩过的坑。这个项目包装的主题是“canvas移动端画板批注PDF预览”本质是解决一个很具体的问题在移动端H5里既要正常预览PDF又要让用户能在任意一页上划线、圈重点、写备注而且笔迹要贴着PDF内容走缩放不跑偏。这里有个反直觉的设计批注不是“写进”PDF文件而是在PDF上面盖一层透明的canvas画板。PDF只负责渲染底图canvas层负责收集手指轨迹两层通过同一套坐标换算对齐。这样做的直接收益是想撤销就撤销、想清空就清空PDF原文件永远不被污染二次渲染也不会把笔迹烧死。这个项目适合三类人做移动端在线签批工具的开发者、需要给文档预览功能加批注能力的H5团队以及想搞清楚canvas与PDF坐标联动的初中级前端。2. 技术选型与整体架构pdf.js负责显示canvas浮层负责“动手”2.1 三层结构PDF渲染层、画板层、坐标换算层整个项目在逻辑上拆成三个互不耦合的层。最底下是PDF渲染层负责把PDF文件解析成可缩放的页面像素中间是画板层用户所有手指操作都落在这一层最上面这一层其实不是UI层而是坐标换算层它不渲染任何东西但所有层之间的对齐、缩放、位移都靠它算。这种拆法最大的好处是每一层可以独立替换。PDF层想从pdf.js换成服务端渲染的图片流画板层完全不受影响画板层想从canvas换成SVG重构PDF层也不用动。实际开发中我习惯把坐标换算层做成一个纯函数模块输入是PDF原始坐标和当前视口信息输出是canvas上的像素坐标单测覆盖率最容易提上去的就是这一层。// viewer.js 核心初始化 const pdfCanvas document.getElementById(pdf-canvas); const boardCanvas document.getElementById(board-canvas); const pdfCtx pdfCanvas.getContext(2d); const boardCtx boardCanvas.getContext(2d); const coords { scale: 1, // 当前缩放值 offsetX: 0, // 内容区在视口内的水平偏移 offsetY: 0, // 内容区在视口内的垂直偏移 dpr: window.devicePixelRatio || 1 }; async function renderPDFAtScale(page, scale) { const viewport page.getViewport({ scale }); pdfCanvas.width viewport.width * coords.dpr; pdfCanvas.height viewport.height * coords.dpr; boardCanvas.width viewport.width * coords.dpr; boardCanvas.height viewport.height * coords.dpr; pdfCanvas.style.width boardCanvas.style.width viewport.width px; pdfCanvas.style.height boardCanvas.style.height viewport.height px; coords.scale scale; await page.render({ canvasContext: pdfCtx, viewport }).promise; }这段代码里最关键的点在canvas的宽高赋值方式内部尺寸width/height乘以dpr外部样式尺寸style.width/style.height保持CSS像素不变。如果不这么做移动端高分辨率屏上canvas会显得发虚后文避坑章节还会展开说。viewport宽高来自pdf.js的计算结果任何一页的缩放渲染都以它为准后面所有坐标换算都以此为基准。2.2 为什么不用现成的批注库市场上确实有把PDF渲染和批注打包好的库但在这个项目场景下选择自研主要卡在两个点上。第一移动端网络环境复杂很多现成库会把整本PDF的批注状态维护在一个模型里交互重、依赖大H5首屏加载压力明显。第二批注数据最终需要回传业务系统每个团队的数据结构要求不一样用通用库反而要花大量精力在数据映射上不如直接拿一个干净的数据协议。自研方案的依赖只有pdf.js一个重型库画板部分原生canvas实现不引入额外框架。pdf.js专注解决“PDF怎么渲染到像素”画板专注解决“手指轨迹怎么变成笔迹”业务系统要什么格式的批注数据我们自己定义序列化。这个取舍在移动端弱网场景下尤其划算首包体积能省掉不少。2.3 移动端视口初始化移动端H5进入这个页面时第一步不是渲染PDF而是先把viewport设定钉死避免用户双击缩放导致坐标系统崩掉。常见的做法是设置maximum-scale1, user-scalableno因为一旦浏览器介入页面级缩放canvas坐标和手指触点之间就会插入一层不可控的换算。// viewport.js const viewportMeta document.querySelector(meta[nameviewport]); viewportMeta.content [ widthdevice-width, initial-scale1, maximum-scale1, minimum-scale1, user-scalableno ].join(, );注意这里禁用的是页面级缩放不是禁用PDF的双指缩放。PDF内部的缩放由代码控制和浏览器视口缩放是两条路径千万别混为一谈。触控事件采用Pointer Events而不是传统的touch事件。理由是Pointer Events天然统一了鼠标、单指、多指三类输入后续如果要兼容桌面端调试同一套代码不用改。监听对象也直接挂在画板canvas上不去监听整个document避免滚动时事件穿透到无关区域。3. 目录结构与初始化流程从依赖安装到PDF首屏出图3.1 目录结构render、board、bridge分家项目源码的目录组织遵循一条原则凡是直接碰canvas的代码和纯逻辑代码分开。拆成三层之后修改UI时不会误伤坐标换算排查问题时也能快速定位到具体文件。src/ api/ // 后端接口封装比如获取PDF文件、回传批注 bridge/ // 坐标换算纯函数模块 components/ // Perview、DrawCanvas两个核心组件 hooks/ // 自定义HooksusePDF、useDrawBoard、useAnnotation utils/ // dpr处理、canvas裁剪等工具函数 store/ // 批注数据临时存储与撤销栈管理components/Perview负责拿到PDF文件的ArrayBuffer交给pdf.jsDrawCanvas负责挂载canvas画板。hooks层是关键usePDF暴露当前页码、渲染进度、翻页函数useDrawBoard暴露笔迹数据、画笔状态、撤销操作两者通过useAnnotation做联动比如翻页时通知画板清空临时状态。3.2 依赖清单精简到只有一个重型库核心依赖只有两类一类是渲染PDF必需的pdf.js另一类是构建工具链自带的模块。画板部分全部手写没有引入图形处理库。这里给一个最小依赖参考{ dependencies: { pdfjs-dist: ^4.x }, devDependencies: { vite: ^5.x, vitejs/plugin-vue: ^5.x } }之所以演示用Vite是因为pdf.js提供的worker文件在现代构建工具里需要显式配置资源引用Vite的new URL写法能直接拿到worker的最终路径这在移动端部署时少踩一个坑。如果你用Webpack需要额外在config里配worker-loader或copy-webpack-plugin把pdf.worker.min.mjs拷到静态目录。3.3 初始化链路四步走完首屏渲染完整的启动时序是先请求PDF文件流转发给pdf.js的getDocument解析出文档对象拿到当前页后按视口宽度计算初始缩放值最后同时初始化PDF画布和批注画布。这里有一步很容易做错批注画布必须在PDF页面首次渲染完成后才能初始化否则用户肉眼会看到画板先白屏一闪、PDF后出现的错位。// App.jsx 初始化流程 async function initDocument(fileUrl) { loading.value true; const pdfData await fetchPdfArrayBuffer(fileUrl); const doc await pdfjsLib.getDocument(pdfData).promise; currentPage.value 1; await renderPage(doc, 1); boardRef.value.init({ width: viewportWidth, height: viewportHeight }); loading.value false; }fetchPdfArrayBuffer这一步我一般会在请求头里带Cache-Control: no-transform防止某些网关把二进制流转成文本流导致PDF解析失败。这是真踩过的坑后面避坑章节会细说。画板init的时候只传入CSS像素尺寸内部自己乘以dpr外部不需要关心物理像素这也是把dpr封装进utils模块的原因。4. 核心模块拆解一次批注从落笔到落盘的完整链路4.1 PDF渲染层页码缓存与按需渲染移动端内存宝贵整本PDF一次性渲染会直接把低端机打爆。常见做法是只维护当前页和前后一页的缓存翻页时销毁远处的canvas。pdf.js渲染一页A4大小的PDF在手机上大约要占用十几MB内存连续翻十页不释放基本就撑不住了。// renderManager.js const pageCache new Map(); async function getOrRenderPage(doc, pageNum, scale) { if (pageCache.has(pageNum)) return pageCache.get(pageNum); const page await doc.getPage(pageNum); const viewport page.getViewport({ scale }); const canvas document.createElement(canvas); canvas.width viewport.width * coords.dpr; canvas.height viewport.height * coords.dpr; const ctx canvas.getContext(2d); await page.render({ canvasContext: ctx, viewport }).promise; pageCache.set(pageNum, { canvas, viewport, page }); trimCache(pageNum); return pageCache.get(pageNum); } function trimCache(currentPage) { for (const key of pageCache.keys()) { if (Math.abs(key - currentPage) 1) pageCache.delete(key); } }这里pageCache用Map而不是普通对象是因为Map天然支持键值遍历和LRU风格的删除策略。trimCache只保留当前页相邻的两页边界翻页看起来流畅内存又被锁死在一个范围内。渲染完成后的canvas可以直接作为底图绘制到显示画布上不必重新走一遍pdf.js渲染管线。4.2 画板核心Pointer事件采集与笔迹数据结构手指按下的瞬间需要拿到触点坐标并转换成canvas内部像素坐标。因为画板canvas自身尺寸是CSS像素乘以dpr所有画笔绘制都发生在物理像素空间里落笔坐标也要跟着换算。// drawBoard.js let isDrawing false; let currentStroke []; function getTouchPos(e) { const rect boardCanvas.getBoundingClientRect(); const x (e.clientX - rect.left) * coords.dpr; const y (e.clientY - rect.top) * coords.dpr; return { x, y }; } boardCanvas.addEventListener(pointerdown, (e) { isDrawing true; currentStroke [{ ...getTouchPos(e), pressure: e.pressure || 0.5, width: brushWidth * coords.dpr }]; boardCtx.beginPath(); boardCtx.moveTo(currentStroke[0].x, currentStroke[0].y); }); boardCanvas.addEventListener(pointermove, (e) { if (!isDrawing) return; const pos getTouchPos(e); currentStroke.push({ ...pos, pressure: e.pressure || 0.5 }); boardCtx.lineTo(pos.x, pos.y); boardCtx.stroke(); }); boardCanvas.addEventListener(pointerup, () { isDrawing false; strokesStack.push(currentStroke); });stroke的数据结构刻意设计成数组里装点对象每个点都带pressure值。这样导出的时候既可以把整条stroke重绘成矢量线也可以按pressure值还原笔锋粗细。state管理上strokesStack保存所有已完成的笔迹currentStroke只在绘制过程中存在绘制结束立即入栈形成可撤销的闭环。4.3 坐标换算PDF坐标、CSS像素与canvas像素的三角关系这是整个项目里最绕、也最值得花时间理解的部分。PDF文件内部有自己的坐标系原点在左下角单位是ptpdf.js渲染时通过viewport把它转换成了CSS像素画面canvas画板又要按dpr换算成物理像素。所以一次笔触落点其实经历了两次换算。// bridge/pdfCoordinate.js export function pdfToBoard(pdfPoint, viewport, dpr) { return { x: (pdfPoint.x - viewport.viewBox[0]) * (viewport.width / viewport.viewBox[2]) * dpr, y: (pdfPoint.y - viewport.viewBox[1]) * (viewport.height / viewport.viewBox[3]) * dpr }; } export function boardToPdf(boardPoint, viewport, dpr) { return { x: boardPoint.x / dpr * (viewport.viewBox[2] / viewport.width) viewport.viewBox[0], y: boardPoint.y / dpr * (viewport.viewBox[3] / viewport.height) viewport.viewBox[1] }; }这两个函数互为逆运算。导出批注时用boardToPdf把笔迹点换算回PDF坐标系这样批注数据存到哪里都能在相同页面上原样复现。缩放的时候不需要对已有笔迹做几何变换因为笔迹数据里存的是PDF坐标系下的数值每次重绘都重新经过一次pdfToBoard自然跟随缩放。4.4 撤销与橡皮擦两种“后悔药”的实现差别撤销的实现不复杂真正的挑战在怎么避免重绘闪烁。简单粗暴的做法是撤销后把整版笔迹全部重画如果一页上有几十条stroke手机端会有肉眼可见的卡顿。我这里做一个分层处理所有笔迹先画到一个离屏的“笔迹底图”canvas上显示绘制时把笔迹底图一次性贴到画板canvas撤销时从stroke栈里弹掉一条然后重建笔迹底图。// annotationStore.js const strokeStack []; let inkLayer document.createElement(canvas); const inkCtx inkLayer.getContext(2d); function commitStroke(stroke) { strokeStack.push(stroke); redrawInkLayer(); } function undoStroke() { if (strokeStack.length 0) return; strokeStack.pop(); redrawInkLayer(); } function redrawInkLayer() { inkCtx.clearRect(0, 0, inkLayer.width, inkLayer.height); for (const stroke of strokeStack) { inkCtx.beginPath(); stroke.points.forEach((p, i) { i 0 ? inkCtx.moveTo(p.x, p.y) : inkCtx.lineTo(p.x, p.y); }); inkCtx.lineWidth stroke.points[0]?.width || brushWidth * coords.dpr; inkCtx.strokeStyle stroke.color; inkCtx.stroke(); } boardCtx.drawImage(inkLayer, 0, 0); }橡皮擦则分两种流派像素擦除和笔迹擦除。像素擦除实现简单把画板canvas的globalCompositeOperation设为destination-out擦到哪里哪里透明但缺点是一旦导出PNG再导入透明像素丢失擦除就失效了笔迹擦除操作的是strokeStack把和擦除路径相交的笔迹整条剔除然后走redrawInkLayer重绘。这个项目里默认用笔迹擦除因为要保证批注数据在服务端和客户端之间可重放、可还原。4.5 批注导出JSON协议与PNG快照的双通道批注数据最终要落地这里设计了一条双通道的导出策略。一旦用户完成一页批注前端同时生成两种产物一份结构化JSON笔迹数据一份PNG快照。JSON用来做数据回放、二次编辑、跨端同步PNG用来快速预览和在无权加载pdf.js的环境里展示效果。// export/annotation.js function exportAnnotation(pageNo) { const pdfPoints strokesStack.map(stroke ({ color: stroke.color, width: stroke.width / coords.dpr, points: stroke.points.map(p boardToPdf(p, viewport, coords.dpr)) })); const snapshotCanvas document.createElement(canvas); snapshotCanvas.width pdfCanvas.width; snapshotCanvas.height pdfCanvas.height; const ctx snapshotCanvas.getContext(2d); ctx.drawImage(pdfCanvas, 0, 0); ctx.drawImage(inkLayer, 0, 0); return { page: pageNo, version: 1.0, strokes: pdfPoints, snapshotBase64: snapshotCanvas.toDataURL(image/png) }; }snapshotBase64这里有一个隐藏功劳先drawImage pdfCanvas再drawImage inkLayer意味着快照是把PDF底图和批注压在同一张图里后端收到这个字段几乎不需要再做任何处理就能直接存库展示。JSON协议的version字段也建议留下未来批注数据类型扩展时旧版本才能做兼容。5. 避坑记录画布模糊、滚动穿透与笔迹失踪的真实翻车现场5.1 画布模糊canvas像素不等于CSS像素第一个直击灵魂的坑就是canvas模糊。移动端照片级屏幕比比皆是如果canvas.width写的是CSS像素尺寸画出来的线条永远像隔着一层毛玻璃。原因是CSS像素和物理像素之间隔着devicePixelRatio这个倍率canvas默认只能在物理像素里给你一倍的清晰度。解决办法上面已经演示过canvas.width赋值CSS尺寸乘以dprstyle.width保持CSS尺寸。每次重绘都要同步这个换算只要有一处遗漏——比如某些工具函数直接返回CSS像素坐标用于绘制线条就会在部分操作中变糊。建议把dpr换算封装成唯一的canvasResize工具函数杜绝散落各处的手写乘法。5.2 滚动穿透touch-action与pointer事件配合失误某次真机测试用户在画板上画到一半被批注的PDF页面跟着手指上下滚动笔迹画歪了。根因是浏览器认为这次手势是一次滚动操作画板canvas没有明确告诉浏览器“这块区域的触摸事件归我管你别抢”。修复方式是给画板canvas设置CSS属性touch-action: none。与之配合的另一条纪律是不要在canvas上监听touch事件后手动调用preventDefault因为被动事件监听器会吃掉这个调用而且容易导致报错。直接使用Pointer Events加touch-action浏览器层面的手势识别被切断事件分发是干净的。5.3 翻页后笔迹消失PDF重绘把画板层顶掉了翻页时如果直接重绘PDF canvas没有先保存批注画板的状态就会看到满屏笔迹瞬间消失。这背后的逻辑其实不复杂两份canvas是平级元素批注canvas盖在PDF canvas上面但PDF canvas重绘时浏览器可能触发合成层更新把批注canvas暂时盖住或者导致画板上下文被重置。解决方式是把笔迹底图inkLayer全局持有不用的时候保留在存储层显示时通过drawImage贴回去。翻页动作完成后等PDF渲染结束立刻重放当前页的笔迹而不是等用户重新落笔才补画。项目里把这一动作收敛进了useAnnotation的syncInkLayer函数翻页回调里必须调用它。5.4 大PDF卡顿与内存泄漏worker与缓存失控一份几十MB的PDF连续快速翻页后页面变得越来越卡甚至白屏。查下来有两个元凶pdf.js的worker线程没有随页面销毁而释放以及pageCache在边界判断里写漏了一个等于号导致缓存一直不清理。worker泄漏会持续占用内存cache不断增长则直接撑爆canvas资源。解决方式一是页面卸载时显式调用pdfDoc.destroy()和worker.terminate()二是trimCache的保留策略调成左右各1页后停止扩展。还需注意getDocument返回的Promise在页面销毁后resolve会有报错风险初始化时要往AbortController里注册取消信号销毁时主动中断。5.5 橡皮擦擦出“黑边”destination-out的重绘时机问题橡皮擦用destination-out擦除时如果擦除过程中触发了其他操作——比如手指短暂停下触发pointercancel——半透明的像素残留在画板上导出后出现一条条淡黑色的擦痕。原因在于destination-out是破坏性的像素操作它没有“撤销本次擦除”的天然能力一旦像素被擦掉只能靠整个画板重绘恢复。所以真正的橡皮擦实现不建议直接操作显示canvas而是把擦除变成一个“笔迹编辑操作”记录擦除路径后统一对strokeStack做裁剪再重建笔迹底图。这样既不产生残留也能保证任意时刻撤销、回放都不损坏像素内容。如果产品上非要做“像素级橡皮擦”那导出时就必须连底图一起导出并且回放逻辑要同步重建。6. 二次开发方向从单页批注到多页协同6.1 从单页画板升级到多页画板现在代码里一页一个canvas多页化之后要改造成“一页一个画板实例”的Map结构。每条笔迹必须加上page字段翻页时只把对应页的strokes渲染到当前可见的canvas上。业务侧建议加一层pageIndex到stroke数组的索引避免全量遍历。// annotationStore.js 多页改造 const strokesByPage new Map(); function pushStroke(pageNo, stroke) { const list strokesByPage.get(pageNo) || []; list.push(stroke); strokesByPage.set(pageNo, list); redrawPage(pageNo); }多页改造过程中最容易遗漏的是PDF虚拟滚动复用时移出屏幕的页面canvas会被销毁但对应的strokes数据不能跟着销毁否则用户滚回来笔迹就没了。思路是把stroke数据独立于canvas生命周期canvas只负责“把数据画出来”。6.2 笔迹数据协议设计给后端一个可回放的格式批注最终要进业务系统协议里至少包含page、type、color、width、points五个字段。type区分画笔、荧光笔还是矩形框point里的pressure字段建议保留服务端就算不用也不碍事。字段越精简跨端同步越稳不要给协议加不必要的元信息。// 笔迹协议示例 { page: 3, type: pen, color: rgba(255, 0, 0, 0.8), width: 2.5, points: [ { x: 120.5, y: 340.2, pressure: 0.8 }, { x: 121.0, y: 341.0, pressure: 0.6 } ] }回放时前端拿到这份协议逐条调用drawStroke逻辑即可。这一整套流程里最容易让后端同事崩溃的是坐标基准不统一。务必在协议文档里写清楚x和y是PDF原始坐标系的数值不是canvas像素值两边才不会有偏差。6.3 性能优化三板斧离屏缓存、合成层、降采样移动端画板性能的瓶颈通常不在绘制本身而在于频繁的整页重绘和canvas尺寸变换。第一板斧是离屏缓存PDF页面渲染结束后缓存为离屏canvas翻页时不再触发pdf.js重渲染直接drawImage到显示画布。第二板斧是给批注canvas设置独立的合成层用CSSwill-change: transform让浏览器把画板层提升到独立GPU层避免每次重绘都重新参与合成。第三板斧是降采样笔迹点过于密集时按距离阈值抽稀比如相距小于1物理像素的点直接丢弃。我现在接批注类需求都会先画一张坐标换算图把PDF原始坐标系、CSS像素坐标系和canvas物理像素坐标系三者边界标清楚再动手写代码。每写完一个模块就强制走一遍“落笔→缩放→翻页→导出→回放”的完整闭环确认数据不变形才继续下一个功能。这个习惯帮助我在这个项目里少返工了至少三轮希望也能帮到你。本文还有配套的精品资源点击获取