Signature

Signature 是对 Vant 签名组件的 Formily 适配。相比官方组件，这层封装额外补上了 modelValue 字段值、现有签名回显，以及 readPretty 阅读态图片预览。

使用建议

适合电子签名、签收确认、免责确认这类需要直接把签名图片存进表单字段的场景。字段值默认保存为 dataURL 字符串。

基础使用

点击“确认”后，当前签名会以 dataURL 形式写回字段值。

vue

<script setup lang="ts">
import { createForm } from '@formily/core'
import { Form, FormButtonGroup, FormItem, Signature, Submit } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'
import { showDemoResult } from '../shared'

const form = createForm()

async function showSignatureResult(values: Record<string, string>) {
  const signature = values.signature

  await showDemoResult({
    signature: signature
      ? `${signature.slice(0, 48)}... (${signature.length} chars)`
      : '',
  })
}
</script>

<template>
  <Form :form="form">
    <Field
      name="signature"
      title="请签名"
      description="请在下方签名后点击确认"
      :decorator="[FormItem, {
        labelAlign: 'top',
      }]"
      :component="[Signature]"
    />

    <FormButtonGroup>
      <Submit :on-submit="showSignatureResult">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

自定义样式

官方 penColor、lineWidth、backgroundColor 和按钮文案都会继续透传。

vue

<script setup lang="ts">
import { createForm } from '@formily/core'
import { Form, FormItem, Signature } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'

const form = createForm()
</script>

<template>
  <Form :form="form">
    <Field
      name="signature"
      title="品牌签名"
      description="使用深色笔迹和浅色底板"
      :decorator="[FormItem, {
        labelAlign: 'top',
      }]"
      :component="[Signature, {
        penColor: '#0f172a',
        lineWidth: 4,
        backgroundColor: '#fff7ed',
        confirmButtonText: '保存签名',
        clearButtonText: '重新签名',
      }]"
    />
  </Form>
</template>

只读回显

当字段本身已经有签名图片时，组件会自动把 modelValue 回绘到画布里；在 readonly / disabled 场景下也能稳定展示。

vue

<script setup lang="ts">
import { createForm } from '@formily/core'
import { Form, FormItem, Signature } from '@silver-formily/vant'
import { Field } from '@silver-formily/vue'

const readonlySignature = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(`
  <svg xmlns="http://www.w3.org/2000/svg" width="240" height="120" viewBox="0 0 240 120">
    <rect width="240" height="120" fill="#ffffff" />
    <path
      d="M20 76 C48 20, 82 26, 110 70 S162 112, 220 42"
      fill="none"
      stroke="#111827"
      stroke-width="6"
      stroke-linecap="round"
      stroke-linejoin="round"
    />
  </svg>
`)}`

const form = createForm({
  values: {
    signature: readonlySignature,
  },
})
</script>

<template>
  <Form :form="form">
    <Field
      name="signature"
      title="已存档签名"
      description="只读状态下会回显已有签名"
      :decorator="[FormItem, {
        labelAlign: 'top',
      }]"
      :component="[Signature, {
        readonly: true,
      }]"
    />
  </Form>
</template>

获取实例

如果需要主动调用 submit / clear / resize，推荐通过 Formily 字段实例的 invoke 获取组件引用，而不是直接拿 Vue ref：

const signatureRef = fieldRef.value?.invoke('getSignatureRef')

signatureRef?.value?.submit()
signatureRef?.value?.clear()
signatureRef?.value?.resize()

API

使用约定

Formily 场景统一使用 modelValue 作为字段值，推荐保存 data:image/... 格式的 dataURL 字符串
点击组件底部“确认”按钮时，会触发 update:modelValue，并把当前签名图片写回字段
点击“清空”按钮时，会同步把字段值清空为 ''
当外部字段值变化时，组件会自动把新的签名图片重新绘制到画布上，避免编辑态只能看到空白板
readPretty 模式下会自动切换到 PreviewText.Signature，非空时展示签名图片，空值显示占位符
tips 和 tips 插槽保持 Vant 原生语义，只会在当前环境不支持 canvas 时作为降级提示展示；如果只是想补充签名说明，建议写在 FormItem.extra / description 这类外层文案里

扩展属性

属性名	类型	描述	默认值
`modelValue`	`string`	当前签名图片，通常为 `dataURL` 字符串	`-`
`readonly`	`boolean`	只读状态，会保留画布展示但阻止编辑	`-`
`disabled`	`boolean`	禁用状态	`-`

官方透传属性

以下属性会直接透传给 Vant Signature：

属性名	类型	描述	默认值
`tips`	`string`	当前环境不支持 `canvas` 时的降级提示文案	官方默认值
`type`	`string`	导出图片类型	`png`
`penColor`	`string`	画笔颜色	`#000`
`lineWidth`	`number`	线宽	`3`
`backgroundColor`	`string`	画布背景色	`''`
`clearButtonText`	`string`	清空按钮文案	官方默认值
`confirmButtonText`	`string`	确认按钮文案	官方默认值

Events

事件名	描述	回调参数
`update:modelValue`	点击确认或清空后同步字段值	`Function`
`submit`	点击确认按钮时触发	`Function`
`clear`	点击清空按钮时触发	`Function`
`start`	开始签名时触发	`Function`
`signing`	签名过程中持续触发	`Function`
`end`	结束签名时触发	`Function`

Slots

插槽名	描述	插槽参数
`tips`	自定义降级提示内容，仅在不支持 `canvas` 时展示	`-`

参考

基础交互和样式能力参考 Vant Signature 官方文档（正式站）。

Signature ​

基础使用 ​

自定义样式 ​

只读回显 ​

获取实例 ​

API ​

使用约定 ​

扩展属性 ​

官方透传属性 ​

Events ​

Slots ​

参考 ​