移动端 PDF 手写批注：Canvas 分层与坐标映射实战

简介：面向移动端 H5 场景的 Canvas 画板与 PDF 批注预览方案，适合需要在前端实现文档阅读、手写标注与页面绘制的开发者参考。整包围绕 PDF.js 解析渲染与 Canvas 触控绘制两条主线展开，涉及 PDF 文档加载、页面缩放渲染、touchstart/touchmove/touchend 事件处理、批注绘制与导出保存等环节，并附有配套样式与图标素材。压缩包共 150 个文件，以 34 个 js 脚本为核心逻辑，配合 10 个 css 样式、4 个 html 页面与若干 png、gif、jpg 图像资源，另有 1 个 pdf 示例文档及字体、音频等辅助文件，整体约 2.4MB，结构紧凑，便于直接运行调试。目前已有 1750 人学习下载。读者可从中获得移动端画板交互的完整实现参考、PDF 渲染与批注叠加的代码思路，以及素材与样式的组织方式，适合用作二次开发的基础模板。

1. 从「手机上看PDF顺手划两笔」说起

某个做移动端文档协作的团队接到一个需求：用户在手机浏览器里打开一份合同 PDF，直接用手指在页面上圈重点、写几笔批注，关掉再打开还能看到。排期两周，开发者第一反应是找个现成的 H5 批注库，试了三四个之后发现，要么手势和 PDF 滚动打架，要么笔迹在 iPhone 上发虚，要么批注换台设备就错位。canvas、pdf、画板、H5、js 这几个词单独看都不陌生，真正揉进一个页面里时，坑全在交叉地带。

这套方案要解决的问题很具体：在移动端浏览器里稳定预览 PDF，叠加一层可手写的批注画板，并且批注能按页保存、任意缩放后仍能对齐回显。适合正在做移动端文档类毕设或课程设计的学生，也适合需要给现有 H5 项目补一块批注能力的前端开发者。下面按选型、渲染、画板、数据、避坑、验收的顺序展开，每一段都对应一个可以照着写的模块。

2. 技术选型与总体架构：四层结构与三个核心模块

移动端 PDF 批注这件事，最忌讳一上来就写绘制代码。先想清楚页面里到底有几个会变化的东西：PDF 底图、笔迹、缩放状态、批注数据。这四样东西的变化频率完全不同，混在一起写，后面加一个撤销功能就得推倒重来。

2.1 为什么选 PDF.js 加自绘 canvas，而不是现成批注插件

选型要先把约束摆出来。移动端浏览器的内存和 GPU 都有限，PDF 底图不能每次画一笔就重绘一遍；批注需要精确到点序列，方便后续做撤销、橡皮擦和跨设备同步；离线或弱网场景下，渲染库要能本地化，不依赖服务端转图片。这三条约束一摆，现成插件基本出局——大多数插件要么把批注存成整页图片（体积大、不可编辑），要么把绘制逻辑和 PDF 渲染耦合在一起（无法单独控制重绘）。

PDF.js 是浏览器端解析和渲染 PDF 最成熟的选择，它把每页渲染到一个 canvas 上，输出的是标准的 Canvas 2D 上下文，后面再叠一层自己的画板就很自然。批注层不用第三方库，自己用 Canvas 2D 画，原因是笔迹的点序列、平滑算法、橡皮擦策略这些都需要和业务数据结构对齐，用现成库反而要花时间绕开它的抽象。代价是键盘事件、触摸事件、撤销栈都得自己维护，但这部分代码量可控，大约三百行以内能覆盖核心逻辑。

这里有个容易被忽略的取舍：PDF 底图用 PDF.js 渲染成 canvas 位图，而不是用 SVG 或 DOM 文本层。SVG 方案在缩放时清晰度好，但大量文本节点在移动端会拖慢滚动；位图方案在缩放倍数高时会糊，解决办法是把渲染倍率跟上 DPR，而不是换技术路线。我一般会在项目初期就把渲染倍率单独抽成一个参数，后面调清晰度不用改渲染流程。

