Wot Design Uni1.8.0

Appearance

Signature 签名 1.6.0 ​

用于签名场景，基于 Canvas 实现的签名组件。提供了基础签名、历史记录、笔锋效果等功能。

提醒

如果遇到导出图片不清晰，可以将 exportScale 设置为 2 以上。

基础用法 ​

基础的电子签名功能。签名完成后会使用预览组件显示签名图片。

html
<wd-signature @confirm="confirm" @clear="clear" :export-scale="2" background-color="#ffffff" />
typescript
const img = ref<Partial<SignatureResult>>({})

function confirm(result: SignatureResult) {
  if (result.success) {
    uni.previewImage({
      urls: [result.tempFilePath]
    })
  }
}

function clear() {
  img.value = {}
}

历史记录 ​

通过 enable-history 开启历史记录功能，可以进行撤销和恢复操作。

html
<wd-signature enable-history background-color="#f5f5f5" />

笔锋模式 ​

通过 pressure 开启笔锋模式，模拟真实书写效果。笔锋模式下笔画粗细会随书写速度变化。

基础笔锋效果 ​

html
<wd-signature pressure :height="300" />

使用建议

  1. 笔锋模式推荐参数范围：
    • min-width: 1-2
    • max-width: 4-6
    • min-speed: 1-2
  2. max-width 和 min-width 的差值建议保持在 3-5 之间
  3. min-speed 值越小，压感越灵敏，建议根据实际书写习惯调整
  4. 对于签名场景，建议将画布高度设置在 300-400 之间

自定义笔锋参数 ​

可以通过以下属性精确控制笔锋效果：

  • min-width: 最小笔画宽度，快速书写时的线条粗细
  • max-width: 最大笔画宽度，慢速书写时的线条粗细
  • min-speed: 速度阈值，用于调整压感灵敏度
html
<wd-signature 
  pressure 
  :height="300" 
  :min-width="1" 
  :max-width="6" 
  :min-speed="1.5"
  background-color="#f5f5f5"
/>
<view class="tip-text">快速书写产生细线条，慢速书写产生粗线条</view>

笔锋模式 + 历史记录 ​

笔锋模式可以与历史记录功能结合使用，支持对带有笔锋效果的线条进行撤销和恢复操作。

html
<wd-signature 
  pressure 
  enable-history 
  :height="300" 
  :min-width="1" 
  :max-width="6"
  background-color="#f5f5f5" 
/>
<view class="tip-text">结合历史记录，支持笔锋效果的撤销与恢复</view>

自定义功能 ​

自定义按钮 ​

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

html
<wd-signature :disabled="disabled" enable-history :step="3">
  <template #footer="{ clear, confirm, currentStep, restore, revoke, historyList }">
    <wd-button block @click="changeDisabled" v-if="disabled">开始签名</wd-button>
    <block v-if="!disabled">
      <wd-button size="small" plain @click="revoke" :disabled="currentStep <= 0">撤回</wd-button>
      <wd-button size="small" plain @click="restore" :disabled="currentStep >= historyList.length">恢复</wd-button>
      <wd-button size="small" plain @click="clear">清除</wd-button>
      <wd-button size="small" @click="confirm">确定</wd-button>
    </block>
  </template>
</wd-signature>
typescript
const disabled = ref(true)

function changeDisabled() {
  disabled.value = false
}

自定义画笔 ​

可以自定义画笔的颜色和宽度。

html
<wd-signature pen-color="#0083ff" :line-width="4" />

弹窗中使用 ​

结合 wd-popup 组件在弹窗中使用签名板。建议使用 after-enter 事件调用签名板的 init 方法以确保正确初始化。

html
<wd-button type="primary" @click="show = true">打开签名板</wd-button>

<wd-popup 
  v-model="show" 
  closable
  safe-area-inset-bottom
  position="bottom"
  custom-style="padding: 48px 20px 20px 20px; border-radius: 16px 16px 0 0;"
  @after-enter="signatureRef?.init()"
