ARTICLE · 1383841
uni-app 手写签名实战:横竖屏双支持,兼容 H5 与小程序(附完整代码)
uni-app 手写签名怎么做?微信小程序 / H5 电子签名、Canvas 描红、横屏整签与竖屏逐字,这篇用实际组件代码一次讲清。
产品经理说:把用户名字用灰色字铺在底上,让用户照着描一遍。心想,不就是 Canvas 画字再画线吗。
真做完才发现:灰色底字被黑色笔迹盖得严严实实,手指越往右下笔迹偏得越多,导出的签名图背景莫名其妙是白的。
下面把这三个坑连同两种模式的适配写法拆开,两种模式共用一套笔迹引擎、条件编译隔离两端,复制过去改个姓名就能跑。❄️
灰字为什么总被盖住:图层不是两个Canvas
能做,但清空重写时得记得重绘底字,很容易漏。
我实际用的是更省心的方案:屏显Canvas保持透明,灰色底字在H5端做成一个DOM覆盖层。
关键是层级和重绘顺序。底字DOM设pointer-events:none、z-index:1,只负责显示不接事件。Canvas设z-index:2叠在底字之上,平时用clearRect保持透明,灰字从透明处透出来,不透明的墨迹自然盖住灰字。只有导出那一刻才fillRect铺白底。
小程序端没有DOM覆盖层,底字用drawGuide画进Canvas,导出前render(false)重绘一遍去掉底字。一套逻辑,用条件编译#ifdef H5分开处理。
横竖屏切换、窗口缩放时,已写笔迹会按新旧画布的宽高比例整体缩放,不会错位或丢笔。
笔迹为什么总偏一点:横屏旋转后的坐标映射
页面一转,屏幕坐标和Canvas坐标就不再是一回事:
mapPoint(clientX, clientY) {const r = this._canvasEl.getBoundingClientRect()return { x: clientY - r.top, y: r.right - clientX }}
屏幕Y轴对应画布X轴,屏幕X轴自右向左对应画布Y轴。竖屏逐字模式不旋转,直接clientX - r.left、clientY - r.top即可。
还有个更隐蔽的坑:事件必须绑在uni-canvas宿主上(getElementById拿到的外层),不能绑内部那个<canvas>。
uni-h5在内部canvas之上还盖了一层全覆盖的overlay div和ResizeSensor,真实触点落在覆盖层、冒泡到宿主,绑内部canvas根本收不到。这就是“明明绑了事件却写不了字”的真凶。
顺带纠正一个常被写错的点:不用自己除以pixelRatio。uni-h5的Canvas上下文内部已按设备像素比做了缩放,触点按CSS像素映射即可。手动再除一遍反而会偏第二次。真正要校准的是上面那层旋转关系,不是像素比。

导出白底还是透明底:看业务,不是看心情
我的组件导出时统一fillRect铺纸色(默认白),因为底字已经被分离出去,导出图天然干净。
怎么选:签名要合成到合同/PDF上,用透明底(导出时别fillRect),否则白底会盖住合同背景。签名直接展示在白色页面上,白底更稳妥。
无论哪种,灰色底字都不能进导出图。它是“照着签”的引导,不是签名本身。小程序端导出前那次render(false)重绘,就是为了把底字抹掉只留轨迹。
竖屏逐字:米字格 + 拼接成一张图
每个字一个米字格正方形画布,charStrokes数组分别存各字笔迹,上一字/下一字随时回看修改,进度条标记已完成的字。
全部写完,把各字导出的正方形图按顺序横向拼接:H5用离屏canvas加载各字图drawImage横排再toDataURL;小程序用一个隐藏的拼接canvas加canvasToTempFilePath。三个字拼出来就是3:1的横排白底签名图,和整签导出格式一致。
点“完成签名”时组件会先校验每个字都有笔迹,缺字就自动跳到第一个没写的字并提示,不会导出缺字的半成品。确认事件回传{ name, path, time, mode: 'char' },入口页拿path直接展示,和整签结果走同一套回传逻辑。
两种模式共用一个笔迹引擎mixin,宿主组件只需提供guideText(描红文字)和rotated(是否旋转)两个computed,笔锋、平滑、触点逻辑全部复用。

上线前必查的三个细节
2、笔锋断点
lineCap和lineJoin都设round,按书写速度动态调粗细、midpoint二次曲线平滑,笔迹才圆润不断线。
3、触点节流
onTouchMove里两点距离小于0.75像素直接跳过,低性能机型才不会卡顿堆积。
💡 总结:
uni-app手写签名的核心不是画线,而是管理图层、坐标和背景。
透明Canvas叠DOM底字治遮挡,横屏重映射触点治偏移,导出铺白底、底字分离治脏图。
横屏整签与竖屏逐字共用笔迹引擎,条件编译隔离两端,一套组件即可上线。
三个坑,每一个都不在“Canvas怎么画线”的范畴里。它们都在“Canvas之外”,图层怎么叠、坐标怎么转、背景什么时候铺。
手写签名这件事,画线是最简单的那一步。真正花时间的,是让那条线落在对的位置、透出对的底、导出对的图。
完整横竖屏签名组件源码(包含 H5 和小程序兼容处理),关注后回复【签名】。
你的签名项目用单Canvas还是双Canvas?导出遇到过背景变白、底字被一起导出吗?评论区聊聊。
不装库!Vue3 Canvas 手写电子印章,圆章椭圆章全搞定(附完整代码)
小鹿
2026.11.19














































