2.2 四层架构：渲染层、批注层、数据层、状态层

整体拆成四层，层与层之间只通过明确的接口通信，这是后面能加功能而不翻车的基础。

渲染层负责把 PDF 页面画到底层 canvas 上，输入是页码和缩放比例，输出是一张与页面等比的位图。这一层不关心笔迹，也不关心用户当前选的是钢笔还是橡皮。

批注层是叠在底图上方的一张透明 canvas，接收触摸事件、画出笔迹、维护当前正在画的这一笔。它只负责“看得见”的部分，画完一笔就把点序列交给数据层，自己不留历史。

数据层保存每一页的批注数组，每条批注包含页码、工具类型、颜色、线宽和归一化后的点序列。这一层不碰 DOM，也不碰 canvas，纯数据操作，方便做序列化、撤销和回显。

状态层管理当前工具、当前页码、缩放比例、撤销栈和重做栈。它像一个调度中心，工具切换、缩放变化、撤销操作都从这里发出，其他三层监听变化后各自更新。

四层拆完之后，一个典型交互的链路就清晰了：手指按下，批注层开始采集点；手指抬起，批注层把点序列交给数据层；数据层追加一条记录并通知状态层更新撤销栈；状态层再通知批注层重绘当前页。每一步职责单一，出问题时能快速定位是哪一层没对上。

2.3 工程目录与依赖配置

目录按层划分，不按文件类型划分，这样新人接手时能一眼看出哪块代码属于哪一层。

{ "name": "mobile-pdf-annotator", "private": true, "dependencies": { "pdfjs-dist": "按项目实际锁定版本", "vue": "按项目实际锁定版本" }, "scripts": { "dev": "vite", "build": "vite build" } }

依赖里真正关键的只有pdfjs-dist，UI 框架按团队习惯选，不影响核心逻辑。pdfjs-dist需要把 worker 文件单独拷贝到静态资源目录，否则打包后会出现“Worker 加载失败”的报错，这一步在构建配置里加一条拷贝规则即可。目录结构建议这样组织：

src/ pdf/ renderer.js # 渲染层：加载文档、渲染页面 viewport.js # 视口计算与 DPR 适配 annotate/ board.js # 批注层：事件采集、笔迹绘制 stroke.js # 笔迹平滑与路径生成 coords.js # 屏幕坐标与归一化坐标互转 store/ annotations.js # 数据层：批注增删改查 history.js # 状态层：撤销重做栈 page/ viewer.js # 页面组装与手势仲裁

renderer.js和board.js之间不直接引用，由viewer.js在中间协调。这样后面如果要把批注层换成 WebGL 渲染，只需要替换board.js，渲染层和数据层不用动。工程上这种“预留替换点”的做法，比追求一次写对更实际。

3. PDF 渲染层落地：视口变换与手势冲突处理

渲染层是整套方案的地基。地基没打好，后面笔迹画得再顺，一缩放就全偏。这一章把 PDF.js 的渲染管线和移动端的手势处理拆开讲，每一步都给到能直接跑的代码。

3.1 PDF.js 渲染管线：从文件到 canvas 位图

PDF.js 的渲染流程是固定的四步：加载文档、获取页面、计算视口、执行渲染。移动端要额外处理两件事，一是 worker 的路径配置，二是渲染任务的取消。

import * as pdfjsLib from 'pdfjs-dist'; // worker 必须指向实际可访问的静态资源，否则主线程解析会卡死页面 pdfjsLib.GlobalWorkerOptions.workerSrc = '/static/pdf.worker.min.js'; async function renderPage(pdfDoc, pageNumber, scale, canvas) { const page = await pdfDoc.getPage(pageNumber); // getViewport 根据缩放比例算出页面在屏幕上的实际尺寸 const viewport = page.getViewport({ scale }); const dpr = Math.min(window.devicePixelRatio || 1, 3); // canvas 的绘图缓冲区按 DPR 放大，CSS 尺寸保持逻辑像素 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'); ctx.setTransform(dpr, 0, 0, dpr, 0, 0); const renderTask = page.render({ canvasContext: ctx, viewport }); // 页面快速切换时取消上一个渲染任务，避免旧页面覆盖新页面 return renderTask.promise; }