>
  <wd-signature 
    ref="signatureRef"
    :height="300"
    enable-history
    pressure
    background-color="#f5f5f5"
    @confirm="handleConfirm" 
  />
</wd-popup>

<wd-img v-if="img.tempFilePath" mode="widthFix" width="100%" :src="img.tempFilePath" />
typescript
import { ref } from 'vue'
import type { SignatureInstance, SignatureResult } from '@/uni_modules/wot-design-uni/components/wd-signature/types'

const show = ref(false)
const img = ref<Partial<SignatureResult>>({})
const signatureRef = ref<SignatureInstance>()

function handleConfirm(result: SignatureResult) {
  show.value = false
  if (result.success) {
    uni.previewImage({
      urls: [result.tempFilePath]
    })
  }
}
scss
.popup-footer {
  margin-top: 16px;
  display: flex;
  justify-content: flex-end;
  gap: 12px;
}

提示

弹窗中使用签名板时，建议：

  1. 开启 closable 显示关闭按钮
  2. 设置 safe-area-inset-bottom 以适配底部安全区
  3. 使用 custom-style 调整弹窗内边距，为关闭按钮留出空间
  4. 在弹窗的 after-enter 事件中调用签名板的 init 方法，确保正确初始化

横屏签名页面 ​

可以通过配置页面的 pageOrientation 来实现横屏签名页面。

json
// pages.json
{
  "pages": [
    {
      "path": "pages/signature-landscape/Index",
      "style": {
        "navigationBarTitleText": "横屏签名",
        "pageOrientation": "landscape"
      }
    }
  ]
}
html
<template>
  <view class="landscape-signature">
    <wd-signature
      ref="signatureRef"
      :height="height"
      :width="width"
      pressure
      enable-history
      background-color="#f5f5f5"
      @confirm="handleConfirm"
    />
  </view>
</template>

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

const height = ref(0)
const width = ref(0)

onMounted(() => {
  const { windowWidth, windowHeight } = uni.getSystemInfoSync()
  // 减去页面边距
  height.value = windowWidth - 40
  width.value = windowHeight - 40
})
</script>

<style>
.landscape-signature {
  padding: 20px;
  height: 100vh;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #fff;
}
</style>

提示

横屏签名页面的建议：

  1. 使用 pageOrientation: "landscape" 强制横屏显示
  2. 动态计算画布尺寸以适配不同设备
  3. 注意横屏时 windowWidth 和 windowHeight 的对调
  4. 建议开启笔锋模式提供更好的签名体验

横屏签名 ​

支持以下两种横屏签名实现方案：

1. 通用横屏方案 (推荐) ​

通过自定义布局和按钮旋转实现横屏效果，适用于所有平台。

html
<template>
  <view class="landscape-signature">
    <wd-signature
      v-if="inited"
      :height="height"
      :width="width"
      enable-history
      pressure
      background-color="#f5f5f5"
      @confirm="handleConfirm"
    >
      <template #footer="{ clear, confirm, restore, revoke, canUndo, canRedo }">
        <view class="custom-actions">
          <view class="button-group">
            <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>
        </view>
      </template>
    </wd-signature>
  </view>
</template>
ts
import { pause } from '@/uni_modules/wot-design-uni/components/common/util'

const height = ref(0)
const width = ref(0)
const inited = ref(false)

onMounted(() => {
  const { windowWidth, windowHeight } = uni.getSystemInfoSync()
  width.value = windowWidth - 48
  height.value = windowHeight - 48
  
  pause(100).then(() => {
    inited.value = true
  })
})
scss
.landscape-signature {
  height: 100vh;
  // #ifdef H5
  height: calc(100vh - 44px);
  // #endif
  background: #fff;
  position: relative;
  padding: 24px 0;
  padding-left: 48px;
  box-sizing: border-box;

  .custom-actions {
    position: fixed;
    left: 0;
    top: 50%;
    width: 48px;
    transform: translateY(-50%) rotate(90deg);
    transform-origin: center;
    z-index: 10;

    .button-group {
      display: flex;
      flex-direction: row;
      gap: 12px;
      white-space: nowrap;
      width: max-content;
      transform: translateX(-50%);
    }
  }
}

