Skip to content

ProForm 配置式表单 ​

基于 @qin-ui/pro-components-core 的 useForm Hook 与 Vant 组件封装的高级表单。它通过 Schema 驱动数据流,使用 path 和 component 配置每个表单项。

基础用法 ​

vue
<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?) 参数 ​

参数类型说明
initDataDeepPartial<D>表单初始数据
initFieldsField<D>[]表单字段初始配置
rootboolean是否为根 form 实例(用于嵌套 form 场景),默认 true。也可作为唯一参数调用 useForm(root?)

useForm 支持两种调用方式:useForm(initData?, initFields?, root?) 或 useForm(root?)。

useForm 返回的实例对象 (form) ​

属性/方法类型说明
formDataReactive<D>响应式表单数据对象,可直接读写
getFormData(path?)(path?) => any读取字段值,不传 path 返回全部数据
setFormData(path, value)-设置字段值,value 支持函数形式 (prev) => next;也可传对象批量覆盖整个表单
fieldsRef<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?)-获取字段父级,一级字段返回虚拟根容器
formRefRef<FormInstance | undefined>底层 Vant Form 实例的引用,可调用 validate()、resetValidation() 等方法
formPopupFormPopup弹出层表单管理对象,提供 open(path, initialValue?, customProps?, fieldId?)、close()、resetProps()、updateProps(props)、visible、popupFieldPath、popupFieldValue、activeFieldId、props。其中 updateProps(props) 写入的弹层属性持久生效(此后每次打开沿用),open 的 customProps 仅对本次打开生效,resetProps() 恢复默认并清空单次覆盖;initialValue 与内联分支同为控件侧取值(已应用字段 valueFormatter.get)

ProForm Props ​

属性类型默认值说明
formForm<D>-useForm 返回的实例,可选,不传时自动创建根表单实例

字段配置(Field) ​

公共属性 ​

属性类型说明
pathPath<D>字段标识,对应 formData 中的 key
labelSlotComponentType字段标签,支持字符串、组件、VNode、函数等
component见下方组件表使用的内置组件名或自定义组件
hiddenMaybeRef<boolean>(支持 boolean / Ref / ComputedRef)是否隐藏
disabledWithRef<boolean>(支持 boolean / Ref / ComputedRef)是否禁用
rulesFormItemRule[]Vant 表单校验规则
slotsSlots字段插槽配置
fieldsFields<D>嵌套子字段配置
fieldStyleStyleValue外层 van-field 样式属性
fieldClassClassValue外层 van-field 样式类名
fieldContainerComponent嵌套字段容器包裹组件
componentStyleStyleValue内部组件样式
componentClassClassValue内部组件类名
componentContainerComponent组件外层包裹容器
valueFormatterValueFormatter值转换函数(支持 get/set 形式);双参声明才注入旧值快照
displayFormatterDisplayFormatter针对 Popup 展现形式的组件,将选中值转化为输入框展示文字
modelPropstringv-model 绑定属性名
popupboolean | Partial<PopupProps>是否通过 Popup 弹窗展示该组件
extraPropsRecord<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 事件即完成回写:

vue
<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 时仅字段级属性生效。