scale是缩放倍率，初始值通常取 1，表示按 PDF 原始尺寸的 CSS 像素渲染。dpr封顶 3 是血泪经验，低端安卓机上 DPR 经常报 3 以上，实际超过 3 之后清晰度提升肉眼几乎看不出，但显存占用翻倍，滚动直接掉帧。setTransform代替ctx.scale，是因为前者会重置之前的变换矩阵，页面切换时不会累积缩放。

渲染任务取消这一点值得单独说。用户在快速翻页时，上一页的渲染可能还没完成，新页面就开始渲染，两个任务同时往一块 canvas 上画，结果是画面撕裂。PDF.js 的renderTask自带cancel()方法，在页面切换前调用一次，能避免大部分花屏问题。

3.2 视口变换与设备像素比适配

移动端的坐标系有三套：触摸事件的坐标是 CSS 像素，canvas 的绘图缓冲区是物理像素，PDF 页面本身又有一套以点（point）为单位的坐标。批注要准确落在 PDF 上，必须把三者串起来。

// 把页面容器上的触摸坐标换算成 PDF 页面内的归一化坐标 function toNormalizedPoint(clientX, clientY, canvasRect, viewport) { const cssX = clientX - canvasRect.left; const cssY = clientY - canvasRect.top; // 归一化：除以 viewport 的逻辑宽高，得到 0~1 的比例 return { x: cssX / viewport.width, y: cssY / viewport.height }; } // 回显时把归一化坐标还原成当前 viewport 下的 CSS 坐标 function toCanvasPoint(normalized, viewport) { return { x: normalized.x * viewport.width, y: normalized.y * viewport.height }; }

这里的关键决定是批注存归一化坐标，而不是像素坐标。像素坐标在缩放后就失效了，归一化坐标乘以新的 viewport 尺寸就能还原。canvasRect用getBoundingClientRect()获取，不要用offsetLeft，因为后者在存在滚动容器和 CSS 变换时会算错。

参数上有两个细节。viewport.width是逻辑像素，不是缓冲区像素，换算时不要乘 DPR，否则会偏出两倍。另外，页面容器如果被 CSS 做了transform: scale()，getBoundingClientRect()返回的尺寸是变换后的结果，此时归一化要基于变换后的矩形，否则笔迹会整体偏移。我一般会禁止在页面容器上使用 CSS 缩放，所有缩放统一由 PDF.js 的scale参数控制，减少一类坐标系。

3.3 手势交互：双指缩放与单指绘制的冲突消解

移动端一个手指既要画画又要滚页面，不仲裁清楚就会出现“想画画结果页面滚走了”。处理策略是按触摸点数量分模式：单指且当前工具是画笔时进入绘制模式，双指时进入缩放模式，非画笔工具下单指用于滚动。

let gestureMode = 'idle'; // idle | draw | pinch let lastPinchDistance = 0; board.addEventListener('touchstart', (e) => { if (e.touches.length === 2) { gestureMode = 'pinch'; lastPinchDistance = distance(e.touches[0], e.touches[1]); // 双指落下时，取消正在画的这一笔，避免误触留下半截线 cancelCurrentStroke(); } else if (e.touches.length === 1 && currentTool === 'pen') { gestureMode = 'draw'; startStroke(e.touches[0]); } }, { passive: false }); board.addEventListener('touchmove', (e) => { if (gestureMode === 'pinch' && e.touches.length === 2) { const dist = distance(e.touches[0], e.touches[1]); const ratio = dist / lastPinchDistance; applyZoom(ratio); lastPinchDistance = dist; // 阻止浏览器默认的页面缩放 e.preventDefault(); } else if (gestureMode === 'draw') { appendPoint(e.touches[0]); e.preventDefault(); } }, { passive: false }); board.addEventListener('touchend', (e) => { if (gestureMode === 'draw' && e.touches.length === 0) { finishStroke(); } if (e.touches.length < 2) { gestureMode = 'idle'; } });

