ProForm 配置式表单
基于 @qin-ui/pro-components-core 的 useForm Hook 与 Vant 组件封装的高级表单。它通过 Schema 驱动数据流,使用 path 和 component 配置每个表单项。
基础用法
<script setup lang="ts">
import { ProForm, useForm } from '@qin-ui/vant-pro';
type FormData = { name: string; age: number };
const form = useForm<FormData>({}, [
{
path: 'name',
label: '姓名',
component: 'field',
rules: [{ required: true, message: '请填写姓名' }],
},
{
path: 'age',
label: '年龄',
component: 'stepper',
},
]);
</script>
<template>
<ProForm :form="form" />
</template>API
useForm(initData?, initFields?, root?) 参数
| 参数 | 类型 | 说明 |
|---|---|---|
initData | DeepPartial<D> | 表单初始数据 |
initFields | Field<D>[] | 表单字段初始配置 |
root | boolean | 是否为根 form 实例(用于嵌套 form 场景),默认 true。也可作为唯一参数调用 useForm(root?) |
useForm支持两种调用方式:useForm(initData?, initFields?, root?)或useForm(root?)。
useForm 返回的实例对象 (form)
| 属性/方法 | 类型 | 说明 |
|---|---|---|
formData | Reactive<D> | 响应式表单数据对象,可直接读写 |
getFormData(path?) | (path?) => any | 读取字段值,不传 path 返回全部数据 |
setFormData(path, value) | - | 设置字段值,value 支持函数形式 (prev) => next;也可传对象批量覆盖整个表单 |
fields | Ref<Field<D>[]> | 响应式字段配置数组 |
getField(path, options?) | - | 获取字段配置,支持路径字符串或查找函数;options.all 返回所有匹配 |
setField(path, patch, options?) | - | 更新字段配置,默认合并模式;options.updateType: 'rewrite' 覆盖,options.all 批量更新 |
deleteField(path, options?) | - | 删除字段配置,options.all 批量删除 |
appendField(path, field, options?) | - | 在指定字段后追加,传 undefined 在末尾追加 |
prependField(path, field, options?) | - | 在指定字段前插入,传 undefined 在开头插入 |
getParentField(path, options?) | - | 获取字段父级,一级字段返回虚拟根容器 |
formRef | Ref<FormInstance | undefined> | 底层 Vant Form 实例的引用,可调用 validate()、resetValidation() 等方法 |
formPopup | FormPopup | 弹出层表单管理对象,提供 open(path, initialValue?, customProps?, fieldId?)、close()、resetProps()、updateProps(props)、visible、popupFieldPath、popupFieldValue、activeFieldId、props。其中 updateProps(props) 写入的弹层属性持久生效(此后每次打开沿用),open 的 customProps 仅对本次打开生效,resetProps() 恢复默认并清空单次覆盖;initialValue 与内联分支同为控件侧取值(已应用字段 valueFormatter.get) |
ProForm Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
form | Form<D> | - | useForm 返回的实例,可选,不传时自动创建根表单实例 |
字段配置(Field)
公共属性
| 属性 | 类型 | 说明 |
|---|---|---|
path | Path<D> | 字段标识,对应 formData 中的 key |
label | SlotComponentType | 字段标签,支持字符串、组件、VNode、函数等 |
component | 见下方组件表 | 使用的内置组件名或自定义组件 |
hidden | MaybeRef<boolean>(支持 boolean / Ref / ComputedRef) | 是否隐藏 |
disabled | WithRef<boolean>(支持 boolean / Ref / ComputedRef) | 是否禁用 |
rules | FormItemRule[] | Vant 表单校验规则 |
slots | Slots | 字段插槽配置 |
fields | Fields<D> | 嵌套子字段配置 |
fieldStyle | StyleValue | 外层 van-field 样式属性 |
fieldClass | ClassValue | 外层 van-field 样式类名 |
fieldContainer | Component | 嵌套字段容器包裹组件 |
componentStyle | StyleValue | 内部组件样式 |
componentClass | ClassValue | 内部组件类名 |
componentContainer | Component | 组件外层包裹容器 |
valueFormatter | ValueFormatter | 值转换函数(支持 get/set 形式);双参声明才注入旧值快照 |
displayFormatter | DisplayFormatter | 针对 Popup 展现形式的组件,将选中值转化为输入框展示文字 |
modelProp | string | v-model 绑定属性名 |
popup | boolean | Partial<PopupProps> | 是否通过 Popup 弹窗展示该组件 |
extraProps | Record<string, any> | 额外的自定义属性,不会被当作组件参数传递 |
响应式支持:除了
component、fields、slots、modelProp等属性之外,很多属性均支持Ref或ComputedRef以实现动态表单。
校验触发时机是 Form 级配置(vant 默认
onBlur):Form 级经<ProForm validateTrigger="onChange">或componentVars['pro-form'].validateTrigger下发;字段级写在rules的trigger(如{ required: true, trigger: 'onChange' })。字段配置顶层写validateTrigger不生效,且会作为 DOM 属性落到van-field根节点。
内置组件(component 取值)
支持了 Vant 的绝大部分数据录入组件:
field(文本框)switch(开关)stepper(步进器)rate(评分)slider(滑块)uploader(上传)checkbox-group(复选框组)radio-group(单选框组)picker(选择器)date-picker(日期选择器)time-picker(时间选择器)cascader(级联选择器)area(省市区选择器)signature(签名)button(按钮)custom(完全自定义)
插槽
以字段 path 命名的插槽优先于 component 渲染,作用域为字段当前的绑定值与合并后的控件属性。
| 作用域参数 | 说明 |
|---|---|
modelValue | 字段当前值(已应用 valueFormatter.get) |
onUpdate:modelValue | 回写字段值;校验时机由 Form 级 validateTrigger 决定(vant 默认 onBlur) |
disabled | 合并后的禁用状态(字段 > 表单 > Provider) |
path | 字段标识 |
| 其余键 | 合并后的控件属性(Provider 注入的 clearable / placeholder 等) |
作用域对象可直接 v-bind 给控件,控件自身的 v-model 事件即完成回写:
<template>
<ProForm :form="form" @submit="handleSubmit">
<template #name="scoped">
<van-field v-bind="scoped" />
</template>
</ProForm>
</template>插槽替换的是整行控件,字段配置为
component: 'field'(或不配置component)时使用本写法。
scoped同时携带path等上下文键,v-bind会一并下发;只读展示场景可直接取modelValue渲染。键名随字段
modelProp变化(默认modelValue/onUpdate:modelValue);Provider 注入的控件属性按字段的字符串component解析,仅用插槽而未配置component时仅字段级属性生效。