外观
Signature 签名组件
约 1488 字大约 5 分钟
2025-10-31
该组件可用于电子签名、手写签名等场景。支持多种画笔颜色、压感绘制、撤销重做、水印等功能。
基本使用
<template>
<view class="signature-container">
<un-signature
ref="signatureRef"
:penSize="penSize"
:backgroundColor="backgroundColor"
@confirm="onConfirm"
></un-signature>
</view>
</template>
<script setup>
import { ref } from 'vue'
const penSize = ref(5)
const backgroundColor = ref('#fff')
const signatureRef = ref<UnSignatureComponentPublicInstance | null>(null)
const onConfirm = (res) => {
console.log('签名完成', res)
// res 为签名图片的 base64 数据
}
</script>
<style lang="scss" scoped>
.signature-container {
width: 100%;
height: 300px;
border: 1px solid #d6d7d8;
border-radius: 8px;
}
</style>自定义画笔颜色
可以通过 penColor 属性设置画笔颜色,也可以通过 penColorList 提供颜色选择列表:
<template>
<view class="signature-container">
<un-signature
:penColor="penColor"
:penColorList="penColorList"
:showColorList="true"
></un-signature>
</view>
</template>
<script setup>
import { ref } from 'vue'
const penColor = ref('#FF1E10')
const penColorList = ref(['#4D4D4D', '#FF1E10', '#FFBE00', '#1A9BFF', '#1AAD19'])
</script>工具栏操作
组件内置了清空、撤销、完成等操作按钮:
<template>
<view class="signature-container">
<un-signature
ref="signatureRef"
:showToolbar="true"
:showClear="true"
:showUndo="true"
clearText="清空"
undoText="撤销"
confirmText="完成"
></un-signature>
</view>
</template>压感绘制
开启压感功能后,可以根据触摸压力调整线条粗细:
<template>
<view class="signature-container">
<un-signature
ref="signatureRef"
:openSmooth="true"
:minLineWidth="2"
:maxLineWidth="8"
></un-signature>
</view>
</template>水印功能
可以为签名添加水印,支持自定义水印文本、颜色、角度等:
<template>
<view class="signature-container">
<un-signature
:showWatermark="true"
:watermark="watermark"
></un-signature>
</view>
</template>
<script setup>
import { ref } from 'vue'
import type { UnWatermarkOption } from '@/uni_modules/uview-unix'
const watermark = ref<UnWatermarkOption>({
showOnSave: true,
text: '电子签名',
color: 'rgba(0, 0, 0, 0.1)',
})
</script>水印使用示例
1. 基础水印
watermark: {
text: '电子签名',
fontSize: 16,
rotate: -30
}2. 单个水印
watermark: {
text: '孙悟空',
fontSize: 50,
spacing: 120,
rotate: 0,
single: true
}3. 平铺水印
watermark: {
text: 'DRAFT',
color: 'rgba(0, 0, 255, 0.15)',
fontSize: 14,
rotate: 0,
spacing: 80,
single: false
}方法调用
可以通过 ref 调用组件的方法:
<template>
<view>
<un-signature ref="signatureRef"></un-signature>
<view class="button-container">
<un-button @click="clear">清空</un-button>
<un-button @click="undo">撤销</un-button>
<un-button @click="confirm">完成</un-button>
</view>
</view>
</template>
<script setup>
import { ref } from 'vue'
const signatureRef = ref<UnSignatureComponentPublicInstance | null>(null)
const clear = () => {
signatureRef.value?.clear()
}
const undo = () => {
signatureRef.value?.undo()
}
const confirm = () => {
signatureRef.value?.getImage().then(res => {
console.log('签名图片', res)
})
}
</script>自定义样式
可以通过 customStyle 和 toolbarStyle 自定义组件样式:
<template>
<view class="signature-container">
<un-signature
:style="customStyle"
:toolbarStyle="toolbarStyle"
></un-signature>
</view>
</template>
<script setup>
import { ref } from 'vue'
const customStyle = ref({
border: '2px solid #e4e7ed',
borderRadius: '8px'
})
const toolbarStyle = ref({
backgroundColor: '#f5f7fa',
padding: '10px'
})
</script>API
Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| title | 标题 | String | 请签名 |
| showTitle | 是否显示标题 | Boolean | true |
| showToolbar | 是否显示工具栏 | Boolean | true |
| showColorList | 是否显示颜色列表 | Boolean | true |
| showClear | 是否显示清空按钮 | Boolean | true |
| showUndo | 是否显示撤销按钮 | Boolean | true |
| showClose | 是否显示关闭按钮 | Boolean | true |
| closeText | 关闭按钮的文本 | String | 关闭 |
| clearText | 清空按钮的文本 | String | 清空 |
| undoText | 撤销按钮的文本 | String | 撤销 |
| confirmText | 完成按钮的文本 | String | 完成 |
| toolbarStyle | 工具栏对齐方式 | Object | {} |
| fixed | 是否固定标题栏和工具栏 | Boolean | false |
| minLineWidth | 线条最小宽度 | String | Number | 2 |
| maxLineWidth | 线条最大宽度 | String | Number | 6 |
| penColor | 画笔颜色 | String | #000000 |
| penColorList | 画笔颜色列表 | String[] | ['#000000', '#FF1E10', '#FFBE00', '#1A9BFF', '#1AAD19'] |
| penSize | 画笔大小 | String | Number | 2 |
| backgroundColor | 背景颜色 | String | #ffffff |
| type | canvas类型 | String | 2d |
| openSmooth | 是否开启压感 | Boolean | false |
| maxHistoryLength | 最大历史记录数 | String | Number | 20 |
| landscape | 是否横屏 | Boolean | false |
| disableScroll | 是否禁用滚动 | Boolean | true |
| disabled | 是否禁用 | Boolean | false |
| boundingBox | 只生成内容区域 | Boolean | false |
| showWatermark | 是否显示水印 | Boolean | false |
| watermark | 水印配置对象 | UnWatermarkOption | - |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| clear | 清空签名时触发 | Function |
| undo | 撤销操作时触发 | Function |
| confirm | 完成签名时触发 | Function |
Methods
| 方法名 | 说明 | 参数 |
|---|---|---|
| clear | 清空签名 | Function |
| undo | 撤销上一步操作 | Function |
| getImage | 获取签名图片 | Function |
Slots
| 名称 | 说明 |
|---|---|
| title | 自定义标题内容 |
| toolbar | 自定义工具栏内容 |
数据类型
/**
* 水印配置项类型
*/
type UnWatermarkOption = {
text: string; // 水印文本内容
fontSize?: string | number; // 字体大小
fontFamily?: string; // 字体-family
color?: string; // 字体颜色
spacing?: string | number; // 水印间距
bold?: boolean; // 是否加粗
rotate?: string | number; // 水印旋转角度
single?: boolean; // 是否为单个水印,默认false
showOnSave?: boolean; // 是否在保存时显示
}Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-signature-title-padding | 10px | 标题内边距 |
| $un-signature-toolbar-padding | 10px 10px 20px 10px | 工具栏内边距 |
| $un-signature-title-font-size | $text-base | 标题字体大小 |
| $un-signature-title-text-color | $text-color | 标题文本颜色 |
| $un-signature-title-bg-color | rgba(255, 255, 255, 0.8) | 标题背景颜色 |
| $un-signature-toolbar-bg-color | rgba(255, 255, 255, 0.8) | 工具栏背景颜色 |
| $un-signature-color-size | 26px | 颜色选择器大小 |
| $un-signature-color-border | 6px solid #fff | 颜色选择器边框 |
| $un-signature-color-box-shadow | 0 0 5px 0 rgba(0, 0, 0, 0.1) | 颜色选择器阴影 |
| $un-signature-color-margin | 0 3px | 颜色选择器间距 |
| $un-signature-toolbar-item-margin-right | 10px | 工具栏项右侧间距 |
| $un-signature-z-index | 9999 | 组件层级 |
| $un-signature-landscape-title-width | 42px | 横屏模式标题宽度 |
| $un-signature-landscape-title-text-width | 300px | 横屏模式标题文本宽度 |
| $un-signature-landscape-toolbar-padding | 10px | 横屏模式工具栏内边距 |
| $un-signature-landscape-toolbar-width | 56px | 横屏模式工具栏宽度 |
| $un-signature-landscape-toolbar-color-margin | 5px 0 | 横屏模式颜色选择器间距 |
| $un-signature-landscape-toolbar-left-margin-top | 15px | 横屏模式左侧工具栏顶部间距 |
| $un-signature-landscape-toolbar-right-margin-bottom | 15px | 横屏模式右侧工具栏底部间距 |
| $un-signature-landscape-toolbar-item-margin-left | -50px | 横屏模式工具栏项左侧间距 |
| $un-signature-landscape-toolbar-item-height | 90px | 横屏模式工具栏项高度 |
| $un-signature-landscape-toolbar-color-list-margin-bottom | 10px | 横屏模式颜色列表底部间距 |
| $un-signature-color-border-radius | 100px | 颜色选择器圆角 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
