Silver Formily Vant0.0.0

Appearance

Mobile Preview Open
Open mobile preview

Input ​

Input 负责值输入、原生 input / textarea 属性透传，以及和 FormItem 搭配时的输入增强能力。

使用约定

当前实现里真正承接 VanField UI 的是 FormItem。因此 clearable、showWordLimit、leftIcon 这类 Vant 输入增强属性，仍然建议写在 Input 上，再由内部自动桥接到外层 FormItem。

推荐写法 ​

  • :component="[Input, props]" / x-component-props：放输入值、占位符、清空能力、字数统计、图标等输入行为属性
  • :decorator="[FormItem, props]" / x-decorator-props：放标签、额外说明、反馈状态、布局对齐等装饰器属性
vue
<Field
  name="description"
  title="详细描述"
  :decorator="[FormItem]"
  :component="[
    Input.TextArea,
    {
      rows: 4,
      maxlength: 120,
      showWordLimit: true,
      clearable: true,
      placeholder: '请输入详细描述',
    },
  ]"
/>

基础输入 ​

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

const form = createForm({
  values: {
    username: '',
    email: '',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="username"
        title="用户名"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            placeholder: '请输入用户名',
          },
        ]"
      />
      <Field
        name="email"
        title="邮箱"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            type: 'email',
            placeholder: '请输入联系邮箱',
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

常见类型 ​

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

const form = createForm({
  values: {
    mobile: '',
    password: '',
    website: '',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="mobile"
        title="手机号"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            type: 'tel',
            placeholder: '请输入手机号',
          },
        ]"
      />
      <Field
        name="password"
        title="密码"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            type: 'password',
            placeholder: '请输入密码',
          },
        ]"
      />
      <Field
        name="website"
        title="个人主页"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            type: 'url',
            placeholder: 'https://example.com',
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

只读与禁用 ​

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

const form = createForm({
  values: {
    readonlyName: 'silver-formily',
    disabledValue: '当前不可编辑',
    alignValue: '这项内容右对齐展示',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="readonlyName"
        title="只读输入框"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            readonly: true,
          },
        ]"
      />
      <Field
        name="disabledValue"
        title="禁用输入框"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            disabled: true,
          },
        ]"
      />
      <Field
        name="alignValue"
        title="内容对齐"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            inputAlign: 'right',
            placeholder: '输入内容会右对齐',
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

图标与清空 ​

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

const form = createForm({
  values: {
    keyword: 'Formily',
    captcha: '',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="keyword"
        title="搜索"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            leftIcon: 'search',
            clearable: true,
            placeholder: '输入关键词后可以直接清空',
          },
        ]"
      />
      <Field
        name="captcha"
        title="验证码"
        :decorator="[FormItem]"
        :component="[
          Input,
          {
            rightIcon: 'question-o',
            placeholder: '点击右侧图标查看说明',
            onClickRightIcon: () => showToast('验证码示例仅用于展示交互能力'),
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

字数统计 ​

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

const form = createForm({
  values: {
    summary: '',
    remark: '已经支持字数统计和清空交互。',
  },
})
</script>

<template>
  <FormProvider :form="form">
    <div class="demo-panel">
      <Field
        name="summary"
        title="简介"
        :decorator="[FormItem]"
        :component="[
          Input.TextArea,
          {
            rows: 2,
            maxlength: 40,
            showWordLimit: true,
            placeholder: '请输入 40 字以内的简介',
          },
        ]"
      />
      <Field
        name="remark"
        title="备注"
        :decorator="[FormItem]"
        :component="[
          Input.TextArea,
          {
            rows: 3,
            maxlength: 80,
            showWordLimit: true,
            clearable: true,
            placeholder: '可以继续补充更多说明',
          },
        ]"
      />
    </div>
  </FormProvider>
</template>

API ​

使用约定 ​

  • Input 和 Input.TextArea 都会透传未单独列出的原生 input / textarea 属性与 DOM 事件
  • 在 Formily 场景里无需手动处理 modelValue / update:modelValue；值同步由字段内部驱动，业务侧请通过 field.value、form.values 等 Formily 方式获取
  • 标准写法推荐使用 readonly；如果沿用了 Formily 生态里更常见的 readOnly，当前封装也会兼容映射
  • clearable、showWordLimit、leftIcon、rightIcon 等增强属性在单独使用 Input 时不会渲染 VanField UI；和 FormItem 搭配时会自动桥接到外层 VanField

Input 基础属性 ​

属性名类型描述默认值
idstring原生输入框 id-
namestring原生输入框 name-
typestring输入类型；常见值包括 text、tel、url、number、password、search'text'
placeholderstring占位提示文案-
readonlyboolean只读状态；和 FormItem 搭配时会同步外层只读样式false
disabledboolean禁用状态；和 FormItem 搭配时会同步外层禁用样式false
autofocusboolean是否自动聚焦false
autocompletestring原生自动完成属性-
autocapitalizestring原生自动大写策略-
autocorrectstring原生自动纠错策略-
enterkeyhintenum移动端回车键提示文案-
inputmodeenum原生输入模式-
spellcheckboolean | null是否开启浏览器拼写检查null

Input 数值与格式化属性 ​

属性名类型描述默认值
maxlengthnumber | string最大字符数-
minnumber最小值，常用于数值类输入-
maxnumber最大值，常用于数值类输入-
formatterFunction输入格式化函数-
formatTriggerenum格式化触发时机'onChange'

Input 桥接属性 ​

这些属性来自官方 Field，在当前封装里推荐写在 Input 上，再由 FormItem 自动桥接到外层 VanField。

属性名类型描述默认值
clearableboolean和 FormItem 搭配时显示清空图标false
clearIconstring自定义清空图标'clear'
clearTriggerenum清空图标展示时机；和 FormItem 搭配且未显式传值时会默认补成 'always''focus'，桥接模式下自动补成 'always'
inputAlignenum输入内容对齐方式-
leftIconstring左侧图标名称或图片链接；和 FormItem 搭配时显示在外层 VanField-
rightIconstring右侧图标名称或图片链接；和 FormItem 搭配时显示在外层 VanField-
iconPrefixstring图标类名前缀-
showWordLimitboolean和 FormItem 搭配时显示字数统计false
onClearFunction清空按钮点击回调；需和 FormItem 搭配-
onClickInputFunction输入区域点击回调；需和 FormItem 搭配-
onClickLeftIconFunction左侧图标点击回调；需和 FormItem 搭配-
onClickRightIconFunction右侧图标点击回调；需和 FormItem 搭配-

Input.TextArea Attributes ​

Input.TextArea 继承 Input 的全部属性与事件，并额外补充下列配置：

属性名类型描述默认值
typeenum固定使用多行文本模式'textarea'
rowsnumber | string可见行数-
autosizeboolean | object是否自适应内容高度-

Input Events ​

事件名描述回调参数
focus获得焦点时触发Function
blur失去焦点时触发Function

参考 ​

输入增强属性的命名与默认值主要参考 Vant Field 官方文档（正式站）。