ruoyi-plus-uniapp

主题

Signature 签名 ​

介绍 ​

Signature 签名组件用于签名场景,基于 Canvas 实现。组件提供了基础签名、历史记录、撤销/恢复、笔锋效果等功能,适用于电子签名、手写板等业务场景。

核心特性:

  • Canvas 绑定 - 基于原生 Canvas 实现,性能优异
  • 笔锋效果 - 支持压感模式,模拟真实书写效果
  • 历史记录 - 支持撤销/恢复操作
  • 自定义样式 - 支持设置画笔颜色、宽度、背景色等
  • 图片导出 - 支持导出为图片文件

基本用法 ​

基础签名 ​

vue
<template>
  <wd-signature @confirm="handleConfirm" />
</template>

<script lang="ts" setup>
import type { SignatureResult } from '@/wd/components/wd-signature/wd-signature.vue'

const handleConfirm = (result: SignatureResult) => {
  if (result.success) {
    console.log('签名图片路径:', result.tempFilePath)
  }
}
</script>

自定义画笔 ​

通过 pen-color 和 line-width 设置画笔颜色和宽度。

vue
<template>
  <wd-signature pen-color="#1989fa" :line-width="4" />
</template>

自定义背景色 ​

通过 background-color 设置签名板背景色。

vue
<template>
  <wd-signature background-color="#f5f5f5" />
</template>

自定义尺寸 ​

通过 width 和 height 设置签名板尺寸。

vue
<template>
  <wd-signature width="100%" height="300rpx" />
</template>

历史记录 ​

设置 enable-history 开启历史记录功能,支持撤销和恢复。

vue
<template>
  <wd-signature enable-history />
</template>

笔锋效果 ​

设置 pressure 开启压感模式,模拟真实书写的笔锋效果。

vue
<template>
  <wd-signature pressure :min-width="2" :max-width="6" />
</template>

自定义按钮文字 ​

通过属性自定义各按钮的文字。

vue
<template>
  <wd-signature
    clear-text="重写"
    confirm-text="完成"
    revoke-text="撤回"
    restore-text="恢复"
    enable-history
  />
</template>

自定义底部按钮 ​

通过 footer 插槽自定义底部按钮区域。

vue
<template>
  <wd-signature>
    <template #footer="{ clear, confirm, revoke, restore, canUndo, canRedo }">
      <view class="custom-footer">
        <wd-button size="small" plain @click="revoke" :disabled="!canUndo">
          撤销
        </wd-button>
        <wd-button size="small" plain @click="restore" :disabled="!canRedo">
          恢复
        </wd-button>
        <wd-button size="small" plain @click="clear">清空</wd-button>
        <wd-button size="small" type="primary" @click="confirm">
          确认
        </wd-button>
      </view>
    </template>
  </wd-signature>
</template>

导出设置 ​

通过 file-type、quality、export-scale 设置导出图片的格式和质量。

vue
<template>
  <wd-signature
    file-type="jpg"
    :quality="0.8"
    :export-scale="2"
    @confirm="handleConfirm"
  />
</template>

<script lang="ts" setup>
const handleConfirm = (result) => {
  // 导出的图片分辨率为画布的2倍
  console.log('图片尺寸:', result.width, result.height)
}
</script>

禁用签名板 ​

设置 disabled 禁用签名功能。

vue
<template>
  <wd-signature disabled />
</template>

获取组件实例 ​

通过 ref 获取组件实例,调用组件方法。

vue
<template>
  <wd-signature ref="signatureRef" />
  <wd-button @click="handleClear">清空</wd-button>
  <wd-button @click="handleConfirm">确认</wd-button>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const signatureRef = ref()

const handleClear = () => {
  signatureRef.value?.clear()
}

const handleConfirm = () => {
  signatureRef.value?.confirm()
}
</script>

API ​

Props ​

