vue-esign 用途及使用教程

一、✍️ vue-esign 核心用途

vue-esign 是 Vue项目专属轻量级电子签名插件，不用依赖后端，纯前端就能实现手写签名、导出保存，体积小、易接入，解决前端手写签名的核心需求。

📌 常见使用场景（手绘重点标注）

📋 办公场景：电子合同签署、审批流程手写确认、报销单/表单签名（高频使用！）
📝 教育场景：在线作业手写答题、试卷批注、课堂笔记手绘、学生签名确认
✨ 通用场景：用户手写昵称、留言板手绘、实名认证手写、小程序签名

🌟 核心优点（手绘小亮点）

轻量无依赖，接入成本极低，不用额外装其他插件
兼容 Vue2、Vue3 双版本，适配绝大多数Vue项目
可自定义：笔迹粗细、笔迹颜色、画板背景（纯色/图片都可）
签名可导出为base64格式，方便传给后端保存或本地预览

二、📝 手把手使用教程（新手友好·一步一标）

⚠️ 前置小提醒

✅ Vue3 项目 → 安装 vue-esign@2.x 版本（推荐）

✅ Vue2 项目 → 安装 vue-esign@1.x 版本（别装错哦！）

✅ 无需额外依赖，安装完成直接使用，不用配置复杂环境

步骤1：安装依赖 📦（复制命令直接执行）

打开项目终端，根据自己的Vue版本，粘贴对应命令，回车安装即可：

bash 复制代码

# Vue3 项目（推荐，适配最新Vue版本）
npm install vue-esign --save

# Vue2 项目（指定1.x版本，避免兼容问题）
npm install vue-esign@1.0.10 --save

步骤2：引入插件 ✨（两种方式，选一种就好）

方式1：全局引入（项目通用，推荐！）

在main.js/ main.ts中引入，全局注册后，所有组件都能直接使用：

javascript 复制代码

// Vue3 项目（main.js / main.ts）
import { createApp } from 'vue'
import App from './App.vue'
import vueEsign from 'vue-esign'

const app = createApp(App)
app.use(vueEsign) // 全局注册签名组件
app.mount('#app')

javascript 复制代码

// Vue2 项目（main.js）
import Vue from 'vue'
import App from './App.vue'
import vueEsign from 'vue-esign'

Vue.use(vueEsign) // 全局注册签名组件
new Vue({
  el: '#app',
  render: h => h(App)
})

方式2：局部引入（仅单个组件使用，节省资源）

如果只有一个组件需要用签名，直接在该组件内引入即可：

vue 复制代码

<template&gt;
  <!-- 签名组件，直接使用 -->
  <vue-esign ref="esign" :width="800" :height="400" />
</template>

<script setup>
// Vue3 局部引入
import { ref } from 'vue'
import vueEsign from 'vue-esign'

const esign = ref(null) // 获取签名组件实例（必须！）
&lt;/script&gt;

<!-- Vue2 局部引入 -->
<script>
import vueEsign from 'vue-esign'
export default {
  components: {
    vueEsign // 局部注册组件
  },
  data() {
    return {
      esign: null // 获取签名组件实例
    }
  }
}
</script>

步骤3：基础使用示例 ✍️（复制即用，新手必看）

以下是Vue3完整可运行示例，包含「签名画板+清空+保存+预览」，粘贴到组件中就能直接测试：

vue 复制代码

<template>
  <div class="esign-container" style="padding: 20px;">
    <!-- 签名画板（核心组件） -->
    <vue-esign
      ref="esign"
      :width="800"       <!-- 画板宽度（px），可自定义 -->
      :height="400"      <!-- 画板高度（px），可自定义 -->
      :lineWidth="6"     <!-- 笔迹宽度，越大数据越粗 -->
      :lineColor="#000"  <!-- 笔迹颜色，支持十六进制（如#ff6600） -->
      :bgColor="#f5f5f5" <!-- 画板背景色，浅灰色更显笔迹 -->
      style="border: 1px solid #ddd; border-radius: 8px;"
    />

    <!-- 操作按钮（清空+保存） -->
    <div style="margin-top: 20px;">
      <button @click="handleReset" style="margin-right: 10px; padding: 8px 16px; cursor: pointer;">🗑️ 清空签名</button>
      <button @click="handleSave" style="padding: 8px 16px; background: #409eff; color: #fff; border: none; border-radius: 4px; cursor: pointer;">💾 保存签名</button>
    </div>

    <!-- 签名预览（保存后显示） -->
    <div v-if="signImg" style="margin-top: 20px;">
      <h4>📸 签名预览：</h4>
      <img :src="signImg" alt="签名图片" style="max-width: 800px; border: 1px solid #eee;">
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

