简介这是一份面向移动端 H5 开发者的 Canvas 画板批注 PDF 预览实战资源适合需要在小程序、WebView 或移动浏览器中实现 PDF 阅读与手写批注功能的初中级前端工程师。资源围绕 PDF.js 解析渲染与 Canvas 触控绘图两条主线展开涵盖 PDF 文档加载、分页渲染、touchstart/touchmove/touchend 事件处理、线条绘制、文本与高亮批注、toDataURL 导出持久化等关键环节并涉及跨域获取文件与性能优化思路。压缩包共 150 个文件约 2.4MB包含 34 个 js 脚本、75 个 gif 演示、11 个 png 与 6 个 jpg 图示、10 个 css 样式及 4 个 html 页面另有字体、音频、pdf 样例与 json 配置等辅助文件目录结构清晰便于按模块查阅与二次开发。目前已有 1749 人学习下载可作为移动端 PDF 批注功能的完整参考实现。1. 移动端画板批注 PDF 预览为什么“能画”和“画得准”是两回事做过移动端 PDF 批注的人多半有过这种体验手指在屏幕上划了一条线松手后线跑偏了半个字或者 PDF 一放大之前标注的圈注全飘到了隔壁段落。这不是玄学是坐标系没对齐。标题里的“canvas 移动端画板批注 pdf 预览”拆开看是四件事用 canvas 做绘图引擎、在移动端跑、把画板叠加在 PDF 预览层上、批注数据要能存能还原。它解决的核心问题是——让用户在手机上看 PDF 时能像在纸上一样圈画写字并且这些笔迹和 PDF 页面严格绑定缩放、翻页、旋转都不丢。适合谁看正在做移动端文档协作、在线教育批改、合同签署、图纸审阅这类功能的工程师。如果你只是想在网页上放个 PDF 预览那用现成的预览组件就够了但一旦要加批注就必须自己接管 canvas 层。这篇笔记按“先立坐标系、再搭画板、最后存数据”的顺序讲中间会给出可直接抄的最小实现和几个我踩过的坑。2. 坐标系对齐PDF 渲染层和 canvas 画板怎么叠才不飘2.1 为什么不能直接拿屏幕坐标画线移动端 PDF 预览常见做法是用 pdf.js 把页面渲染到一个 canvas 上再在上面盖一个透明 canvas 专门收笔迹。问题出在PDF 页面有自己的尺寸比如 A4 是 595×842 pt渲染到屏幕时会被缩放和偏移。如果你直接把 touch 事件的 clientX/clientY 画到画板 canvas 上一旦用户双指放大笔迹就和 PDF 内容错位了。正确的做法是维护三层坐标屏幕坐标touch 事件给的、画板 canvas 坐标CSS 像素、PDF 页面坐标pt。批注数据最终要存成 PDF 页面坐标这样无论设备屏幕多大、缩放多少重新打开都能还原到正确位置。2.2 建立坐标转换的最小实现下面这段代码演示如何把一次触摸落点转成 PDF 页面坐标。假设你已经用 pdf.js 拿到了页面的 viewport。// pdfViewport: pdf.js 的 page.getViewport({ scale }) // canvasRect: 画板 canvas 的 getBoundingClientRect() function screenToPdfPoint(touch, canvasRect, pdfViewport) { // 第一步屏幕坐标 - 画板 canvas 坐标 const canvasX touch.clientX - canvasRect.left; const canvasY touch.clientY - canvasRect.top; // 第二步画板坐标 - PDF 页面坐标 // pdfViewport 的 scale 已经把 pt 映射到 CSS 像素 const pdfX canvasX / pdfViewport.scale; const pdfY canvasY / pdfViewport.scale; return { x: pdfX, y: pdfY }; }逻辑说明canvasRect 保证画板在页面中有偏移时也能算对pdfViewport.scale 是 pdf.js 渲染时用的缩放比它把 PDF 的 pt 单位转成了屏幕像素。参数上scale 必须和渲染 PDF 那一层用的 scale 完全一致否则会系统性偏移。我一般会把 viewport 对象缓存在页面状态里缩放时同步更新而不是每次重新计算。2.3 缩放和旋转时的同步策略移动端用户会双指缩放这时 PDF 渲染层和画板层必须同步变换。常见做法是两层用同一个 CSS transform或者监听缩放结束后重绘。我倾向于后者缩放过程中只做视觉变换缩放结束后按新的 viewport 重绘画板上的所有笔迹。这样避免高频重绘卡顿也保证最终位置准确。旋转同理。手机横竖屏切换时viewport 的 rotation 会变画板上的点要按旋转矩阵重新映射。这一步不做横屏后批注就会跑到页面外面。3. 画板引擎选型原生 canvas 还是现成库3.1 原生 canvas 手写 vs fabric.js vs 其他移动端画板批注选型主要看三件事包体积、触摸事件处理、笔迹平滑。原生 canvas 最轻但你要自己处理多点触控、笔迹插值、撤销重做。fabric.js 功能全但移动端包体积偏大而且它的对象模型对“纯笔迹批注”有点重。我一般会推荐如果只是画线、圈注、简单文字原生 canvas 加一个轻量的笔迹平滑算法就够了如果要支持拖拽图形、富文本标注再考虑 fabric.js 这类库。热词里提到的“canvas 绘图引擎”和“m3e canvas”本质上都是在问有没有现成的绘图抽象。我的经验是批注场景的绘图需求很窄自己封装一层比引入大库更可控。3.2 触摸事件到笔迹的最小闭环下面是一个最小可用的画板初始化代码处理单指绘制。const board document.getElementById(board); const ctx board.getContext(2d); let drawing false; let lastPoint null; // 按设备像素比设置 canvas 分辨率避免模糊 const dpr window.devicePixelRatio || 1; board.width board.clientWidth * dpr; board.height board.clientHeight * dpr; ctx.scale(dpr, dpr); board.addEventListener(touchstart, (e) { e.preventDefault(); drawing true; const t e.touches[0]; lastPoint { x: t.clientX, y: t.clientY }; }); board.addEventListener(touchmove, (e) { e.preventDefault(); if (!drawing) return; const t e.touches[0]; const current { x: t.clientX, y: t.clientY }; ctx.beginPath(); ctx.moveTo(lastPoint.x, lastPoint.y); ctx.lineTo(current.x, current.y); ctx.strokeStyle #e74c3c; ctx.lineWidth 2; ctx.lineCap round; ctx.stroke(); lastPoint current; }); board.addEventListener(touchend, () { drawing false; lastPoint null; });逻辑说明devicePixelRatio 处理是移动端 canvas 清晰度的关键不乘 dpr 画出来是糊的。touchmove 里用 lineTo 逐段画简单但够用。参数上lineWidth 和 strokeStyle 按业务定注意 lineCap 设成 round 让笔迹端点圆润。这段代码没做笔迹平滑快速划线会有折线感后面进阶部分会补。3.3 笔迹平滑为什么你的线看起来像锯齿移动端触摸采样率有限快速划线时点与点之间距离大直接 lineTo 会看到明显折角。常见做法是用二次贝塞尔曲线做插值取相邻三个点以前一点和中点作为控制点和终点画曲线。这样笔迹会顺滑很多代价是计算量略增。我一般会在 touchmove 里攒点每三个点画一段曲线而不是每来一个点就画直线。4. 批注数据怎么存从笔迹到可还原的 JSON4.1 存储结构设计批注要能存能还原数据结构必须包含页码、坐标数组PDF 页面坐标、样式颜色、线宽、类型笔迹/文字/高亮。下面是一个我常用的结构。{ page: 3, type: stroke, style: { color: #e74c3c, width: 2 }, points: [ { x: 120.5, y: 340.2 }, { x: 122.1, y: 342.8 } ] }逻辑说明points 存的是 PDF 页面坐标不是屏幕坐标这样换设备也能还原。page 从 1 开始和 pdf.js 的页码一致。style 独立出来方便统一改主题。4.2 还原时的重绘流程还原时遍历当前页的所有批注把 PDF 坐标转回画板坐标再画。转换就是 screenToPdfPoint 的逆运算canvasX pdfX * viewport.scale。注意重绘前要清空画板并且按批注创建顺序画保证层叠关系正确。4.3 撤销重做的实现要点撤销重做用两个栈undoStack 和 redoStack。每次完成一笔就 push 到 undoStack撤销时 pop 出来 push 到 redoStack 并重绘。重绘时只画 undoStack 里的批注。注意不要在 touchmove 过程中 push否则一笔会被拆成很多步。我一般会在 touchend 时把整笔作为一个操作入栈。5. 避坑与排查移动端批注最容易翻车的五个地方5.1 现象iOS Safari 上导出白图原因iOS Safari 对 canvas 尺寸有限制超过一定像素面积通常是 16777216 像素即 4096×4096后canvas 会变成空白。移动端 PDF 页面按高 dpr 渲染很容易超限。解决限制画板 canvas 的最大分辨率或者分块渲染。我一般会把 dpr 上限设为 2而不是直接用设备的 3。另外导出前检查 canvas.width * canvas.height 是否超限。5.2 现象笔迹和 PDF 内容错位缩放后更明显原因画板 canvas 的 CSS 尺寸和实际像素尺寸不一致或者 viewport.scale 用了旧值。解决确保 canvas.width clientWidth * dpr 且 ctx.scale(dpr, dpr)同时缩放结束后用最新 viewport 重绘所有批注。排查时可以在屏幕上画一个已知 PDF 坐标的点看它是否落在预期位置。5.3 现象touchmove 触发页面滚动画线断断续续原因没有阻止默认滚动行为。解决在 touchstart 和 touchmove 里调用 e.preventDefault()并且给画板容器加 CSS touch-action: none。注意 preventDefault 要加在 passive: false 的监听器上否则浏览器会忽略。5.4 现象快速划线时笔迹丢失中间点原因touchmove 事件在移动端会被合并或丢弃尤其在高频滑动时。解决用 getCoalescedEvents() 获取合并前的所有点。这个 API 在多数现代移动浏览器上可用能显著提升笔迹精度。5.5 现象批注保存后重新打开位置偏了半个屏幕原因保存时存了屏幕坐标或者还原时 viewport 的 scale 和保存时不一致。解决统一存 PDF 页面坐标还原时按当前 viewport 转换。排查时对比保存前后的 viewport.scale 和页面旋转角度。6. 进阶技巧用离屏 canvas 和压感模拟提升批注手感批注手感这件事用户不会说“你的贝塞尔插值有问题”但他们会觉得“不好用”。我后来固定了两个习惯一是用离屏 canvas 做笔迹预览二是用速度模拟压感。离屏 canvas 的思路是当前正在画的这一笔先画在离屏 canvas 上每帧合成到主画板。这样撤销时不用重绘所有历史笔迹只清掉离屏层就行。对于批注层数多的页面这个优化很明显。压感模拟更简单根据 touchmove 的速度动态调 lineWidth。速度快时线细速度慢时线粗模拟真实笔触。代码上就是在 touchmove 里算两点间距离和时间差映射到线宽范围。// 速度 - 线宽映射速度越快线越细 function speedToWidth(speed) { const minWidth 1; const maxWidth 4; const maxSpeed 2; // px/ms按实际手感调 const ratio Math.min(speed / maxSpeed, 1); return maxWidth - (maxWidth - minWidth) * ratio; }参数上maxSpeed 需要按设备调我一般在真机上试几轮。这个技巧不复杂但用户感知很明显。验证批注是否真的对齐我有个笨办法但很管用在 PDF 里找一个明显的文字块在它四个角各点一个点然后缩放、翻页、重新打开看这四个点是否还框住那个文字块。框不住就是坐标转换某一步错了。做移动端批注这几年我最大的教训是不要相信“先画上去再说”。坐标系没定好后面每加一个功能都要还债。先把 PDF 坐标存对再谈手感和性能。希望帮到你。本文还有配套的精品资源点击获取