企业官网建设流程全解析

简介：面向移动端开发者的Canvas画板批注PDF预览方案，结合PDF.js实现在手机浏览器中渲染PDF并支持触控批注，适用于H5文档审阅、在线签字等场景。压缩包共150个文件，包含75个gif动图演示、34个js脚本、11个png图片、10个css样式等，包体仅2.4MB，便于快速部署学习。gif动图直观展示操作效果，js与css为可直接引用的核心代码与界面样式，png/jpg等提供图标素材。方案覆盖PDF解析与渲染、Canvas触摸事件处理、批注绘制与持久化导出等核心知识点，附带完整示例页面和可运行的HTML/JS代码。已有1750人学习下载，适合具备基础JS知识、希望掌握移动端批注功能的Web前端开发者参考实践。

1. 移动端 H5 里的 Canvas 画板，凭什么给 PDF 做批注不白屏

做移动端 H5 的工程师，大概率都撞过这样一个需求：给一个在线审批页面加上批注能力，用户要在 PDF 合同、图纸或试卷上直接圈画签字，然后把标注后的结果回传给后端。第一反应往往是“PDF 不就有自带注释吗”，可真落到移动端浏览器里，PDF 原生注释基本不可用，唯一靠谱的路线是让 Canvas 画板叠在 PDF 渲染层上面，用一套坐标换算把笔迹钉在文档上。这里的核心难点不是“画一笔”的能力，而是 PDF 预览和画板两层如何共享滚动、缩放与手势，以及性能是否经得住 iPad 和 Android 千元机的考验。

一句话描述这个标题的价值：canvas 负责笔迹绘制，移动端手势负责交互输入，批注层与 PDF 渲染层通过坐标系统绑定，最终实现“所见即所得”的在线圈划与导出。它能解决的核心诉求是：在 H5 应用里给 PDF 文档添加手写签名、要点圈画和高亮标记，同时保证笔迹不因滚动画布而错位、不因 PDF 翻页而丢失。适合的读者包括做在线教育题批、电子合同签署、图纸审核和移动 OA 审批的前端开发者。如果你拿到的是 vue / react 混合栈，盯住渲染层与批注层的绑定关系比纠结“谁画得好看”重要得多。

文章从方案选型说起，带你看一套能跑的 canvas 移动端批注 pdf 预览技术链路：从 PDF 渲染到画板叠加、从坐标换算到手势协调、从导出合并到真机避坑，最后给出一个验证批注精度的调试思路。

2. PDF 渲染方案怎么选：pdf.js 承载渲染，Canvas 层只画批注

2.1 常见做法：为什么把 PDF 转成图片再让 Canvas 叠上去

移动端做 PDF 预览，业界最成熟的开源渲染引擎是 pdf.js，它可以把 PDF 解析成 Canvas 位图或 SVG 矢量图。常见做法是把每一页渲染成一个离屏 Canvas，再把这个 Canvas 当作背景图放到页面里；批注层用第二个全屏 Canvas 叠在上方，透明背景，只负责画线、画矩形、写文字。两层各自独立，滚动时同时移动，缩放时同时变换，才能避免“线飘了”的尴尬。

选 pdf.js 而不是原生 iframe 或浏览器内置预览器，最关键的原因是：移动端微信浏览器、WebView 和部分国产浏览器对 PDF 内嵌预览的支持极差，iOS 上可能直接跳转新页面或者空白，而 pdf.js 把渲染控制权交给你，渲染进度、缩放比例、页数跳转都能在 JavaScript 层处理。另一个原因是批注数据需要和 PDF 页码绑定，原生预览器完全做不到。

在 Vue 项目里引用 pdf.js，一般用pdfjsLib.getDocument()加载 PDF，再用pdfjsLib.GlobalWorkerOptions.workerSrc指定 worker 路径。下面是一段核心初始化逻辑：

// pdf 加载与页面渲染 - 基于 pdf.js import * as pdfjsLib from 'pdfjs-dist'; pdfjsLib.GlobalWorkerOptions.workerSrc = '/static/pdfjs/pdf.worker.min.js'; async function renderPdfPage(url, pageNum, scale) { const pdf = await pdfjsLib.getDocument(url).promise; 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; // 这个离屏 canvas 作为批注层的背景 }