// 签名组件实例（必须通过ref获取，才能调用内置方法）
const esign = ref(null)
// 保存的签名图片（base64格式，可用于预览、上传）
const signImg = ref('')

// 清空签名（调用插件内置reset方法）
const handleReset = () => {
  esign.value.reset() // 清空画板
  signImg.value = '' // 清空预览图
}

// 保存签名（转为base64格式）
const handleSave = async () => {
  try {
    // 调用插件内置generate方法，生成base64图片
    const base64 = await esign.value.generate()
    if (!base64) {
      alert('✍️ 请先完成签名再保存哦！')
      return
    }
    signImg.value = base64 // 显示预览图
    // 后续可将base64传给后端保存，或转为文件上传
    console.log('签名base64：', base64)
  } catch (error) {
    console.error('保存签名失败：', error)
    alert('保存签名失败，请重试！')
  }
}
</script>

步骤4：自定义配置项 ⚙️（按需调整，手绘表格）

根据项目需求，自定义画板样式，所有配置项整理如下（直接复制使用）：

配置项	类型	默认值	手绘说明（重点）
width	Number	800	画板宽度（单位px，不可写百分比）
height	Number	400	画板高度（单位px，按需调整）
lineWidth	Number	4	笔迹宽度，数值越大越粗（推荐5-8）
lineColor	String	#000000	笔迹颜色，支持十六进制（如#ff0000红色）
bgColor	String	#ffffff	画板背景色，纯色即可（推荐#f5f5f5浅灰）
bgImg	String	''	画板背景图片（url地址，注意跨域问题）
disabled	Boolean	false	是否禁用签名（true=禁用，false=可签名）

自定义示例（带背景图的签名板）

vue 复制代码

<vue-esign
  ref="esign"
  :width="800"
  :height="400"
  :lineWidth="8"       <!-- 粗笔迹 -->
  :lineColor="#ff6600" <!-- 橙色笔迹，更醒目 -->
  bgImg="https://xxx.com/sign-bg.png" <!-- 自定义背景图URL -->
/>

步骤5：常见问题 & 注意事项 ⚠️（手绘避坑指南）

📱 移动端适配：画板宽度别写固定值，用屏幕宽度计算，避免溢出// Vue3 适配移动端（获取屏幕宽度，减去边距） const width = ref(document.documentElement.clientWidth - 40)
📦 base64体积过大：生成的签名base64可能偏长，可安装image-conversion库压缩后再上传后端 npm install image-conversion --save
✍️ 签名为空提示：调用generate()时，如果没签名，会返回false，需先判断再保存（示例中已包含）
🌐 跨域问题：bgImg（背景图）需确保支持跨域，否则会报错，优先用本地图片
🔍 版本兼容：Vue2和Vue3版本不能混装，装错会导致组件无法显示，严格按照步骤1安装

三、📌 核心方法速查（手绘小卡片）

插件只有2个核心方法，记牢就能满足99%的需求，不用记复杂语法：

方法名	手绘说明	使用方式（必记）
reset()	清空当前签名，重置画板	esign.value.reset()
generate()	生成签名base64图片（异步）	await esign.value.generate()

四、💾 MD文档保存方法（手绘步骤）

复制本文档全部内容，按照以下步骤保存，即可下载使用：

新建一个文本文档（.txt），打开后粘贴全部内容
重命名文件，将后缀从「.txt」改为「.md」（例：vue-esign手绘笔记.md）
双击文件，用Markdown编辑器（Typora、VS Code等）打开，即可查看/编辑

五、✍️ 笔记总结（手绘重点）

vue-esign 是Vue专属轻量级电子签名插件，纯前端实现，无依赖、易接入；
核心流程：安装依赖 → 全局/局部引入 → 配置画板 → 调用方法（保存/清空）；
关键注意：版本别装错、移动端适配、签名为空判断，避开这3个坑就能顺利使用。