手写签名组件封装：Canvas坐标换算与Pointer Events实战

1. 组件设计思路为什么要把手写签名做成一个独立封装先讲个背景。业务系统里总会碰到“请签名”的环节——合同签署、巡检确认、验收单、处方笺、维修工单这些场景不约而同地需要一个能“写”字的区域。Web 端最通用、最可靠的做法就是在 canvas 上监听指针轨迹并绘制笔迹。我最早在两个项目里各写了一份签名逻辑一个用 mouse 事件一个用 touch 事件结果不仅代码重复两台不同安卓机的表现还不一样有的笔迹断断续续有的画布偏移一截。说白了这是把“交互能力”硬编码进了业务页面业务代码越来越脏签名功能却越来越难维护。后来我把这个能力抽成了一个独立组件一个 SignaturePad.vue。props 控制外观emits 回传结果父组件只关心三个事情用户有没有签、签到哪一步了、拿到的是什么格式的图片。这就是封装独立组件的好处第一隔离复杂度业务页面不需要知道 canvas 怎么画第二统一交互标准所有项目里的签名体验一致第三后续可以单独升级、单独测试甚至发布成 npm 包别的项目直接引用不用重复造轮子。做需求拆解的时候我会先把“签名”这个动作翻译成一组明确的功能点用户可以在指定区域内自由书写支持鼠标、触摸板、手指、触控笔写错了可以一键清除重写签名完成后能导出为图片父组件拿到数据用于提交或回显组件外观可配置画布宽高、笔迹颜色、线条粗细、背景色在移动端不能因为手写触发页面滚动或浏览器手势在高分屏下图片不能模糊。这 6 条就是组件的基本需求。所有封装工作都围绕这 6 条展开不多做也不少做。实际开发中我最怕有人把“可能以后用得上”的功能一股脑塞进组件比如加个橡皮擦、加个背景模板、加个笔迹回放这些不是不能用而是它们会显著增加组件的维护成本和使用成本。独立组件的第一原则是“边界清晰”组件只解决签名这件事其他交给上层业务。技术选型上我没有直接引入 signature_pad 这类第三方库而是选择了原生 canvas Pointer Events 手写实现。原因有三个一是第三方库虽然省事但很多业务场景需要对画布做深度定制库的抽象反而成了限制二是手写实现能让你真正理解坐标换算、线条平滑这些底层逻辑出了问题自己就能修三是依赖越少组件被其他项目引用时越不容易发生版本冲突。当然如果你项目工期特别紧用 signature_pad 也没问题但看再多别人的代码不如自己写一遍这也是我坚持手写的原因。2. 核心实现解析Canvas 笔迹绘制与坐标换算签名组件的核心就是“把指针轨迹变成画布上的像素”。听起来简单实际写起来有几个关键点很容易踩坑。2.1 画布坐标为什么不能用 offsetX很多人写 canvas 签名第一步就会想监听 mousemove然后直接用 e.offsetX 和 e.offsetY 取坐标。这个写法在简单页面里能用但一旦 canvas 外面套了滚动容器、或者页面发生了缩放、或者 canvas 本身有 CSS 边框offsetX 和 offsetY 就会和实际绘图坐标对不上出现“笔迹画歪了”的现象。我习惯的做法是用 clientX / clientY 减去 canvas 左上角的视口坐标const rect canvas.getBoundingClientRect(); const x e.clientX - rect.left; const y e.clientY - rect.top;这样获取的是相对于画布内容的实际绘制坐标。getBoundingClientRect 返回的是元素在视口内的位置不受内边距和滚动的影响所以在绝大多数场景下都比 offsetX 可靠。这里还要注意如果 canvas 的 CSS 尺寸和逻辑尺寸不一致比如设置了 width: 100%但 canvas.width 是一个固定值坐标换算还需要乘以缩放系数这个问题我放在第 4 节专门讲。2.2 Pointer Events一套接口兼容鼠标和触摸传统做法是分别监听 mouse 和 touch 事件比如 touchstart 对应 mousedown然后还要处理 touchmove 和 mousemove 的映射关系。这么做的麻烦在于两个事件体系都有自己的一套坐标和属性代码里到处是分支判断而且不同浏览器对 touch 事件的处理细节还有差异。Pointer Events 是更现代的方案它把鼠标、触摸、触控笔统一成了指针事件监听 pointerdown、pointermove、pointerup 就够了。好处很明显代码只写一套逻辑同时默认支持了鼠标、手指和手写笔。一个重要的辅助方法是 setPointerCapture它可以把指针捕获到当前画布元素上当指针移出画布范围时move 和 up 事件依然会派发给画布不会丢笔画。canvas.addEventListener(pointerdown, (e) { canvas.setPointerCapture(e.pointerId); drawing true; // 记录起点 });另外移动端浏览器对手指滑动有默认行为——滚动页面。要阻止这个行为可以在 canvas 的 CSS 里加上 touch-action: none。这个属性能告诉浏览器这个元素上的触摸操作由我们自己处理不需要浏览器接管滚动和缩放。忘了这一行移动端画两笔页面就开始上下滑签名根本没法用。2.3 线条平滑直线连接与二次贝塞尔曲线最简单的绘制方式是在 pointermove 时把当前点和上一个点用 lineTo 连起来然后 stroke。这样画出来的线条有两个问题线段拼接处有明显的折角看起来像锯齿当指针移动速度很快、采样点很稀疏时线段转折特别生硬。要解决这个问题常见的方案是用二次贝塞尔曲线quadraticCurveTo做插值。思路是不再直接用原始采样点作为线段的端点而是用每个采样点和相邻点的中点来生成曲线控制点。具体来说我在 move 事件中维护一个点数组当累积到第 3 个点时计算前两个点的中点和当前两个点的中点然后以中间点为控制点、以第二个中点为终点绘制一段贝塞尔曲线。这样做出来的笔迹比直线连接平滑得多这也是很多签名库采用的标准做法。function drawSmoothSegment(ctx, p1, p2, p3) { const mid1 { x: (p1.x p2.x) / 2, y: (p1.y p2.y) / 2 }; const mid2 { x: (p2.x p3.x) / 2, y: (p2.y p3.y) / 2 }; ctx.moveTo(mid1.x, mid1.y); ctx.quadraticCurveTo(p2.x, p2.y, mid2.x, mid2.y); }这里用了一个很简单的数学事实两点的中点一定在两点之间用它来做曲线的起始点能保证曲线首尾连续不会出现跳变。生活里可以类比成“在纸上快速画线时手腕一带而过产生的那种圆滑的弧度”而不是拿尺子每两厘米划一段直线。2.4 高清屏适配devicePixelRatio 的理解如果直接把 canvas 的 CSS 尺寸设为组件宽度然后 canvas.width 也设为同样数值在普通屏幕上看着没问题但放到 Retina 屏或 2K、3K 手机上导出的图片就会模糊。原因在于屏幕物理像素和 CSS 像素之间有一个倍数关系也就是 devicePixelRatio。物理像素越多单位 CSS 像素需要渲染的物理点就越多。canvas 默认只按 CSS 像素来分配绘制缓冲区所以高分屏上压缩放大后容易发虚。解决办法是在初始化时按设备像素比放大 canvas 的绘图缓冲区再通过 scale 把坐标系恢复正常function setupCanvas(canvas, width, height) { const dpr window.devicePixelRatio || 1; canvas.width width * dpr; canvas.height height * dpr; canvas.style.width width px; canvas.style.height height px; const ctx canvas.getContext(2d); ctx.scale(dpr, dpr); return ctx; }这样一来绘图时还是以 CSS 像素为单位的坐标但最终渲染到屏幕时每一个 CSS 像素都有更多的物理像素来支撑签名导出后也会更清晰。注意每次执行 clearRect 之后scale 状态会保留不用重复调用但如果你重置了 canvas.widthscale 会被重置需要重新 setup。3. 实操过程完整组件代码与接入步骤有了上面的原理下面直接给出一个可用、能快速集成进 Vue 3 项目的独立组件。组件用组合式 API 编写核心逻辑都收敛在 setup 里。3.1 组件目录与基础结构项目里我习惯这样组织components/ SignaturePad/ SignaturePad.vue README.md组件本身只依赖 Vue不引入任何第三方库。下面是完整代码。template div classsignature-pad :style{ width, height } canvas refcanvasRef classsignature-pad__canvas pointerdownonPointerDown pointermoveonPointerMove pointeruponPointerUp pointercancelonPointerUp /canvas div v-ifshowToolbar classsignature-pad__toolbar button typebutton clickclear清除/button button typebutton clickconfirm :disabled!hasContent确认/button /div /div /template script setup import { ref, reactive, onMounted, onBeforeUnmount, computed } from vue; const props defineProps({ width: { type: [Number, String], default: 400 }, height: { type: [Number, String], default: 200 }, lineWidth: { type: Number, default: 3 }, penColor: { type: String, default: #000000 }, bgColor: { type: String, default: #ffffff }, showToolbar: { type: Boolean, default: true } }); const emit defineEmits([confirm, clear, update:modelValue]); const canvasRef ref(null); const ctx ref(null); const hasContent ref(false); const points reactive([]); let drawing false; let lastPoint null; onMounted(() { const canvas canvasRef.value; canvas.setPointerCapture canvas.setPointerCapture.bind(canvas); ctx.value setupCanvas(canvas, parseCssSize(props.width), parseCssSize(props.height)); fillBackground(ctx.value, props.bgColor, parseCssSize(props.width), parseCssSize(props.height)); }); function parseCssSize(value) { if (typeof value number) return value; return parseInt(value, 10) || 300; } function setupCanvas(canvas, width, height) { const dpr window.devicePixelRatio || 1; canvas.width width * dpr; canvas.height height * dpr; canvas.style.width width px; canvas.style.height height px; const context canvas.getContext(2d); context.scale(dpr, dpr); return context; } function fillBackground(context, color, width, height) { context.clearRect(0, 0, width, height); if (color color ! transparent) { context.fillStyle color; context.fillRect(0, 0, width, height); } else { context.clearRect(0, 0, width, height); } } function getPointerPosition(e) { const canvas canvasRef.value; const rect canvas.getBoundingClientRect(); return { x: e.clientX - rect.left, y: e.clientY - rect.top }; } function drawLineSegment(p1, p2) { const context ctx.value; context.lineWidth props.lineWidth; context.lineCap round; context.lineJoin round; context.strokeStyle props.penColor; context.beginPath(); context.moveTo(p1.x, p1.y); context.lineTo(p2.x, p2.y); context.stroke(); } function drawSmoothSegment(p1, p2, p3) { const context ctx.value; const mid1 { x: (p1.x p2.x) / 2, y: (p1.y p2.y) / 2 }; const mid2 { x: (p2.x p3.x) / 2, y: (p2.y p3.y) / 2 }; context.lineWidth props.lineWidth; context.lineCap round; context.lineJoin round; context.strokeStyle props.penColor; context.beginPath(); context.moveTo(mid1.x, mid1.y); context.quadraticCurveTo(p2.x, p2.y, mid2.x, mid2.y); context.stroke(); } function onPointerDown(e) { drawing true; points.length 0; const pos getPointerPosition(e); lastPoint pos; points.push(pos); canvasRef.value.setPointerCapture(e.pointerId); } function onPointerMove(e) { if (!drawing) return; const pos getPointerPosition(e); points.push(pos); if (points.length 2) { drawLineSegment(points[0], points[1]); emit(update:modelValue, toDataURL()); } else if (points.length 3) { drawSmoothSegment(points[points.length - 3], points[points.length - 2], pos); emit(update:modelValue, toDataURL()); } lastPoint pos; hasContent.value true; } function onPointerUp(e) { if (!drawing) return; drawing false; // 画最后一笔保证结尾闭合 if (lastPoint points.length 2) { drawLineSegment(lastPoint, lastPoint); } emit(update:modelValue, toDataURL()); } function clear() { const canvas canvasRef.value; const context ctx.value; const width parseCssSize(props.width); const height parseCssSize(props.height); fillBackground(context, props.bgColor, width, height); hasContent.value false; points.length 0; lastPoint null; emit(clear); emit(update:modelValue, ); } function toDataURL(type image/png, quality 1) { const canvas canvasRef.value; return canvas.toDataURL(type, quality); } function confirm() { if (!hasContent.value) return; emit(confirm, toDataURL()); } defineExpose({ clear, toDataURL, confirm }); /script style scoped .signature-pad { display: inline-block; border: 1px solid #d9d9d9; border-radius: 6px; overflow: hidden; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif; } .signature-pad__canvas { display: block; touch-action: none; cursor: crosshair; } .signature-pad__toolbar { display: flex; justify-content: flex-end; gap: 8px; padding: 8px 12px; background: #fafafa; border-top: 1px solid #f0f0f0; } .signature-pad__toolbar button { padding: 5px 14px; border: 1px solid #d9d9d9; border-radius: 4px; background: #fff; cursor: pointer; font-size: 13px; } .signature-pad__toolbar button:hover { border-color: #409eff; color: #409eff; } .signature-pad__toolbar button:disabled { opacity: 0.5; cursor: not-allowed; } /style这个组件有几点设计值得说明。第一toolbar 不是强制出现的通过 showToolbar 控制是否在组件内部渲染“清除/确认”按钮实际业务中很多页面有自己的底部操作按钮不需要组件再套一层按钮栏。第二confirm 只负责把 dataURL 交出去上传保存是父组件的事组件不关心网络请求。第三hasContent 的判断在业务校验里很有用父组件可以通过监听 clear 和 confirm 状态来重置表单字段。3.2 Props 参数说明参数名类型默认值说明widthNumber/String400画布宽度支持数字或带单位字符串heightNumber/String200画布高度lineWidthNumber3笔迹粗细单位 pxpenColorString#000000笔迹颜色bgColorString#ffffff背景色设置为 transparent 可导出透明背景图片showToolbarBooleantrue是否显示组件内置清除和确认按钮参数设计上我坚持“少而稳定”。像橡皮擦、定时自动清除这些业务相关的功能一概不放进去。如果一个需求真的需要那应该创建一个新的组件或者通过插槽扩展而不是无限堆 props。3.3 在业务页面中使用组件接入方式非常简单。局部注册直接用template div classcontract-page h3签署确认/h3 SignaturePad refsignatureRef :width360 :height180 :penColor#1a1a1a confirmhandleConfirm / /div /template script setup import { ref } from vue; import SignaturePad from /components/SignaturePad/SignaturePad.vue; const signatureRef ref(null); function handleConfirm(dataURL) { // dataURL 就是 base64 编码的 PNG 图片 // 可以直接提交给后端也可以转成 Blob 再走上传接口 const uploadData dataURLToBlob(dataURL); // ... 调用上传接口 } function dataURLToBlob(dataURL) { const arr dataURL.split(,); const mime arr[0].match(/:(.*?);/)[1]; const bstr atob(arr[1]); let n bstr.length; const u8arr new Uint8Array(n); while (n--) { u8arr[n] bstr.charCodeAt(n); } return new Blob([u8arr], { type: mime }); } /scriptdataURLToBlob 这个辅助函数在很多项目里都会用到。后端如果接受 base64 字符串倒还好说遇到只收 multipart 文件的上传接口就要先把 base64 转成 Blob 再包一层 FormData。这个转换过程里有个小细节注意处理 base64 字符串里的换行符某些浏览器导出的 dataURL 会自带换行用 atob 之前最好先 replace(/[\r\n]/g, )否则解码会报错。4. 常见问题与排查技巧实录写组件的时候觉得原理都懂了真正放到业务环境里跑一遍还是踩了不少坑。下面这几个问题是我在不同项目里真实遇到过的每个都值得记下来。4.1 签名图片模糊现象鼠标写出来的字在屏幕上看着正常导出 PNG 后放到文档里明显发虚尤其在手机屏幕上特别明显。原因没有做 devicePixelRatio 适配。canvas 的绘图缓冲区只有 CSS 像素那么大但高分屏在渲染时需要更多物理像素浏览器只能把低分辨率的缓冲区拉伸放大自然就模糊了。解决按第 2.4 节的方式初始化时把 canvas.width 和 canvas.height 乘以 dpr再用 ctx.scale(dpr, dpr) 把坐标系恢复为 CSS 像素导出的图片清晰度会有肉眼可见的提升。另外一个容易忽略的细节不要在看板上直接判断效果。组件写好后用手机浏览器打开页面实际签个字再拿到电脑上放大看看这样才能看出真实清晰度。4.2 移动端签名时页面跟着滚动现象在手机上用手指签名刚画两笔页面就开始上下滑动完全没法控制。原因浏览器默认把触摸滑动当成页面滚动手势canvas 收到了 pointermove 事件但浏览器同时也在滚动页面两者互相干扰。解决给 canvas 加上 touch-action: none。这个 CSS 属性告诉浏览器“这个元素的触摸动作由应用自己处理”浏览器就不会去执行默认的滚动行为。补充一点如果组件被放在弹窗Modal里使用还要注意弹窗自身是否支持滚动有的弹窗在 touchmove 时会触发底层页面滚动需要在弹窗层级也做一些处理。4.3 画布偏移签名位置不对现象鼠标按下后笔迹起点跟在指针的右下方或左上方明显偏了一段距离。原因通常是坐标换算用了 offsetX / offsetY但 canvas 的 CSS 尺寸和实际渲染尺寸不一致或者页面里有滚动容器导致 offset 坐标不准。解决统一使用 clientX - rect.left 的方式换算。我在 getPointerPosition 里获取了 canvas 的 getBoundingClientRect每次取坐标都重新计算避免缓存过期的 rect。这个方法不受内部 padding 影响也不会因为滚动位置改变而错位。4.4 手写签名识别率低这个热搜词我很感兴趣。先要说明一点签名组件本身不负责“识别”它负责“采集”。识别率低通常有两个层面。第一采集质量不够。比如图片分辨率低、笔迹太细、背景有杂色这些都会导致后续 OCR 或人工比对的困难。我建议在组件里把导出图片的尺寸做得足够大并且提供透明的背景选项这样后续无论做图像处理还是叠加到 PDF 上都有更多余地。第二书写区域太小。有些业务方把签名框压缩得很小用户在手机上一笔写完笔画挤成一团不管是肉眼还是机器都很难辨认。这里不是靠改组件代码能解决的需要产品层面给用户一个足够大的签名区域。我的经验是移动端签名框最小不要小于 320 × 180高度太低用户会很别扭。如果你接入了识别引擎建议在导出时统一 PNG 格式避免 JPEG 压缩带来的笔迹边缘噪点这里边有很实际的差异JPEG 的压缩噪声会把笔画的边界弄得毛糙识别引擎很容易把毛糙当成额外的笔画特征。4.5 组件在弹窗中使用遇到的问题弹窗场景是最容易出问题的。一个是弹窗打开时 canvas 还没有渲染完成onMounted 里拿不到正确的宽度另一个是弹窗打开后 canvas 的宽度计算成 0。解决方案很简单在 canvas 渲染完成后或者在弹窗动画结束后的 nextTick 里再初始化。我的写法是暴露一个 init 方法或者用 v-if 控制画布在弹窗动画结束后再渲染template el-dialog v-modelvisible openedonDialogOpened SignaturePad v-ifvisible refsignatureRef / /el-dialog /template script setup function onDialogOpened() { // 确保弹窗 DOM 和动画都完成后再初始化画布 nextTick(() { signatureRef.value?.reInit?.(); }); } /script组件的 reInit 方法就是在清除当前画布并重新执行 setupCanvas。弹窗、折叠面板这些容器里使用 canvas 类组件几乎都会遇到这个问题提前预判能省下不少排查时间。4.6 常见问题速查表现象原因解决办法图片模糊未适配 devicePixelRatiocanvas 尺寸乘以 dpr 并 scale移动端滚动浏览器默认手势touch-action: none笔迹偏移坐标换算用了 offsetXclientX - rect.left弹窗中画布空白初始化时机过早弹窗动画后 nextTick 再 init笔迹有折角直接用直线连接二次贝塞尔曲线插值导出截图缺少背景色bgColor 未绘制初始化时 fillRect 清空背景边缘被裁剪canvas 外有 border用 box-sizing 控制宽高计算5. 组件复用与发布从项目目录到通用组件库组件在项目里跑通之后接下来要考虑的是怎么让别人也能方便地用起来。这里有两种常见的交付方式。如果只是团队内部几个项目复用把组件放在公共组件库里通过 npm 私有仓库发布就可以。如果是想做成开源组件或者公司内部统一所有项目的前端基础设施那就要考虑按 npm 包的形式发布。5.1 本地公共组件目录这种方式最简单。你只需要在项目里建立一个 src/components 或 src/packages 目录把 SignaturePad 放进去然后统一导出。在 Vue 3 项目里全量注册和按需引入都可以// components/index.js import SignaturePad from ./SignaturePad/SignaturePad.vue; export default { install(app) { app.component(SignaturePad, SignaturePad); } }; export { SignaturePad };然后在 main.js 里import { createApp } from vue; import App from ./App.vue; import SignaturePad from ./components; createApp(App).use(SignaturePad).mount(#app);全量注册的好处是方便坏处是即使用户只用了其中两个组件打包时也可能会把所有组件包含进来。如果你的构建工具支持 tree-shaking最好用按需引入的方式哪个页面用到了就在页面里 import这个组件体积不大但遵循按需引入的原则会让打包产物更干净。5.2 打包成 npm 包要把这个组件发布成 npm 包用 Vite 的库模式打包最直接。在 vite.config.js 里配置import { defineConfig } from vite; import vue from vitejs/plugin-vue; export default defineConfig({ plugins: [vue()], build: { lib: { entry: components/index.js, name: SignaturePad, fileName: (format) signature-pad.${format}.js }, rollupOptions: { external: [vue], output: { globals: { vue: Vue } } } } });external: [vue] 表示打包时不要把 Vue 打进去而是由使用方提供。这么一个简单的组件打包产物通常只有几 KB但发布前记得写清楚 README把 props、emits、dev 环境的 Demo 都列出来。组件库的价值一半在代码另一半在使用文档里见过太多组件库因为文档缺失而无人敢用的例子。5.3 版本管理和维护心得每个组件在发布时建议遵循语义化版本大版本不兼容时升主版本号新增向后兼容的功能升次版本号修 bug 升补丁号。做签名组件这种基础能力最怕的是悄悄改行为导致接入方埋雷。比如我之前在一次升级里把导出图片格式从默认 PNG 改成了 JPEG结果已经有同事基于 PNG 透明背景来做后期合成升级后所有合成图都多了一个白底直接线上故障。这就是典型的需要升主版本号的行为变更。所以任何对接口行为有影响的改动都要升大版本哪怕只是换了一个默认值。5.4 扩展方向参考签名组件可以扩展的方向其实不少。比较常见的是支持压感某些手写笔会给出 pressure 值可以根据压力动态调整线宽提升真实感支持笔迹回放把每次 pointermove 的点位和事件记录成数组可以回放签名过程在司法类应用里有价值支持自定义背景比如合同里经常要“在此签名”的提示文字可以通过 slot 或者背景图片实现支持图片导出格式选择PNG、JPEG、SVG甚至转成 PDF 页面。这些扩展如果做都应该保持主组件的核心逻辑不变通过新 props 或新方法对外提供能力而不是一股脑全塞进原组件。6. 踩过几次坑之后的总结回到最早那个问题为什么要把手写签名从业务代码里抽出来封装成独立组件看起来只是一个“画线”的小功能但真正踩过轮子、兼容完各种设备之后你会发现坑全藏在细节里。坐标换算、高清屏适配、移动端手势、弹窗初始化时机每一个拿出来都可以是一场排查事故。把这些复杂度封装住业务侧只用 handleConfirm(dataURL) 就能拿到结果这件事本身就有价值。我个人实际使用中的体会是这类交互组件最容易被低估的环节是“坐标换算”和“不同输入设备的一致性”。你可以在 PC 上写得无比顺滑但不代表手机上也顺滑你在开发机上写得无比清晰不代表用户的 2K 屏上也清晰。封装的时候一定要预留好充分的调试手段比如暴露一个用于检查坐标的 debug 模式或者让导出图片的尺寸直接可配这些都能在线上问题出现时帮你快速定位。最后再分享一个在真实项目中很好用的小技巧导出图片时除了给父组件回传 dataURL还可以给后端额外传一个签名框的“像素宽高比”或者“画布在页面上的坐标信息”。某些业务场景需要把签名精确贴回到原始合同的图层位置上没有这些几何信息光靠一张图片很难对齐。一个签名组件做到这一步已经不只是“能写”的玩具而是真正能在生产环境扛事的基建了。