这段代码里有三个关键点：第一，workerSrc 必须指向实际部署的 worker 文件，很多项目白屏就是 worker 路径没配好；第二，scale由当前设备的 DPR 和用户缩放比例共同决定，不能直接用 CSS 像素当 Canvas 物理像素，否则渲染出的 PDF 会发虚；第三，每次翻页和缩放都会触发重新渲染，必须做缓存处理，否则卡顿非常明显。

2.2 渲染上屏：离屏 Canvas 铺页面，批注层叠加在上方

pdf.js 渲染出来的离屏 Canvas 要放进页面，通常做法是把该 Canvas 作为绝对定位的元素铺满可视区，外层容器负责滚动和缩放。批注层 Canvas 也铺在同一个容器里，用相同的 CSS 尺寸和定位属性，pointer-events允许接收手指触摸。

页面结构大致长这样：外层是一个尺寸等于 PDF 页面的 div，里面放一个 Canvas 背景图，再放一个 Canvas 批注层，两个 Canvas 的 CSS 尺寸保持完全一致。批注层负责处理 touch 事件，背景层负责显示 PDF 内容。下面给出结构代码：

<div id="pdf-viewer" ref="viewer" class="viewer-wrap"> <!-- PDF 渲染层 --> <canvas ref="pageCanvas" class="page-canvas"></canvas> <!-- 批注层 --> <canvas ref="annotateCanvas" class="annotate-canvas"></canvas> <!-- 滚动容器，接收滚动手势 --> <div class="scroll-layer" @touchstart="onTouchStart" @touchmove="onTouchMove"></div> </div>

.viewer-wrap { position: relative; width: 100%; height: 100vh; overflow: auto; -webkit-overflow-scrolling: touch; } .page-canvas, .annotate-canvas { position: absolute; top: 0; left: 0; width: 100%; height: 100%; touch-action: none; } .scroll-layer { position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 2; }

注意.scroll-layer放在最上层，它既接收滚动事件也接收绘制事件。真正的工作流是：用户在批注模式下手势画线；在阅读模式下触摸滚动画布。两种模式通过一个 mode 变量切换，不能在批注模式里让浏览器滚动。touch-action: none是为了禁掉浏览器的默认手势，否则画线时页面会跟着滚。

2.3 性能预算：一页 PDF 渲染的极限尺度和缓存策略

移动端 Canvas 批注最大的性能陷阱是：一张 PDF 页面在 iPad 上渲染成 2048x2732 的位图，内存和绘图开销会直接打爆低端机。业内通用的做法是限制 scale 上限，比如最大只渲染到 2 倍 DPR，超出 2 倍的清晰度收益在手机屏幕上根本看不出来。

我一般对单页 Canvas 面积做预算：物理像素总数不超过 4096x4096，单页渲染时长控制在 1 秒以内（中端机）。超出这个范围就把 PDF 按需渲染，只渲染当前页和相邻页，页面离开视口后释放 Canvas 内存。另外，必须做页面的 Canvas 缓存：把渲染过的离屏 Canvas 存到 Map 中，翻页返回时直接取缓存，而不是重新渲染一遍，这一步对滚动手感提升极其明显。

pdf.js 渲染时有一个容易忽略的“隐性重绘”：每次滚动时如果把背景 Canvas 重新贴到新位置，会造成合成层抖动。正确做法是移动最外层容器位置，而不是改 Canvas 尺寸。也就是说，滚动发生在viewer-wrap这一层，两个 Canvas 不动。这让浏览器把整块内容当成合成层，避免了反复局部重绘。

3. 坐标系统设计：把手指的像素点钉在 PDF 文档的真实位置上

3.1 四层坐标系：屏幕点、CSS 点、Canvas 点、PDF 点如何换算

