夜雨聆风学习资料网

ARTICLE · 1383841

uni-app 手写签名实战:横竖屏双支持,兼容 H5 与小程序(附完整代码)

uni-app 手写签名实战:横竖屏双支持,兼容 H5 与小程序(附完整代码)

uni-app 手写签名怎么做?微信小程序 / H5 电子签名、Canvas 描红、横屏整签与竖屏逐字,这篇用实际组件代码一次讲清。

产品经理说:把用户名字用灰色字铺在底上,让用户照着描一遍。心想,不就是 Canvas 画字再画线吗。

真做完才发现:灰色底字被黑色笔迹盖得严严实实,手指越往右下笔迹偏得越多,导出的签名图背景莫名其妙是白的。

下面把这三个坑连同两种模式的适配写法拆开,两种模式共用一套笔迹引擎、条件编译隔离两端,复制过去改个姓名就能跑。❄️

01

灰字为什么总被盖住:图层不是两个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分开处理。

横竖屏切换、窗口缩放时,已写笔迹会按新旧画布的宽高比例整体缩放,不会错位或丢笔。

02

笔迹为什么总偏一点:横屏旋转后的坐标映射

uni-app手写签名在H5横屏,是用CSS把整个页面旋转90°实现的(服务号浏览器锁不了横屏)。

页面一转,屏幕坐标和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像素映射即可。手动再除一遍反而会偏第二次。真正要校准的是上面那层旋转关系,不是像素比。

03

导出白底还是透明底:看业务,不是看心情

canvasToTempFilePath导出的背景,取决于Canvas有没有填背景色。

我的组件导出时统一fillRect铺纸色(默认白),因为底字已经被分离出去,导出图天然干净。

怎么选:签名要合成到合同/PDF上,用透明底(导出时别fillRect),否则白底会盖住合同背景。签名直接展示在白色页面上,白底更稳妥。

无论哪种,灰色底字都不能进导出图。它是“照着签”的引导,不是签名本身。小程序端导出前那次render(false)重绘,就是为了把底字抹掉只留轨迹。

04

竖屏逐字:米字格 + 拼接成一张图

整签适合名字短、追求一气呵成。名字长或想写工整,竖屏逐字更稳。

每个字一个米字格正方形画布,charStrokes数组分别存各字笔迹,上一字/下一字随时回看修改,进度条标记已完成的字。

全部写完,把各字导出的正方形图按顺序横向拼接:H5用离屏canvas加载各字图drawImage横排再toDataURL;小程序用一个隐藏的拼接canvas加canvasToTempFilePath。三个字拼出来就是3:1的横排白底签名图,和整签导出格式一致。

点“完成签名”时组件会先校验每个字都有笔迹,缺字就自动跳到第一个没写的字并提示,不会导出缺字的半成品。确认事件回传{ name, path, time, mode: 'char' },入口页拿path直接展示,和整签结果走同一套回传逻辑。

两种模式共用一个笔迹引擎mixin,宿主组件只需提供guideText(描红文字)和rotated(是否旋转)两个computed,笔锋、平滑、触点逻辑全部复用。

05

上线前必查的三个细节

1、清空残影
每次清空必须clearRect(0, 0, width, height)覆盖全画布,只靠beginPath会留残影。

2、笔锋断点

lineCap和lineJoin都设round,按书写速度动态调粗细、midpoint二次曲线平滑,笔迹才圆润不断线。

3、触点节流

onTouchMove里两点距离小于0.75像素直接跳过,低性能机型才不会卡顿堆积。

💡 总结:

uni-app手写签名的核心不是画线,而是管理图层、坐标和背景。

透明Canvas叠DOM底字治遮挡,横屏重映射触点治偏移,导出铺白底、底字分离治脏图。

横屏整签与竖屏逐字共用笔迹引擎,条件编译隔离两端,一套组件即可上线。

三个坑,每一个都不在“Canvas怎么画线”的范畴里。它们都在“Canvas之外”,图层怎么叠、坐标怎么转、背景什么时候铺。

手写签名这件事,画线是最简单的那一步。真正花时间的,是让那条线落在对的位置、透出对的底、导出对的图。

完整横竖屏签名组件源码(包含 H5 和小程序兼容处理),关注后回复【签名】。

你的签名项目用单Canvas还是双Canvas?导出遇到过背景变白、底字被一起导出吗?评论区聊聊。

📖 推荐阅读

不装库!Vue3 Canvas 手写电子印章,圆章椭圆章全搞定(附完整代码)

uni-app扫普通二维码进小程序:微信文档没写的3个坑(附完整代码)

uni-app 扫不出码?uni.scanCode 的 3 个“静默失败”

------ END ------

小鹿

2026.11.19

❄️ 持续分享 ❄️
*深耕技术|持续迭代|温柔前行*
#uni-app #手写签名 #Canvas #电子签名

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料