passive: false必须显式声明，因为touchmove默认是 passive 的，里面调preventDefault()不会生效，页面照样滚动。distance是两点间欧氏距离，applyZoom里对缩放比例做上下限约束，通常限制在 0.5 到 4 之间，超出范围手指继续张开也不会更糊。

这里有个交互上的取舍：双指落下时直接取消当前笔画，还是保留半截？我的做法是取消，因为双指落下的意图几乎都是缩放，保留半截线会让用户困惑，撤销一次又显得多余。取消的逻辑里要注意同步清理绘制状态和临时点数组，否则下一笔会带上上一笔的残留点。

4. canvas 批注画板：笔迹绘制、坐标映射与数据模型

批注层是用户感知最强的一层，笔迹跟手不跟手、撤销来不及时时灵不灵，全看这一章。核心思路是双 canvas 分层加归一化坐标，配合一个轻量的撤销栈。

4.1 双 canvas 分层：静态底图与动态笔迹分离

页面里放两个 canvas，底层放 PDF 渲染结果，上层透明，专门承载笔迹。这样画一笔只重绘上层，底图不用动，滚动和缩放时也只需要重绘上层。

<div class="page-container" style="position: relative;"> <canvas id="pdf-layer"></canvas> <canvas id="ink-layer" style="position: absolute; left: 0; top: 0;"></canvas> </div>

上层 canvas 的宽高必须和底层完全一致，包括 DPR 放大后的缓冲区尺寸和 CSS 尺寸。实践中容易犯的错是只同步了 CSS 尺寸，忘了同步width/height属性，结果笔迹被拉伸。我一般写一个syncCanvasSize(source, target)的工具函数，在缩放和页面切换后统一调用一次。

分层带来的另一个好处是橡皮擦的实现变简单了。对象擦除模式下去掉某一条批注，只需要清空上层重绘剩余批注，底图纹丝不动。如果只有一张 canvas，每次擦除都要连带重绘 PDF，性能差距在低端机上非常明显。

4.2 笔迹采集与平滑：从触摸事件到点序列

原始触摸点大约每 16 毫秒采一个，直接用折线连起来会看到明显的棱角。常见做法是用二次贝塞尔曲线把相邻三个点连成平滑路径，代价是每个点的计算量略增，但在移动端完全可以接受。