批注功能做的第二件事，是把手指按下的屏幕坐标换算成 PDF 文档上的坐标。这里有四个坐标系在打架：屏幕坐标（手指在浏览器窗口的位置）、CSS 坐标（元素在页面布局中的位置）、Canvas 绘图坐标（Canvas 内部的世界坐标）、PDF 坐标（PDF 文档自身的坐标）。如果换算链条断裂，就会出现“在 A4 纸左上角画一笔，结果落在右上角”这种翻车现场。

换算关系常见做法是：屏幕坐标减去容器左上角位置，得到容器内 CSS 坐标；CSS 坐标乘以 DPR 得到 Canvas 物理坐标；Canvas 物理坐标除以当前缩放比例，得到 PDF 文档坐标。用代码表示如下：

// 屏幕坐标 -> PDF 文档坐标 function screenToPdf(clientX, clientY) { const rect = pageCanvas.getBoundingClientRect(); const cssX = clientX - rect.left; const cssY = clientY - rect.top; const dpr = window.devicePixelRatio; const canvasX = cssX * dpr; const canvasY = cssY * dpr; // pdf 点通过当前缩放比例还原 const pdfX = canvasX / (scale * dpr); const pdfY = canvasY / (scale * dpr); return { x: pdfX, y: pdfY }; }

参数说明：scale是用户当前浏览 PDF 的缩放倍数，dpr是设备像素比。这段代码的前提是两个 Canvas 铺满同一个容器内且没有偏移。还有一个细节：PDF 坐标原点是左下角，屏幕坐标原点是左上角，所以 y 轴需要翻转：pdfY = pageHeight - pdfY。

3.2 批注层重绘策略：矢量点集 + 实时路径，不是位图落盘

画批注的另一个关键选择是：批注到底是用位图形式保存还是按矢量点集保存。常见做法是把批注存成矢量点集，每次重绘时从点集重新画线。这样做的原因在于：位图一旦存下来就固定了分辨率，用户缩放 PDF 后，批注会糊；而矢量点集可以随着缩放重新计算绘制坐标，永远清晰。

具体实现时，在批注层 Canvas 上把一次笔画记录成points数组。touchmove 时只把新点 push 进去，然后重绘整条线。重绘开销可控，因为 Canvas 的 2D context 画 polyline 非常快。核心逻辑如下：

// 批注笔画数据结构 let strokes = []; // 所有完成的笔画 let activeStroke = []; // 正在绘制的笔画 function handleTouchMove(evt) { const touch = evt.touches[0]; const point = screenToPdf(touch.clientX, touch.clientY); activeStroke.push(point); // 清屏重绘所有笔画 ctx.clearRect(0, 0, annotateCanvas.width, annotateCanvas.height); drawAllStrokes(); // 实时画当前笔画 drawStroke(activeStroke, '#ff0000', 3); } function drawStroke(points, color, width) { if (!points.length) return; ctx.beginPath(); ctx.moveTo(points[0].x, points[0].y); for (let i = 1; i < points.length; i++) { ctx.lineTo(points[i].x, points[i].y); } ctx.strokeStyle = color; ctx.lineWidth = width; ctx.stroke(); }

注意：这里的坐标是 PDF 文档坐标，而不是 Canvas 物理坐标。真正绘制前需要把文档坐标乘上当前缩放和 DPR，画到批注 Canvas 里。我习惯维护一个viewportTransform，统一在画的时候转换。这样每次缩放后只用清屏再重画一遍即可，不需要改已有笔画的数据。

3.3 锐化位图带来的陷阱：为什么缩放后批注模糊，怎么重采样

Canvas 的位图重采样是个玄学问题。很多人发现：在 iPad 上画完批注，缩小 PDF 后再放大，笔迹模糊成一片。原因不是 Canvas 不支持矢量，而是你把笔画画在位图上之后，位图缩放是像素插值，自然损失边缘。解决之道是“重绘而非缩放”：缩放时把批注层 Canvas 的width和height按新的 DPR 值重复设置，然后按新的变换矩阵把所有笔画再画一遍。