参数说明类型默认值
pen-color签名笔颜色string#000
line-width签名笔宽度number3
background-color画板背景色string-
width画布宽度string | number-
height画布高度string | number-
disabled是否禁用签名板booleanfalse
disable-scroll是否禁用画布滚动booleantrue
file-type导出图片的类型stringpng
quality导出图片的质量number1
export-scale导出图片的缩放比例number1
enable-history是否开启历史记录booleanfalse
step撤回和恢复的步长number1
pressure是否启用压感模式(笔锋)booleanfalse
min-width压感模式下笔画最小宽度number2
max-width压感模式下笔画最大宽度number6
min-speed最小速度阈值number1.5
clear-text清空按钮文本string清空
confirm-text确认按钮文本string确认
revoke-text撤回按钮文本string撤回
restore-text恢复按钮文本string恢复
custom-class自定义根节点样式类string-
custom-style自定义根节点样式string-

Events ​

事件名说明回调参数
start开始绘制时触发event: TouchEvent
end结束绘制时触发event: TouchEvent
signing绘制过程中触发event: TouchEvent
confirm确认签名时触发result: SignatureResult
clear清空签名时触发-

Slots ​

名称说明参数
footer自定义底部按钮区域{ clear, confirm, revoke, restore, canUndo, canRedo, historyList, currentStep }

Methods ​

通过 ref 获取组件实例后可调用以下方法:

方法名说明参数返回值
init初始化签名板forceUpdate?: boolean-
clear清空签名--
confirm确认签名并导出图片--
revoke撤回上一步--
restore恢复上一步--

类型定义 ​

typescript
/**
 * 签名结果类型
 */
interface SignatureResult {
  /** 生成图片的临时路径 */
  tempFilePath: string
  /** 是否成功生成图片 */
  success: boolean
  /** 生成图片的宽度 */
  width: number
  /** 生成图片的高度 */
  height: number
}

主题定制 ​

组件提供了以下 CSS 变量用于主题定制:

变量名说明默认值
--wd-signature-bg签名板背景色#ffffff
--wd-signature-radius签名板圆角8rpx
--wd-signature-border签名板边框1px dashed #eee
--wd-signature-footer-margin-top底部按钮区域上边距16rpx
--wd-signature-button-margin-left按钮左边距16rpx

最佳实践 ​

1. 电子签名场景 ​

vue
<template>
  <view class="signature-container">
    <view class="signature-tip">请在下方区域签名</view>
    <wd-signature
      ref="signatureRef"
      height="400rpx"
      background-color="#fafafa"
      @confirm="handleConfirm"
    />
  </view>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const signatureRef = ref()

const handleConfirm = (result) => {
  if (result.success) {
    // 上传签名图片
    uni.uploadFile({
      url: '/api/upload',
      filePath: result.tempFilePath,
      name: 'signature',
      success: (res) => {
        console.log('签名上传成功')
      }
    })
  }
}
</script>

2. 带笔锋的手写板 ​

vue
<template>
  <wd-signature
    pressure
    :min-width="1"
    :max-width="8"
    pen-color="#333"
    enable-history
  />
</template>

常见问题 ​

1. 签名图片导出失败? ​

确保在调用 confirm 方法之前已经有签名内容。可以通过监听 end 事件来判断是否有签名。

2. 如何提高导出图片的清晰度? ​

设置 export-scale 属性,例如设置为 2 可以导出2倍分辨率的图片:

vue
<wd-signature :export-scale="2" />

3. 微信小程序中签名不清晰? ​

组件已自动处理设备像素比,如果仍有问题,可以尝试增大 line-width 属性值。

4. 如何实现签名预览? ​

通过 confirm 事件获取图片路径后,使用 wd-img 组件展示:

vue
<template>
  <wd-signature @confirm="handleConfirm" />
  <wd-img v-if="signatureUrl" :src="signatureUrl" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const signatureUrl = ref('')

const handleConfirm = (result) => {
  if (result.success) {
    signatureUrl.value = result.tempFilePath
  }
}
</script>
移动端预览