Signature 签名 - Vant 4

✍️ Signature 签名

🎯 介绍

用于签名场景的组件，基于 Canvas 实现，支持手写签名、电子签名等场景。请升级 vant 到 >= 4.3.0 版本来使用该组件。

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Signature } from 'vant';

const app = createApp();
app.use(Signature);

🎯 代码演示

✍️ 基础用法

当点击确认按钮时，组件会触发 submit 事件，事件的第一个参数为 data，包含以下字段：

• image：签名对应的图片，为 base64 字符串格式。若签名为空，则返回空字符串。
• canvas：Canvas 元素。

<template>
  <van-signature @submit="onSubmit" @clear="onClear" />
  <img v-if="image" :src="image" />
</template>

<script>
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const image = ref('');
    const onSubmit = (data) => {
      image.value = data.image;
    };
    const onClear = () => showToast('签名已清空');
    return { image, onSubmit, onClear };
  },
};
</script>

🎨 自定义颜色

通过 pen-color 来自定义笔触颜色，让签名更具个性化。

<template>
  <van-signature pen-color="#ff0000" @submit="onSubmit" />
</template>

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

export default {
  setup() {
    const onSubmit = (data) => {
      console.log('签名数据:', data);
    };
    return { onSubmit };
  },
};
</script>

📏 自定义线宽

通过 line-width 来自定义线条宽度，控制签名的粗细效果。

<template>
  <van-signature :line-width="5" @submit="onSubmit" />
</template>

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

export default {
  setup() {
    const onSubmit = (data) => {
      console.log('签名数据:', data);
    };
    return { onSubmit };
  },
};
</script>

🎨 自定义背景颜色

通过 background-color 来自定义背景颜色，营造不同的签名氛围。

<template>
  <van-signature background-color="#f0f0f0" @submit="onSubmit" />
</template>

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

export default {
  setup() {
    const onSubmit = (data) => {
      console.log('签名数据:', data);
    };
    return { onSubmit };
  },
};
</script>

📋 API

🎛️ Props

参数	说明	类型	默认值
type	📸 导出图片类型	string	png
pen-color	🎨 笔触颜色，默认黑色	string	#000
line-width	📏 线条宽度	number	3
background-color	🎨 背景颜色	string	-
tips	💡 当不支持 Canvas 的时候出现的提示文案	string	-
clear-button-text	🗑️ 清除按钮文案	string	清空
confirm-button-text	✅ 确认按钮文案	string	确认

🎪 Events

事件名	说明	回调参数
start	🚀 开始签名时触发	-
end	🏁 结束签名时触发	-
signing	✍️ 签名过程中触发	event: TouchEvent
submit	✅ 点击确定按钮时触发	data: { image: string; canvas: HTMLCanvasElement }
clear	🗑️ 点击取消按钮时触发	-

🎭 Slots

名称	说明	参数
tips	💡 自定义提示文案	-

🔧 方法

通过 ref 可以获取到 Signature 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
resize v4.7.3	🔄 外层元素大小或组件显示状态变化时，可以调用此方法来触发重绘	-	-
clear v4.8.6	🗑️ 可调用此方法来清除签名	-	-
submit v4.8.6	✅ 触发 submit 事件，与点击确认按钮的效果等价	-	-

📘 类型定义

组件导出以下类型定义，方便在 TypeScript 项目中使用：

import type { SignatureProps, SignatureInstance } from 'vant';

SignatureInstance 是组件实例的类型，用法如下：

import { ref } from 'vue';
import type { SignatureInstance } from 'vant';

const signatureRef = ref<SignatureInstance>();
signatureRef.value?.resize();

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-signature-padding	var(--van-padding-xs)	📦 签名组件内边距
--van-signature-content-height	200px	📏 签名区域高度
--van-signature-content-background	var(--van-background-2)	🎨 签名区域背景色
--van-signature-content-border	1px dotted #dadada	🖼️ 签名区域边框样式

📚 相关文档

🎨 绘图组件

📝 表单组件

• Field - 输入框组件，用于文本输入
• Form - 表单组件，用于数据收集和验证

🎭 弹层组件

• Popup - 弹出层组件，可用于签名弹窗
• Dialog - 对话框组件，用于确认操作

🔧 工具组件

• ConfigProvider - 全局配置组件，用于主题定制
• Toast - 轻提示组件，用于操作反馈