// 缩放变化后的重绘 function onZoom(newScale) { scale = newScale; // 重置批注层尺寸，强制清屏 annotateCanvas.width = annotateCanvas.height = 0; annotateCanvas.width = containerWidth * dpr; annotateCanvas.height = containerHeight * dpr; ctx.setTransform(dpr * scale, 0, 0, dpr * scale, 0, 0); drawAllStrokes(); // 同时重新渲染pdf层 renderPdfPage(currentPage, scale); }

参数上，ctx.setTransform直接设置了从文档坐标到物理像素的缩放矩阵。之后画任何笔画都按文档坐标来写，省去每一笔都乘转换的繁琐。这个方案的代价是缩放过程中必须重新绘制一遍所有笔画，笔画多到几百条时可能掉帧，所以后续讲性能优化时会提到用“分层 Canvas 缓存已完成笔画”的方案。先记住：别对位图做 scale 操作，要重采样重绘。

4. 移动端手势协调：绘制模式与阅读模式如何不打架

4.1 单指画线、双指缩放、单指滑动翻页：事件的三种身份识别

移动端批注体验最大的难点不是“能画”，而是“能不能同时滚动”。单指画线时手指在屏幕上移动，浏览器默认行为是滚动页面；双指缩放时浏览器默认行为是页面缩放。必须在 JS 层通过touchstart时的事件点数来区分手势意图，然后对后续移动事件做不同的处理。

常见做法是“先到先得，锁定模式”：touchstart触发时如果只有一根手指，进入“绘画”模式；如果有两根手指，进入“缩放”模式。锁定后直到所有手指抬起才解除。这样避免了绘制到一半突然手指并拢导致的手势切换。代码示意如下：

// 手势模式控制 let gestureMode = 'idle'; // 'draw' | 'zoom' | 'scroll' function onTouchStart(evt) { evt.preventDefault(); if (evt.touches.length === 1) { gestureMode = 'draw'; activeStroke = []; } else if (evt.touches.length === 2) { gestureMode = 'zoom'; lastPinchDistance = getDistance(evt.touches[0], evt.touches[1]); } } function onTouchMove(evt) { if (gestureMode === 'draw') { handleDrawMove(evt); } else if (gestureMode === 'zoom') { handleZoomMove(evt); } } function onTouchEnd() { if (gestureMode === 'draw') { strokes.push(activeStroke); } gestureMode = 'idle'; }

这里有个血泪经验：不能依赖click或mouse事件做移动端画线，touch 事件和 mouse 事件在 iOS 上会有 300 毫秒延迟，同时触发会带来非确定性行为。统一用touch事件，且在touchstart时第一时间preventDefault，避免浏览器默认的滚动和长按菜单。

4.2 双指缩放计算与中心点保持：图片不飘的数学

双指缩放是另一个容易翻车的地方。用户希望以两指中心为锚点缩放，就是两指之间的那个点不漂移。计算公式是：读取两指的clientX/clientY，算出中心点坐标；再算出两指距离distance，与上一次距离比值的对数就是缩放系数；最后为了让中心点保持不动，还要把容器滚动位置按照缩放比例偏移。

代码实现如下：

// 双指缩放事件处理 function handleZoomMove(evt) { const dist = getDistance(evt.touches[0], evt.touches[1]); const newScale = clamp(scale * (dist / lastPinchDistance), 0.5, 4); // 计算两指中心在容器内的坐标 const centerX = (evt.touches[0].clientX + evt.touches[1].clientX) / 2; const centerY = (evt.touches[0].clientY + evt.touches[1].clientY) / 2; const rect = viewerRef.getBoundingClientRect(); const localX = centerX - rect.left; const localY = centerY - rect.top; // 按比例调整滚动位置以保持锚点 const ratio = newScale / scale; viewerRef.scrollLeft = (viewerRef.scrollLeft + localX) * ratio - localX; viewerRef.scrollTop = (viewerRef.scrollTop + localY) * ratio - localY; scale = newScale; lastPinchDistance = dist; renderPdfPage(currentPage, scale); redrawAnnotations(); }

