📌 在Web应用开发中，电子签名功能已成为合同签署、表单确认等场景的基础需求。vue-esign作为一款基于Vue.js的Canvas手写签名组件，以轻量化设计和跨端兼容性为核心优势，为开发者提供了开箱即用的手写签名解决方案。无论是金融服务的在线合同签署，还是各类系统的电子表单确认，vue-esign都能通过简洁的API集成，快速实现专业级签名体验。
项目地址: https://gitcode.com/gh_mirrors/vu/vue-esign 一、功能特性
1.1 跨设备兼容能力
- 全平台支持：无缝适配PC端鼠标操作与移动端触屏输入，无需额外适配代码
- 使用场景：企业内部审批系统中，员工可通过电脑或手机完成电子签章，提升流程效率
1.2 智能画布系统
- 自适应布局：画布尺寸随窗口缩放、屏幕旋转自动调整，实时校正签名坐标
- 使用场景：各类应用中，解决用户横屏签字时的坐标偏移问题，确保签名位置精准
1.3 个性化配置中心
- 自定义画笔参数：支持调整线条粗细（1-20px）、颜色（十六进制/RGB/RGBA格式）
- 背景色设置：可配置透明画布或自定义背景色，满足不同场景的导出需求
- 使用场景：在线教育平台的作业批改功能，教师可使用红色粗线条进行手写批注
1.4 专业图像处理
- 智能裁剪：自动去除签名图片四周空白区域，优化图片展示效果
- 多格式导出：支持PNG/JPEG/WEBP格式，可配置图片质量参数（0-1）
- 使用场景：各类合同系统中，导出高清PNG格式签名嵌入文件，确保法律有效性
二、技术亮点
2.1 双框架支持架构
- ✨ Vue 2/3双向兼容：同一组件包同时支持Vue 2和Vue 3项目，通过条件编译实现框架适配
- 技术实现：采用Vue 3的Composition API重构核心逻辑，同时保留Vue 2的Options API兼容层
2.2 性能优化策略
- Canvas离屏渲染：签名过程使用离屏Canvas进行绘制计算，避免频繁DOM操作
- 事件防抖处理：针对触屏设备的快速绘制场景，优化事件响应机制，降低性能损耗
2.3 灵活API设计
- 声明式配置：通过props传递配置项，支持v-model双向绑定背景色
- 命令式调用：提供reset()清空画布、generate()导出图片等实例方法
- 使用示例：
// 生成高质量JPEG图片
this.$refs.esign.generate({
format: 'image/jpeg',
quality: 0.9
}).then(base64 => {
this.signatureData = base64
})
三、使用指南
3.1 快速安装
# 最新稳定版
npm install vue-esign@latest --save
3.2 基础集成
// Vue 3全局注册
import { createApp } from 'vue'
import App from './App.vue'
import vueEsign from 'vue-esign'
createApp(App)
.use(vueEsign)
.mount('#app')
3.3 组件使用
<template>
<vue-esign
ref="esign"
:width="800"
:height="300"
:lineWidth="6"
:lineColor="#1E88E5"
v-model:bgColor="canvasBg"
:isCrop="true"
/>
<button @click="handleReset">清空</button>
<button @click="handleExport">导出</button>
</template>
<script setup>
import { ref } from 'vue'
const esign = ref(null)
const canvasBg = ref('#f5f5f5')
const handleReset = () => {
esign.value.reset()
}
const handleExport = async () => {
try {
const base64 = await esign.value.generate()
// 处理签名图片
} catch (err) {
alert('请先完成签名')
}
}
</script>
3.4 核心属性配置
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| width | Number | 800 | 导出图片宽度 |
| height | Number | 300 | 导出图片高度 |
| lineWidth | Number | 4 | 画笔粗细 |
| lineColor | String | #000000 | 画笔颜色 |
| isCrop | Boolean | false | 是否裁剪空白区域 |
| isClearBgColor | Boolean | true | 重置时是否清空背景色 |
四、版本更新时间线
-
2023-05：发布v2.0.0版本，全面支持Vue 3
- 新增
isClearBgColor属性，控制重置时是否保留背景色 - 重构
bgColor绑定方式，Vue 3中使用v-model:bgColor替代.sync修饰符
- 新增
-
2022-11：发布v1.4.0版本
- 新增WEBP图片格式支持
- 优化移动端触控响应速度
-
2021-03：发布v1.0.0稳定版
- 实现基础签名功能
- 支持PC/移动端适配
图：vue-esign组件在移动端的签名效果演示
五、常见问题
5.1 签名图片背景透明问题
Q：导出PNG格式时背景为什么是黑色？
A：当设置bgColor为空且导出PNG格式时，透明背景在某些预览环境下会显示为黑色。解决方案：显式设置bgColor: '#ffffff'
5.2 Vue 3中背景色绑定问题
Q：Vue 3项目中bgColor无法双向绑定？
A：Vue 3中需使用v-model:bgColor替代Vue 2的.sync修饰符，确保背景色变更能正确同步
5.3 签名验证机制
Q：如何判断用户是否真的进行了签名？
A：generate()方法在无有效签名时会reject并返回'Not Signned'，可通过try/catch捕获该异常进行提示
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
