sxz-e-signature

一个用于电子签名 / 手写签名的 Vue 组件。

1. 当前兼容性结论

• 目前实际构建出来的 npm 包只兼容：Vue 3 项目
• 不兼容 Vue 2 项目（即便 package.json 里的 peerDependencies 写了 >=2.6.0 || >=3.0.0）

为什么不兼容 Vue 2？

• 构建后的文件 dist/e-signature.es.js 和 dist/e-signature.umd.js 中：
  • 直接从 vue 中使用了 defineComponent、ref、onMounted 等 Vue 3 的 API
  • UMD 版本也依赖全局的 Vue 对象里提供这些 Vue 3 API
• Vue 2 的运行时里 没有这些 API，所以在 Vue 2 项目中引用时会报错，无法正常工作。

结论：当前发布的这个 npm 包只能在 Vue 3 项目中使用，不能直接在 Vue 2 项目中使用。

后续如果要支持 Vue 2，需要：

• 要么单独做一份 Vue 2 版本的组件并发布；
• 要么使用 vue-demi + 专门的打包配置，为 Vue 2 和 Vue 3 各产出一份不同的构建产物。

如果你希望，我可以根据你的 Vue 2 项目结构，帮你出一份「专门给 Vue 2 用的签名组件」代码，把它直接拷贝到你的项目里使用。

2. 在 Vue 3 项目中的使用方式

2.1 安装

npm install sxz-e-signature

确保你的项目是 Vue 3 项目（例如使用 Vite + Vue 3）。

2.2 全局注册（推荐）

// main.js
import { createApp } from 'vue'
import App from './App.vue'

import ElectronicSign from 'sxz-e-signature'
import 'sxz-e-signature/dist/style.css'

const app = createApp(App)

// 因为当前包默认导出的是组件本身，需要手动注册一个全局组件名
app.component('ElectronicSign', ElectronicSign)

app.mount('#app')

然后在任意组件中直接使用：

<template>
  <ElectronicSign @export="handleExport" />
</template>

<script>
export default {
  methods: {
    handleExport(dataUrl) {
      // dataUrl 是 base64 的 png 图片
      console.log('签名图片地址：', dataUrl)
    }
  }
}
</script>

2.3 局部注册

<script>
import ElectronicSign from 'sxz-e-signature'
import 'sxz-e-signature/dist/style.css'

export default {
  components: { ElectronicSign },
  // ...
}
</script>

2.4 在 Vue 2 项目中使用

1. 安装依赖（版本 ≥ 1.1.7 才包含源码目录）

   npm install sxz-e-signature vue@^2.6.0 vue-demi @vue/composition-api

   • vue@^2.6.0：确保主项目使用 2.6+ 版本。
   • @vue/composition-api：给 Vue2 提供 Composition API。
   • vue-demi：桥接层，确保组件能同时调用 Vue2 / Vue3 API。

2. 在入口文件中挂载插件

   // main.js
   import Vue from 'vue'
   import App from './App.vue'
   
   import VueCompositionApi from '@vue/composition-api'
   import ElectronicSignPlugin from 'sxz-e-signature'
   import 'sxz-e-signature/dist/sxz-e-signature.css'
   
   Vue.use(VueCompositionApi)          // 先安装 composition-api
   Vue.use(ElectronicSignPlugin)       // 再安装签名插件
   
   new Vue({
     render: (h) => h(App)
   }).$mount('#app')

3. 在组件内使用

   <template>
     <ElectronicSign @export="handleExport" />
   </template>
   
   <script>
   export default {
     methods: {
       handleExport (dataUrl) {
         console.log('签名图片：', dataUrl)
       }
     }
   }
   </script>

4. 可选：按需局部注册

   import { ElectronicSign } from 'sxz-e-signature/src'
   
   export default {
     components: { ElectronicSign }
   }

5. uni-app + Vue2 项目特殊配置

   如果你使用的是 HBuilderX 的 uni-app + Vue2 项目，需要解决 vue-demi 的路径问题。有以下几种方案：

   方案一：创建 vue.config.js（如果 uni-app 支持）

   在项目根目录创建 vue.config.js 文件：

   // vue.config.js
   module.exports = {
     configureWebpack: {
       resolve: {
         alias: {
           '@vue/composition-api/dist/vue-composition-api.mjs':
             '@vue/composition-api/dist/vue-composition-api.esm.js'
         }
       }
     },
     chainWebpack: (config) => {
       config.resolve.alias.set(
         '@vue/composition-api/dist/vue-composition-api.mjs',
         '@vue/composition-api/dist/vue-composition-api.esm.js'
       )
     }
   }

   方案二：升级 @vue/composition-api（推荐）

   最简单的方法是升级到支持 .mjs 的版本：

   npm install @vue/composition-api@latest

   方案三：使用 patch-package（如果方案一、二都不行）

   1. 安装 patch-package：

   npm install patch-package --save-dev

   2. 手动修改 node_modules/vue-demi/lib/index.mjs，将 .mjs 改为 .esm.js

   3. 生成补丁：

   npx patch-package vue-demi

   4. 在 package.json 的 scripts 中添加：

   {
     "scripts": {
       "postinstall": "patch-package"
     }
   }

   样式文件路径修正：

   从 1.1.8 版本开始，样式文件路径已修正为：

   import 'sxz-e-signature/dist/sxz-e-signature.css'

6. 注意事项

• 如果你的 Vue 2 项目没有自定义 webpack 配置，可以直接把仓库根目录的 webpack.config.js 复制过去使用。该配置已经内置：
  • @vue/composition-api/dist/vue-composition-api.mjs -> ...esm.js 的 alias；
  • .vue、.js、.css 的常用 loader；
  • dev server 与 @ 别名等基础设置。
  • [email protected]+ 已经把 src/ 和 dist/style.css 一起发布，确保升级后再安装；
  • vue-demi 的安装命令会自动根据你的 Vue 版本选择正确模式；
  • 如果你的项目里已经安装 @vue/composition-api，只需要确认版本在 ^1.7.2 即可；
  • 如果你是老的多页系统，也可以直接通过 <script src=".../dist/e-signature.umd.js"></script> 引入，然后执行 Vue.use(ElectronicSignPlugin)。

3. 组件 API 说明

3.1 Props

• strokeColor：画笔颜色
  • 类型：String
  • 默认值：'#000000'
• strokeWidth：画笔粗细
  • 类型：Number
  • 默认值：2

3.2 事件

• export
  • 触发时机：点击「确定」按钮时
  • 回调参数：dataUrl: string，一个 image/png 的 base64 图片地址

示例：

<ElectronicSign
  stroke-color="#ff0000"
  :stroke-width="3"
  @export="onExport"
/>

methods: {
  onExport(dataUrl) {
    // 可以上传到服务器，或者直接展示/下载
  }
}

4. 后续计划 & 说明

• 当前状态

  • 代码仓库中组件写法理论上可以配合 vue-demi 做到 Vue 2 / Vue 3 双版本兼容；
  • 但目前打出来的 dist 产物是基于 Vue 3 运行时 的，所以实际效果是：只支持 Vue 3。

• 未来可改进点

  • 调整打包配置，真正产出 Vue 2 + Vue 3 双版本；
  • 或者单独维护一个 Vue 2 版本的 e-signature 组件供老项目使用。

如果你希望兼容 Vue 2，可以告诉我：

• 你的 Vue 2 项目是 webpack 还是 vite；
• 是单页面应用（SPA）还是在老系统中局部嵌入组件。

我可以根据你的情况，设计一条最简单的接入方案（例如直接给你一份 Vue 2 组件源码，复制粘贴即可使用）。