更新记录

1.0.0（2026-09-01） 下载此版本

1. 新增 fg-sign-pad 签名组件，支持弹窗（popup）/ 内嵌（inline）两种模式
2. 基于 Canvas 2D（type="2d"）实现，兼容 App（app-vue）、H5、微信/支付宝/百度/字节/QQ/快手等小程序平台
3. 支持画笔颜色、粗细、画板背景、圆角等配置
4. 支持撤销上一笔、清空重签、导出图片（base64 / 临时文件路径）
5. 支持 v-model 受控弹窗与事件回调（confirm / cancel / change 等）

平台兼容性

uni-app(4.87)

其他

fg-sign-pad 签名组件

组件名：fg-sign-pad

基于 Canvas 2D（type="2d"）的手写签名组件，适用于合同签名、文件签名、审批签字、电子签名等场景。

• 支持 弹窗（popup） 与 内嵌（inline） 两种使用模式
• 支持画笔颜色、画笔粗细、画板背景、圆角等个性化配置
• 支持 撤销上一笔、清空重签、导出图片（base64 / 临时文件路径，可直接用于 uni.uploadFile 上传）
• 双击无需配置，easycom 自动注册，引入插件后直接在页面使用 <fg-sign-pad> 标签即可

平台兼容性

说明：组件使用 uni.createSelectorQuery().fields({ node: true }) 获取 Canvas 2D 节点，这是 uni-app 跨端统一的标准画布方案，各端基础库需满足上表要求。若初始化失败会通过 error 事件抛出并在控制台提示。

快速开始

插件放入 uni_modules 目录后（本项目已内置），页面可直接使用，无需 import：

模式一：弹窗模式（推荐，合同/文件签名常用）

<template>
    <view class="page">
        <!-- 页面展示签名缩略图 / 状态 -->
        <image v-if="signature" :src="signature.base64" mode="widthFix" style="width: 300px;"></image>
        <view v-else class="tip">尚未签名</view>

        <!-- 点击虚线入口 → 弹出签名面板 -->
        <fg-sign-pad mode="popup" @confirm="onConfirm" @cancel="onCancel" />
    </view>
</template>

<script>
export default {
    data() {
        return {
            signature: null
        }
    },
    methods: {
        onConfirm(res) {
            // res = { base64, tempFilePath, fileType, width, height }
            this.signature = res
            // 上传到服务器
            uni.uploadFile({
                url: 'https://your-api.com/sign',
                filePath: res.tempFilePath, // 有临时文件路径优先用它上传
                name: 'file',
                success: () => uni.showToast({ title: '签名已提交', icon: 'success' })
            })
        },
        onCancel() {
            console.log('用户取消签名')
        }
    }
}
</script>

模式二：内嵌模式（签名板直接显示在页面中）

<template>
    <view>
        <fg-sign-pad ref="sign" mode="inline" :height="240" />
        <button type="primary" @tap="submit">提交签名</button>
    </view>
</template>

<script>
export default {
    methods: {
        submit() {
            this.$refs.sign.exportSignature().then(res => {
                console.log(res.base64, res.tempFilePath)
            })
        }
    }
}
</script>

Vue 3（组合式 API）用法

<template>
    <fg-sign-pad ref="signRef" mode="inline" @confirm="onConfirm" />
</template>

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

const signRef = ref(null)

function onConfirm(res) {
    console.log('签名结果：', res.base64)
}

function doExport() {
    signRef.value.exportSignature().then(res => {
        // ...
    })
}
</script>

受控弹窗（v-model）

<template>
    <view>
        <button @tap="showSign = true">打开签名</button>
        <fg-sign-pad v-model="showSign" mode="popup" @confirm="onConfirm" />
    </view>
</template>

<script>
export default {
    data() {
        return { showSign: false }
    },
    methods: {
        onConfirm(res) {
            this.showSign = false
            // 处理 res
        }
    }
}
</script>

Props

事件

confirm 回调参数说明：

• base64：图片 dataURL 格式，可直接用于 <image :src> 预览或转 FormData 上传
• tempFilePath：本地临时文件路径，可用于 uni.uploadFile 直接上传
• 各端差异：H5 端 base64 稳定可用；小程序/App 端 tempFilePath 稳定可用，base64 由临时文件读取转换（个别平台读取失败时为空串，此时请使用 tempFilePath 上传）

方法（通过 ref 调用）

常见问题

1. 控制台报错"未获取到 canvas 节点"？

• 微信小程序请检查基础库版本 >= 2.9.0（manifest.json → mp-weixin → 基础库最低版本）
• App 端请确认使用 app-vue 页面（nvue 不支持），HBuilderX 版本 >= 3.x
• 插件放入 uni_modules 后请刷新 HBuilderX 项目

2. 报错"canvasToTempFilePath:fail Cannot read property 'width' of undefined"？ 微信小程序在自定义组件内调用 canvasToTempFilePath 时必须传入组件实例作为第二参数，组件内部已处理（uni.canvasToTempFilePath(options, this)）。另一个常见原因是 Vue3 下 canvas 节点被 reactive 用 Proxy 包装后传给原生 API 会失败——组件已将 canvas 节点与 ctx 存放在实例非响应式属性（this._canvas / this._ctx）上。若仍出现该错误，请停止运行后重新编译运行（清理 unpackage/dist 下对应平台的旧编译产物），确保源码与编译产物一致。

3. H5 端（PC 浏览器）无法签写？ 组件已支持鼠标事件（mousedown/mousemove/mouseup），PC 浏览器可直接按住鼠标签名；触摸设备自动走 touch 事件，二者互不干扰。

4. 为什么弹窗打开时画板偶尔空白？ 画板初始化依赖弹窗内容渲染完成，组件已做 nextTick 延迟 + 失败自动重试（3 次）。若页面在弹窗出现的同时有大量渲染任务，可稍作等待或升级基础库。

5. 签名图片模糊怎么办？ 组件已按设备 pixelRatio 放大画布分辨率（dpr 适配），导出尺寸为物理像素，无需额外处理。

6. 导出图片为什么带白底？ bgColor 默认 #FFFFFF，导出时背景会一并绘制。如需透明底 PNG，将 bgColor 设置为 transparent 即可。

更新日志

详见 changelog.md