FormItem
FormItem是当前 Vant 封装里的装饰器组件,负责承接VanField的展示、布局和反馈层能力。
提示
Vant 并没有单独的 FormItem 组件,官方是把“表单项壳层”和“文本输入”统一放进 Field 里。这里拆成 FormItem + Input,是为了继续保持 Formily 的 decorator + component 心智。
基础使用
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: {
phone: '13800138000',
remark: '',
},
})
</script>
<template>
<FormProvider :form="form">
<div class="demo-panel">
<Field
name="phone"
title="手机号"
required
:decorator="[
FormItem,
{
labelWidth: '5em',
extra: 'labelWidth、required 仍走表单项壳层,extra 属性会显示在下方说明区',
},
]"
:component="[
Input,
{
placeholder: '请输入手机号',
},
]"
/>
<Field
name="remark"
title="备注"
:decorator="[
FormItem,
{
labelAlign: 'top',
},
]"
:component="[
Input.TextArea,
{
rows: 2,
placeholder: '这里可以写一些补充信息',
},
]"
/>
</div>
</FormProvider>
</template>直接使用
vue
<script setup lang="ts">
import { FormItem, Input } from '@silver-formily/vant'
import { ref } from 'vue'
const value = ref('')
</script>
<template>
<div class="demo-panel">
<FormItem
label="用户名"
asterisk
feedback-status="error"
feedback-text="这里只是静态示例,用来观察反馈区和输入区的位置"
>
<Input
v-model="value"
placeholder="直接插进 FormItem 默认槽"
/>
</FormItem>
<FormItem
label="说明"
extra="extra 属性现在会单独显示在 FormItem 下方"
>
<Input
v-model="value"
placeholder="继续输入,观察壳层结构"
/>
</FormItem>
<FormItem label="原生 extra 插槽">
<template #extra>
<span class="slot-extra">这段内容仍然走 Vant 原生 extra 布局</span>
</template>
<Input
v-model="value"
placeholder="观察右侧 extra 插槽位置"
/>
</FormItem>
</div>
</template>边框与说明
vue
<script setup lang="ts">
import { FormItem, Input } from '@silver-formily/vant'
import { reactive } from 'vue'
const values = reactive({
name: 'silver-formily',
phone: '13800138000',
city: 'Hangzhou',
remark: '说明区会跟着边框一起形成完整的一项',
})
</script>
<template>
<div class="demo-panel">
<FormItem
label="名称"
border
extra="这是第一条,观察说明区和下一项之间的边框关系"
>
<Input
v-model="values.name"
placeholder="请输入名称"
/>
</FormItem>
<FormItem
label="手机"
border
>
<Input
v-model="values.phone"
placeholder="请输入手机号"
/>
</FormItem>
<FormItem
label="城市"
border
>
<Input
v-model="values.city"
placeholder="请输入城市"
/>
</FormItem>
<FormItem
label="备注"
extra="这是最后一条,观察底部说明区本身的边框收尾效果"
border
>
<Input
v-model="values.remark"
placeholder="请输入备注"
/>
</FormItem>
</div>
</template>API
使用约定
title会自动映射到labeldescription会自动映射到extraextra属性会作为表单项下方的独立说明区域渲染extra插槽仍然保持 Vant 原生VanField #extra的布局语义extra属性和extra插槽互不影响,可以同时存在field.required、field.validateStatus、field.selfErrors等字段状态会自动映射到外层VanFieldclearable、showWordLimit、leftIcon这类输入增强属性请写在Input上,由FormItem内部负责桥接tag、titleStyle、valueClass、clickable这类更偏布局和展示层的属性,建议写在FormItem上
FormItem 封装属性
| 属性名 | 类型 | 描述 | 默认值 |
|---|---|---|---|
label | string | number | VNode | 左侧标签内容;未传时优先读取 field.title | field.title |
extra | string | number | VNode | 额外说明内容;未传时优先读取 field.description | field.description |
feedbackStatus | enum | 手动覆盖反馈状态 | field.validateStatus |
feedbackText | string | number | VNode | 手动覆盖底部反馈文案 | 自动读取字段反馈 |
asterisk | boolean | 手动控制必填星号展示 | field.required && field.pattern !== 'readPretty' |
FormItem 展示与布局属性
| 属性名 | 类型 | 描述 | 默认值 |
|---|---|---|---|
tag | keyof HTMLElementTagNameMap | 根节点标签名 | 'div' |
required | boolean | enum | 是否显示必填态 | field.required |
colon | boolean | 是否在标签后显示冒号 | - |
size | enum | 表单项尺寸 | - |
border | boolean | 是否显示内边框 | true |
center | boolean | 是否让内容垂直居中 | false |
labelWidth | number | string | 左侧标签宽度 | - |
labelAlign | enum | 标签对齐方式 | - |
labelClass | string | string[] | object | 标签区域额外类名 | - |
titleClass | string | string[] | object | 标题区域额外类名 | - |
titleStyle | string | object | 标题区域样式 | - |
valueClass | string | string[] | object | 内容区域额外类名 | - |
error | boolean | 手动指定错误态;也会被 feedbackStatus 的推导结果覆盖 | 根据字段状态与反馈配置推导 |
errorMessage | string | 手动指定错误文案;也会被 feedbackText 的推导结果覆盖 | 根据字段状态与反馈配置推导 |
errorMessageAlign | enum | 底部错误文案对齐方式 | - |
clickable | boolean | null | 是否开启点击反馈 | 未传时跟随 isLink |
isLink | boolean | 是否展示右侧箭头并开启链接态样式 | false |
arrowDirection | enum | 右侧箭头方向,仅在 isLink 为 true 时有明显视觉效果 | - |
FormItem Slots
| 插槽名 | 描述 | 插槽参数 |
|---|---|---|
default | 默认内容,会被放进 VanField 的 #input 区域 | - |
input | 自定义输入区域,优先级高于默认插槽 | - |
label | 自定义标签区域 | - |
extra | 自定义额外说明区域 | - |
button | 自定义右侧按钮区域 | - |
left-icon | 自定义左侧图标区域 | - |
right-icon | 自定义右侧图标区域 | - |
error-message | 自定义底部反馈区域 | object |
FormItem.BaseItem
纯展示组件,保留和 FormItem 相同的视觉结构与插槽能力,但不会和 Formily Field 状态做自动桥接。适合只想复用 VanField 布局壳层、不需要接入字段状态的场景。
参考
属性命名、布局能力和默认值主要参考 Vant Field 官方文档(正式站)。