signature_pad 签名图片压缩避坑全解

signature_pad 签名图片压缩避坑全解

【免费下载链接】signature_padHTML5 canvas based smooth signature drawing项目地址: https://gitcode.com/gh_mirrors/si/signature_pad

上线第一个月，订单系统里用户提交的签名图片平均 200KB，CDN 带宽账单随之翻倍。问题不在用户，而在导出环节：signature_pad 默认导出全分辨率 PNG，远超列表页展示所需，格式与体积一直没有纳入设计。把 toDataURL 的机制弄清楚，签名图片压缩到原来的几分之一并不靠玄学，而是几个明确的参数。

底层机制：toDataURL 导出签名图片时做了什么

要理解体积差异，得先看 toDataURL 在 src/signature_pad.ts 里的两条分支。

第一条分支处理位图格式（PNG、JPEG）。此时库只是把调用转发给原生的 canvas.toDataURL(type, quality)，导出的是一张画布截图。位图按像素存数据，文件体积主要由 canvas.width × canvas.height 决定，内容越复杂，PNG 这种无损格式要付出的字节就越多。JPEG 是有损格式，quality 参数（0~1）在这里才真正生效，控制的是压缩时丢弃多少信息。

第二条分支处理 SVG。它不截图，而是遍历库内部保存的点组数据，把每一笔转成 path、circle 或 line 节点，再整体 base64 编码返回。也就是说，SVG 的体积由"签了多少笔"决定，跟画布分辨率无关——这也是它通常最小、且放大不糊的原因。

这里还藏着一个不显眼的坑：fromDataURL 只是把一张位图画回画布，不会重建内部点数据。之后再调 toSVG，这部分内容是进不了矢量输出的，除非用 includeDataUrl 把原图作为 image 节点嵌回去。

🧭 格式选型：按业务场景给签名图片选对格式

格式选择的本质是在透明、保真、分辨率三者之间做取舍：位图体积由像素总数决定，压得动的是分辨率，压不动的是单像素保真度；SVG 体积由笔画数据决定，适合要求清晰、但不必还原像素的场景。选格式前先问三个问题：这张图以后会被放大吗、要叠在透明背景上吗、会被打印吗。答案不同，表里就只剩一个正确答案。

⚙️ 参数调优：quality 取值与常见陷阱

问题：为什么 toDataURL("image/png", 0.3) 跟默认导出差不多大？原因不复杂：PNG 是无损格式，浏览器编码时直接忽略 quality，这个参数只对 JPEG 这类有损格式生效。正确做法是想明白 PNG 想变小只能少给像素——导出前调小画布尺寸，或者干脆别按 devicePixelRatio 放大画布。

问题：JPEG 导出来背景发黑？原因：画布默认透明底，而 JPEG 没有 alpha 通道，canvas.toDataURL 导出时会把透明区域合成到黑色底上。正确做法是初始化时把 backgroundColor 设成不透明色，docs/js/app.js 的示例正是这么做的，这个值同时用于 clear() 时重绘画布背景：

const pad = new SignaturePad(canvas, { backgroundColor: 'rgb(255, 255, 255)', // 导出 JPEG 前必须是不透明色 }); pad.toDataURL('image/jpeg', 0.7); // quality 只对 JPEG 生效

问题：SVG 到底要不要带背景？includeBackgroundColor 默认是 false，导出的是透明底矢量；打印、贴进白底文档时才需要显式打开。includeDataUrl 同理，它只嵌入 fromDataURL 传入的那张位图，纯手写场景用不上：

// 日常存档：透明底、无嵌入图 pad.toDataURL('image/svg+xml'); // 打印版：补上背景色 pad.toDataURL('image/svg+xml', { includeBackgroundColor: true });

问题：为什么同一支签名，在 Retina 手机上导出的 PNG 大了一圈？原因：docs/js/app.js 的 resizeCanvas() 会把画布宽高乘以 devicePixelRatio 保证显示清晰，而位图体积随像素数平方增长——ratio 为 3 时像素就是 9 倍。正确做法：业务不需要印刷级保真时，把 ratio 上限设成 1 或 2，或者导出时单独用小画布重绘。

📦 落地路径：从 Demo 示例到生产业务

第一步，把仓库拉下来跑通示例：

git clone https://gitcode.com/gh_mirrors/si/signature_pad cd signature_pad yarn install && yarn start

yarn start 会先构建产物，再把 docs/ 目录挂在 9000 端口，脚本定义见 package.json。

第二步，打开浏览器里的 demo 页面 docs/index.html。四个 Save 按钮对应 docs/js/app.js 里的三段导出调用。用同一段签名把三种格式各存一次，对比体积和观感，比读文档直观。

第三步，确定导出参数。所有导出都收敛到 src/signature_pad.ts 的 toDataURL：SVG 分支收一个对象，位图分支收一个数字。同时重点看 app.js 里 resizeCanvas() 的分辨率策略，那是体积的总开关。

第四步，接入自己业务。npm 安装 signature_pad 后导入 ESM 产物，按上一节的选型表初始化参数，导出前用 isEmpty() 挡掉空画布。落库环节建议把 base64 解码成文件再存，README.md 里有服务端的解码示例，避免把一长串 data URL 直接塞进 HTML。

回到开头那张 200KB 的账单，格式选对、像素管住，同一支签名就能落到十几 KB 量级。接下来值得花十分钟验证一次：打开 docs 示例，用同一段签名把 PNG、JPEG、SVG 各导一份，记下三个文件大小，再回头调 toDataURL 的参数，哪个参数在你的场景里最值钱，测一轮就清楚了。

【免费下载链接】signature_padHTML5 canvas based smooth signature drawing项目地址: https://gitcode.com/gh_mirrors/si/signature_pad