xtf-signature

组件说明

xtf-signature 是Canvas 手写签名组件，适用于合同、签收和审批；支持笔迹回填、撤销、回放与图片导出。 核心能力以当前 xtf-signature.vue 源码为准。

---

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

<template>
  <xtf-signature ref="sign" :height="300" @change="onEvent" />
</template>

<script>
export default {
  data() {
    return { value: '' }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

<template>
  <xtf-signature
    :height="260"
    stroke-style="#2563eb"
    :line-width="8"
    :sign-limit="2"
    @limit-exceed="onEvent"
  />
</template>

<script>
export default {
  data() {
    return { value: '' }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

<template>
  <view>
    <xtf-signature ref="sign" trim-whitespace :export-scale="2" @save="onEvent" /><xtf-button
      label="导出"
      @click="$refs.sign.getImageData().then(onEvent)"
  /></view>
</template>

<script>
export default {
  data() {
    return { value: '' }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
width	[String, Number]	'100%'	控制组件的 width 行为。	按业务需要设置。
height	[String, Number]	360	控制组件的 height 行为。	按业务需要设置。
lineWidth	[String, Number]	6	控制组件的 lineWidth 行为。	按业务需要设置。
initialStrokes	Array	函数返回值	控制组件的 initialStrokes 行为。	按业务需要设置。
minDistance	[String, Number]	2	控制组件的 minDistance 行为。	按业务需要设置。
historyLimit	[String, Number]	0	控制组件的 historyLimit 行为。	按业务需要设置。
strokeStyle	String	''	控制组件的 strokeStyle 行为。	按业务需要设置。
backgroundColor	String	''	控制组件的 backgroundColor 行为。	按业务需要设置。
placeholder	String	''	控制组件的 placeholder 行为。	按业务需要设置。
radius	[String, Number]	28	控制组件的 radius 行为。	按业务需要设置。
disabled	Boolean	false	控制组件的 disabled 行为。	按业务需要设置。
readonly	Boolean	false	控制组件的 readonly 行为。	按业务需要设置。
previewImage	String	''	控制组件的 previewImage 行为。	按业务需要设置。
previewMode	String	'aspectFit'	控制组件的 previewMode 行为。	按业务需要设置。
forceBackground	Boolean	true	控制组件的 forceBackground 行为。	按业务需要设置。
trimWhitespace	Boolean	false	控制组件的 trimWhitespace 行为。	按业务需要设置。
exportPadding	[String, Number]	24	控制组件的 exportPadding 行为。	按业务需要设置。
exportScale	[String, Number]	1	控制组件的 exportScale 行为。	按业务需要设置。
status	String	'draft'	控制组件的 status 行为。	按业务需要设置。
signLimit	[String, Number]	0	控制组件的 signLimit 行为。	按业务需要设置。
signerInfo	Object	函数返回值	控制组件的 signerInfo 行为。	按业务需要设置。
auditInfo	Object	函数返回值	控制组件的 auditInfo 行为。	按业务需要设置。
signArea	Object	函数返回值	控制组件的 signArea 行为。	按业务需要设置。
customClass	String	''	控制组件的 customClass 行为。	按业务需要设置。
customStyle	[String, Object]	''	控制组件的 customStyle 行为。	按业务需要设置。

数据项结构

字段	类型	默认值	说明
id/key	String | Number	index	稳定键；列表、轮播和瀑布流项目建议提供。
title/label/name	String	''	展示名称，具体读取字段见组件对应 prop。
disabled	Boolean	false	禁用可交互项目。

---

事件

事件名称	触发时机	回调参数	参数说明
update:strokes	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('update:strokes', ...) 为准。
status-change	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('status-change', ...) 为准。
blocked	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('blocked', ...) 为准。
limit-exceed	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('limit-exceed', ...) 为准。
start	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('start', ...) 为准。
change	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('change', ...) 为准。
end	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('end', ...) 为准。
clear	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('clear', ...) 为准。
undo	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('undo', ...) 为准。
replay-start	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('replay-start', ...) 为准。
replay-end	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('replay-end', ...) 为准。
save	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('save', ...) 为准。

事件使用示例

<template>
  <xtf-signature @update:strokes="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

---

方法

clear()、reset(strokes)、undo()、isEmpty()、replay(speed)、getImageData(options)、setStatus(status)。

使用示例：

this.$refs.sign.clear()

---

主题说明

• var(--xtf-card-border) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-shadow-soft) 参与组件的颜色、背景、边框或动效呈现。
• 视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。