function drawStroke(ctx, points, color, lineWidth) { if (points.length < 2) return; ctx.beginPath(); ctx.strokeStyle = color; ctx.lineWidth = lineWidth; ctx.lineCap = 'round'; ctx.lineJoin = 'round'; // 用相邻点的中点作为贝塞尔控制点，减少折线感 ctx.moveTo(points[0].x, points[0].y); for (let i = 1; i < points.length - 1; i++) { const midX = (points[i].x + points[i + 1].x) / 2; const midY = (points[i].y + points[i + 1].y) / 2; ctx.quadraticCurveTo(points[i].x, points[i].y, midX, midY); } // 最后一个点单独连线，避免路径断开 const last = points[points.length - 1]; ctx.lineTo(last.x, last.y); ctx.stroke(); }

lineCap和lineJoin都设成round，否则快速划动时笔迹端头是方角，看起来像断开的。points是已经换算成 canvas 逻辑坐标的数组，绘制前不需要再乘 DPR，因为上下文已经通过setTransform处理过了。

采集阶段还有一个优化点：touchmove事件在部分安卓机上触发频率不稳定，手指快速划动时点会很稀疏，曲线看起来不连续。解决办法是监听pointermove并开启getCoalescedEvents()，把两次事件之间合并的多个点展开，笔迹会明显更跟手。这个 API 在 iOS Safari 上支持得稍晚，需要做一个存在性判断再降级到普通触摸事件。

4.3 坐标映射与数据模型：屏幕坐标到 PDF 坐标

每条批注的数据结构决定了后面回显、同步、撤销好不好做。字段不用多，但每个都要有明确用途。

// 一条批注的完整结构 const annotation = { id: 'a_1700000000000_1', // 时间戳加自增，避免重复 pageIndex: 0, // 从 0 开始的页码 tool: 'pen', // pen | highlighter | eraser color: '#e53e3e', lineWidth: 2.5, // 逻辑像素，回显时按缩放比例换算 points: [ // 归一化坐标，取值范围 0~1 { x: 0.12, y: 0.33 }, { x: 0.14, y: 0.35 } ], createdAt: 1700000000000 };

lineWidth存逻辑像素而不是归一化值，是因为线宽在缩放时如果跟着等比放大，放大两倍后笔迹会粗得没法看。回显时按lineWidth * scale计算实际线宽，配合一个上限约束，视觉效果更自然。points存归一化坐标的理由在第 3 章已经说过，这里补充一点：归一化之后，同一份批注数据可以在不同尺寸的屏幕上回显，不用为每台设备单独存储。

回显流程是数据层按pageIndex过滤出当前页的批注，逐条调用drawStroke，坐标先用toCanvasPoint还原。整个流程是幂等的，同一份数据重绘多少次结果都一样，这对撤销和重做很重要。

4.4 撤销重做与橡皮擦策略

撤销栈用两个数组实现，一个存已完成的批注，一个存被撤销的批注。新画一笔压入撤销栈并清空重做栈，撤销时从撤销栈弹出压入重做栈，重做反向操作。

const history = { done: [], // 已生效的批注 undone: [] // 被撤销、可重做的批注 }; function commit(annotation) { history.done.push(annotation); history.undone.length = 0; // 新操作后重做链失效 redrawInkLayer(); } function undo() { if (!history.done.length) return; const last = history.done.pop(); history.undone.push(last); redrawInkLayer(); } function redo() { if (!history.undone.length) return; const item = history.undone.pop(); history.done.push(item); redrawInkLayer(); }

橡皮擦建议用对象擦除，而不是像素擦除。像素擦除在 canvas 上要用globalCompositeOperation = 'destination-out'，看起来直接，但擦完之后没法单独恢复某一条被擦掉的笔迹，撤销只能整页回滚。对象擦除把“擦掉”理解为“删除某条批注”，撤销栈天然支持，跨设备同步时也只需要传删除指令，数据量小一个量级。

实现对象擦除时，橡皮擦的触摸点要和每条批注的点序列做命中检测，距离小于阈值（通常是线宽加 8 像素）就判定命中，把该条批注从撤销栈移到重做栈。命中检测用简单的逐点距离比较就够，批注点数量一般不超过几百个，性能不是瓶颈。如果批注特别多，可以先用包围盒做粗筛，再逐点细判。

5. 移动端避坑排查：从笔迹偏移到 iOS 渲染黑屏

这一章列的五个问题，是这套方案在真机上最容易翻车的地方，每个都按现象、原因、解决三段写。提前知道这些，能省掉大量在 Chrome 模拟器上反复怀疑人生的时间。

5.1 笔迹整体偏移：CSS 尺寸与缓冲区尺寸不同步

现象：手指画在页面左上角，笔迹却出现在右下角，偏移量随屏幕尺寸变化。

原因：canvas 的绘图缓冲区尺寸由width/height属性决定，显示尺寸由 CSS 决定，两者不一致时，浏览器会把缓冲区拉伸到显示尺寸。触摸事件的坐标基于 CSS 像素，而绘制坐标基于缓冲区像素，中间少了一次换算，笔迹就整体错位。

解决：每次尺寸变化后统一走一个同步函数，先设置canvas.width = cssWidth * dpr，再设置canvas.style.width = cssWidth + 'px'，并且在绘制前用ctx.setTransform(dpr, 0, 0, dpr, 0, 0)把上下文对齐到逻辑像素。排查时在touchstart里打印clientX、getBoundingClientRect().left和canvas.width三个值，一眼就能看出是哪一步没对上。

5.2 iOS 上页面回弹、长按选中文字

现象：在批注层上划动时，整个页面跟着上下弹动，或者长按弹出文本选择菜单，笔迹画到一半被打断。

原因：移动端浏览器默认把触摸行为交给页面滚动和文本选择，touchmove没有阻止默认行为，或者阻止了但因为passive: true不生效。

解决：批注层容器上加touch-action: none，CSS 上同时加user-select: none和-webkit-touch-callout: none。事件监听统一用{ passive: false }，在touchmove里根据当前手势模式决定是否preventDefault()。注意不要全局阻止默认行为，否则页面就完全不能滚动了，只在批注层生效。

5.3 高 DPI 屏上笔迹发虚

现象：在 iPhone 或高分屏安卓机上，笔迹边缘模糊，看起来像被轻微放大过。

原因：canvas 缓冲区只按 CSS 尺寸创建，浏览器在显示时按 DPR 放大，相当于用低分辨率位图铺满高分辨率屏幕，边缘自然发虚。

解决：缓冲区尺寸乘以 DPR，上下文用setTransform缩放回去。DPR 要封顶，超过 3 之后收益递减，直接取Math.min(window.devicePixelRatio, 3)。如果同时对底图和批注层做 DPR 适配，注意两层的 DPR 取值要一致，否则笔迹和 PDF 的清晰度会不一致，视觉上很怪。

5.4 大体积 PDF 首屏渲染卡顿

现象：打开一份几十页的 PDF，首屏白屏两三秒，滚动时页面渲染明显滞后。

原因：一次性把所有页都交给 PDF.js 渲染，主线程被占满，移动端 JavaScript 引擎处理不过来。

解决：只渲染当前可见页和上下各一页，其余页面用占位容器撑开高度。滚动时用IntersectionObserver监听页面进入视口，进入后再触发渲染。渲染任务加一个队列，同一时刻只允许一个renderTask在跑，新任务进来先取消旧的。这套做法在几十页的文档上能把首屏时间压到一秒以内。

5.5 批注回显错位：坐标基准不统一

现象：同一份批注数据，在小屏手机上画完，换到大屏设备打开，笔迹位置整体偏移；或者缩放之后笔迹和 PDF 内容对不上。

原因：存储时用了某一时刻的像素坐标，回显时按新的视口尺寸直接绘制，两个基准不一致。另一种情况是存了归一化坐标，但回显时用了变换前的矩形尺寸。

解决：统一存归一化坐标，回显时只乘以当前viewport.width和viewport.height。排查时把归一化坐标、当前 viewport 尺寸、还原后的像素坐标三个值打出来，看哪一步乘错了。这类问题在开发阶段不容易发现，因为同一台设备上缩放前后差异小，必须换设备或改窗口大小才能复现。

提示：五个问题里有三个和坐标系有关。把坐标换算收敛到一个coords.js里，所有地方都调用同一套函数，能减少大半的偏移类 bug。

6. 验收与答辩：用一份可复现的检查清单收尾

功能写完不算交付，能通过一份别人也能复现的检查清单才算。答辩或验收时，评审最想看的不是“能画”，而是“边界情况处理得怎么样”。

6.1 验收清单：功能、性能、兼容性三条线

把检查项固定成表格，每次发版前逐条过一遍，比口头说“我测过了”有说服力得多。

表格里“回显一致性”这一项最好用两台真实设备测，模拟器改分辨率测不出归一化坐标的乘法错误。性能项的“首屏可交互时间”用performance.now()在页面挂载时打点，渲染完成时再打一次，差值就是结果，比肉眼估更准。

答辩演示时，我通常会把一个真实踩过的坑作为主线：先演示问题，再讲定位过程，最后展示修复前后的对比。评审对“发现问题、定位原因、验证修复”这个闭环的兴趣，远大于功能列表本身。演示顺序建议按“正常流程 → 边界操作 → 一个坑的排查过程”来排，控制在五分钟以内。

从那以后我每次接手 canvas 相关的移动端项目，都会在开发第一天先用一台 iPhone 和一台低端安卓把笔迹偏移检查跑一遍，再谈其他功能。地基歪了，上面盖得越漂亮返工越狠。希望这套结构能帮到你，少走几段我走过的弯路。

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