实现说明

通用横屏方案特点：

  1. 使用 fixed 布局配合旋转实现左侧垂直按钮栏
  2. 通过 footer 插槽自定义操作按钮
  3. 使用 transform 实现按钮的旋转效果
  4. 适用于所有平台,实现方式一致
  5. 建议使用 inited 变量配合延迟加载避免画布初始化问题

2. 原生横屏方案 (仅微信小程序) ​

微信小程序提供了原生的横屏支持，使用时需要注意区分平台:

json
{
  "path": "pages/signature/landscape",
  "style": {
    "navigationBarTitleText": "横屏签名",
    // #ifdef MP-WEIXIN
    "pageOrientation": "landscape"
    // #endif
  }
}
html
<template>
  <view class="landscape-signature">
    <wd-signature
      v-if="inited"
      ref="signatureRef"
      :height="height" 
      :width="width"
      enable-history
      pressure
      background-color="#f5f5f5"
      @confirm="handleConfirm"
    >
    </wd-signature>
  </view>
</template>
ts
import { pause } from '@/uni_modules/wot-design-uni/components/common/util'

const height = ref(0)
const width = ref(0)
const inited = ref(false)

onMounted(() => {
  const { windowWidth, windowHeight } = uni.getSystemInfoSync()
  width.value = windowWidth
  height.value = windowHeight - 60 // 预留底部按钮空间

  pause(100).then(() => {
    inited.value = true
  })
})
scss
.landscape-signature {
  height: 100vh;
  background: #fff;
  position: relative;
  box-sizing: border-box;

  // #ifdef MP-WEIXIN
  padding: 0;
  display: flex;
  flex-direction: column;

  .weixin-actions {
    padding: 12px;
    background-color: #f8f8f8;
    
    .button-group {
      display: flex;
      justify-content: center;
      gap: 12px;
    }
  }
  // #endif
}

注意事项

  1. pageOrientation 配置仅在微信小程序端生效
  2. 使用条件编译区分不同平台的布局结构
  3. 微信小程序页面会自动旋转，按钮布局不需要特殊处理
  4. 预留底部按钮空间时需要考虑横屏布局
  5. 其他平台请使用通用横屏方案

Attributes ​

参数说明类型默认值最低版本
pen-color签名笔颜色string#000000-
line-width签名笔宽度number3-
height画布的高度number200-
width画布的宽度number300-
clear-text清空按钮的文本string--
confirm-text确认按钮的文本string--
file-type导出图片类型stringpng-
quality导出图片质量(0-1)number1-
export-scale导出图片的缩放比例number1-
disabled是否禁用签名板booleanfalse-
background-color画板的背景色string--
disable-scroll是否禁用画布滚动booleantrue-
enable-history是否开启历史记录booleanfalse1.8.0
step历史记录步长number11.8.0
pressure是否启用笔锋模式booleanfalse1.8.0
min-width笔锋模式最小宽度number21.8.0
max-width笔锋模式最大宽度number61.8.0
min-speed笔锋模式速度阈值number1.51.8.0

Events ​

事件名称说明参数最低版本
start开始签名时触发event: TouchEvent-
end结束签名时触发event: TouchEvent-
signing签名过程中触发event: TouchEvent-
confirm确认签名时触发result: SignatureResult-
clear清空签名时触发--

Methods ​

方法名说明参数最低版本
init初始化签名板forceUpdate?: boolean-
confirm确认签名--
clear清空签名--
restore恢复上一步--
revoke撤销上一步--

Slots ​

名称说明参数最低版本
footer自定义底部按钮{ clear, confirm, restore, revoke, currentStep, historyList }-

源代码 ​

文档
 • 组件

Released under the MIT License.

Copyright © 2023-present weisheng

Released under the MIT License.

Copyright © 2023-present weisheng