Silver Formily Vant1.0.1

Appearance

Mobile Preview Open
Open mobile preview

Signature ​

Signature 是对 Vant 签名组件的 Formily 适配。相比官方组件，这层封装会把“签字编辑”和“签名预览”拆成两个状态：编辑时展示画板，确认后切换为图片预览。

使用建议

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

注意

为了简化使用，官方组件中的各种事件均不再暴露。

基础使用 ​

点击“确认”后，当前签名会以 dataURL 形式写回字段值，并切换成图片预览；点击“清空”后会回到签字面板。

vue
<script setup lang="ts">
import { createForm } from '@silver-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 @submit="showSignatureResult">
        查看结果
      </Submit>
    </FormButtonGroup>
  </Form>
</template>

自定义样式 ​

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

vue
<script setup lang="ts">
import { createForm } from '@silver-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: '#e11d48',
        lineWidth: 4,
        backgroundColor: '#fff7ed',
        confirmButtonText: '保存签名',
        clearButtonText: '重新签名',
      }]"
    />
  </Form>
</template>

禁用回显 ​

当字段已经有签名图片且处于 disabled 状态时，组件会直接显示图片预览，不再渲染签字画板。

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

const disabledSignature = `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: disabledSignature,
  },
})
</script>

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

禁用态 ​

disabled 只保留“不可编辑”的语义。无论字段是否已有值，组件都不会再显示可交互的签字画板：有值时显示图片预览，无值时显示空占位态。

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

const archivedSignature = `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="M24 74 C56 18, 92 22, 120 68 S176 110, 218 40"
      fill="none"
      stroke="#0f172a"
      stroke-width="6"
      stroke-linecap="round"
      stroke-linejoin="round"
    />
  </svg>
`)}`

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

<template>
  <Form :form="form">
    <Field
      name="emptyDisabledSignature"
      title="禁用且无值"
      description="直接展示空占位态，不再渲染签字画板。"
      :decorator="[FormItem, {
        labelAlign: 'top',
      }]"
      :component="[Signature, {
        disabled: true,
      }]"
    />

    <Field
      name="archivedSignature"
      title="禁用但已有值"
      description="会直接进入图片预览态。"
      :decorator="[FormItem, {
        labelAlign: 'top',
      }]"
      :component="[Signature, {
        disabled: true,
      }]"
    />
  </Form>
</template>

获取实例 ​

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

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

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

API ​

扩展属性 ​

属性名类型描述默认值
modelValuestring当前签名图片，通常为 dataURL 字符串-
disabledboolean禁用状态-

属性 ​

组件的其他属性参考 Vant Signature 官方文档。

Events ​

官方文档中的各种事件不再暴露。

事件名描述回调参数
update:modelValue点击确认或清空后同步字段值Function

Slots ​

同官方文档