这段代码里clamp函数限制了缩放范围，避免用户缩到 0.1 这种离谱值。注意：必须更新滚动容器的 scrollLeft / scrollTop，否则缩放后中心点会偏移。这一条我曾漏掉，结果用户双指缩放一次，页面就飘出可视区，调试了很久才发现是滚动位置没联动。

4.3 橡皮擦与撤销栈：数据结构和渲染性能的配合

移动端批注的橡皮擦不能做成“位图擦除”，因为位图擦除只影响视觉像素，不影响底层 PDF 坐标数据。常见做法是：每次擦除时把命中的笔画从strokes数组里移除，然后清屏重绘整层。笔画的命中检测用“点到折线距离”。

// 橡皮擦：计算点到线段距离，判定是否擦除 function hitTestStroke(point, stroke, threshold) { for (let i = 1; i < stroke.length; i++) { const dist = pointToSegmentDistance(point, stroke[i - 1], stroke[i]); if (dist < threshold) return true; } return false; } function eraseAtPoint(point) { const threshold = 8 / scale; // 阈值随缩放调整 strokes = strokes.filter((s) => !hitTestStroke(point, s, threshold)); redrawAnnotations(); }

撤销栈则是简单的快照式：入栈时深拷贝一个strokes的引用数组，而不是拷贝每个点。代价是内存，好处是快速。注意清理撤销栈的时机：PDF 翻页后撤销栈应当清空，因为跨页撤销语义太复杂，没必要实现。

5. 避坑清单：移动端 Canvas 批注最容易翻车的五个细节

5.1 iOS 橡皮筋回弹导致笔迹错位

现象：用户在 iOS Safari 里快速画线，笔画中途出现一个明显的断裂或位移，像是画了一个折线。原因是 iOS 的橡皮筋滚动效果：手指往下滑到顶部时，页面会露出顶部的白色背景，等手指抬起后回弹。这个过程中touchmove事件照常触发，但坐标在回弹期间发生了变化。

解决：给document.body和批注容器加overscroll-behavior: none，同时阻止touchmove的默认行为。如果批注目标是微信浏览器，还可以在touchmove里判断document.scrollingElement.scrollTop是否在边界，是则直接return。

5.2 Android WebView 的高 DPR 兼容差异

现象：同一段代码在 iPad 上批注正常，在小米 8 的 WebView 里笔迹只有原本的一半大小，或者整张 PDF 显示模糊。原因在于 Android WebView 的devicePixelRatio在系统缩放设置改变后不是整数，不同 WebView 对ctx.scale(dpr, dpr)的支持程度有差异。

解决：渲染 PDF 层时不要用devicePixelRatio直接赋值，先检测ctx.setTransform是否可用。如果不可用，退化为手动乘坐标。另外在 Android 上强制window.devicePixelRatio = 2不是好办法，建议用 CSSviewportmeta 标签统一视口宽度。

5.3 页面切换后批注层 Canvas 被系统清空

现象：App 切到后台再回来，批注内容全部消失。原因是移动端浏览器在内存紧张时会回收 Canvas 的位图存储区域。Canvas 的width属性被系统重置后，内容就没了，但 DOM 元素还在。

解决：在visibilitychange事件里监听页面从后台恢复，然后把strokes数组重新绘一遍。因为笔画数据是存在 JS 数组里的，不会随 Canvas 丢失。这也说明了为什么不能把批注直接画在 Canvas 上而不保存数据。

5.4 PDF 大文件的加载进度与渲染阻塞

现象：加载 80 页的 PDF，用户看到白屏接近 10 秒，然后页面一次性弹出。原因是pdf.getDocument()默认会把整个 PDF 都 fetch 下来，且大规模渲染阻塞主线程。

解决：给 pdf.js 传入disableAutoFetch = true和rangeChunkSize参数，让它按需加载每一页的数据。渲染时用requestIdleCallback分页渲染，只渲染可视页和前后一页。看到白屏时不能一味认为渲染慢，也可能是 worker 文件没部署成功，请求 404 了。

5.5 坐标换算的边界问题：横屏旋转后全部偏移

现象：手机横竖屏切换后，批注位置整体偏移了半个屏幕。原因是getBoundingClientRect()在旋转前后给的容器位置不同，而 Canvas 的物理尺寸没有跟随变化。

解决：监听orientationchange，重新获取容器boundingClientRect，更新批注层的width/height，更新所有笔画的变换矩阵，然后重绘。屏幕旋转后没有重绘是这一类 bug 最常见的源头。

6. 导出与验证：把批注合成 PDF 或图片，并检查坐标是否漂移

6.1 合成导出：用离屏 Canvas 将 PDF 层与批注层合并出图

批注完成后的导出需求有两种常见形态：一种是导出为图片（PNG/JPEG），直接发给对方确认；另一种是导出为 PDF 文档，和原 PDF 合并。前者实现起来简单：创建一个离屏 Canvas，宽高等于 PDF 页面的物理像素，先把 PDF 背景画上去，再把批注层用drawImage贴上去，最后toDataURL('image/png')。后者的常见做法是：把图片塞进一个新的 PDF 页，或者用 pdf-lib 这类库将图片转成 PDF 页后与原文档合并。

// 导出批注后图片 function exportPageAsImage(pageNum, scale) { const pdfCanvas = pdfPageCanvasCache.get(pageNum); const annotCanvas = annotateCanvas; const exportCanvas = document.createElement('canvas'); exportCanvas.width = pdfCanvas.width; exportCanvas.height = pdfCanvas.height; const ctx = exportCanvas.getContext('2d'); ctx.drawImage(pdfCanvas, 0, 0); // 批注层是透明背景，直接原样贴上去 ctx.drawImage(annotCanvas, 0, 0); return exportCanvas.toDataURL('image/png'); }

注意：导出时批注层的坐标必须用文档坐标转换回物理像素，即乘以 DPR。如果你一直用setTransform绘制，导出的 canvas 直接从annotateCanvas截取是没有问题的。但如果你在批注层上做过滚动偏移（因为容器滚动导致 Canvas 位置变化），导出前要把 Canvastranslate回原点。

6.2 验证精度：一张网格纸 + 双指缩放，五分钟检查漂移

这一节是我的习惯做法，也是血泪经验总结。每次做完批注功能，我不会急着自己画一版看效果，而是调一张极简网格纸 PDF（毫米格）。在四个角和中心各画一个交叉点和一条一米长的线，导出后与底图对比。如果在网格线上完美重叠，坐标换算就没有问题。

操作步骤：

1. 用 PDF 工具生成一张 A4 网格纸，载入应用。
2. 单指分别画水平线和垂直线，各画到网格边缘。
3. 双指缩放到 200%，再画交叉线。
4. 导出，放大图片，观察笔触是否落在网格线上或者偏移出一个固定的像素数。

如果偏移量是固定像素，说明换算公式里少了某个常量偏移；如果每个缩放级别偏移量不同，说明没有按scale比例乘回。

6.3 最后一招：把批注数据上报后端与回放，做最真实的性能回归

移动端 Canvas 批注的性能问题只有真机才能暴露，我保留的最后一个验证手段是：把 strokes 数组中的点集上报到后端，用回放播放器在电脑上复现绘制过程。回放可以控制绘制速度，从而判断每个阶段的 FPS 是否低于预期。这比在模拟器里看肉眼流畅度更可靠——因为模拟器的渲染行为和真机差异很大。

使用时给每次笔画打上时间戳，回放时按时间间隔逐个插入点。回放器在 Canvas 上照着笔画顺序重新走一遍。如果某一段开始明显掉帧，就在对应区域调试该段点的密集程度和 canvas 面积。注意一点：笔画的点集不要过度采样，一般每 10 像素采一个点就够了，超过这个密度只是在浪费 CPU，手感并不会变好。

做这个功能已经整整一年，我的习惯是导出验证永远排在功能开发后面，但重要性永远排第一。坐标不漂移，比画得好看重要一万倍。希望这篇内容能让你在移动端 Canvas 画板批注 PDF 的道路上少踩几个坑。

本文还有配套的精品资源，点击获取